I am on a literate program using org-babel. My source is structured like so,
-imports
-utility fns
-game structure
- detailed explanations
This is the normal structure of the code, what I would like to do is move explanations of the utility fns to the end so it does not show up first in the generated pdf file. Now this can be done with noweb extension, but the problem is when you have lots of little functions for each one I have to add a src_block with a unique name scroll down the file and add a reference to that in the file which is really annoying. Is there a way to name all the src_blocks in a section? say all code in this section goes into block A.
You can give multiple chunks the same name. For example, I generate my .emacs file with org-tangle, and at the top of the org file, I have a master template that looks something like this:
#+begin_src emacs-lisp :tangle "/path/to/.emacs" :comments both :noweb tangle
<<generated-file-warning>
<<includes>>
<<definitions>>
<<settings>>
<<generated-file-warning>
#+end_src
Underneath that, I have my outline with source blocks like so:
* extensions
** yasnippet
#+name: early-includes
#+begin_src emacs-lisp
(require 'yasnippet)
(yas/initialize)
#+end_src
#+name: settings
#+begin_src emacs-lisp
(yas/load/directory "/path/to/my/snippets")
#+end_src
Note: for older versions of org-mode, you may need to use #+srcname: instead of #+name:
You can also create a property called noweb-ref, which applies the same name to all source blocks in a sub-tree.
Related
I want to write a Literate Program with org-mode. Let's say I have the following function:
fn do_stuff()
{
// 200 lines of code go here.
}
I would write something like that in org-mode:
#+BEGIN_SRC rust :tangle /some/path
fn do_stuff()
{
#+END_SRC
// Many more blocks of `BEGIN_SRC` go here to exlpain 200 lines of code mentioned above.
// They will have formatting, and prose between them, and headings with different nesting levels.
// The whole shebang in short.
#+BEGIN_SRC rust :tangle /some/path
}
#+END_SRC
Now, here is the question. I hope I will explain it well, it's kinda hard to put in words.
What do I do with the first and last #+BEGIN_SRC blocks shown above?
How do I style the function declaration with org-mode and/or Literate Programming?
It seems kind of out of place with all the “formatting, prose, headings” of the 200 lines of code mentioned above.
I need ideas please :-)
Thanks in advance.
I would use noweb to tangle the full code without necessarily presenting it all in order. That is, I would do something like this:
The core code is
#+name: code1
#+begin_src rust :noweb yes :tangle no
...
#+end_src
More code etc. and then, at the end:
#+BEGIN_SRC rust :tangle /some/path
fn do_stuff()
{
<<code1>>
}
#+END_SRC
You may need :noweb yes on the full code block as well.
I have a bunch of elisp and other code with some notes i wanted to reformat to be more organized, and i found that having to type
#+BEGIN_SRC emacs-lisp ... #+END_SRC
all the time around what i want, is taking a bit longer than expected...
So what i wanted to do instead is to wrap/or put the selected content (with C-space) and put it in a template source code block for org-mode (in my case it's mostly elisp code, but i plan to use it for other things maybe)
How could i do this in emacs or in elisp?
There is a new templating mechanism in recent Org mode (>= 9.0 IIRC) that allows you tor wrap a region in a block: after selecting the region in the usual manner, you say C-c C-, s. You still have to type the emacs-lisp part though. That's the disadvantage. The advantage is that it is general enough to allow you to wrap a region in any kind of block. In your case, I think the disadvantage outweighs the advantage, so I would go with the wrap-region method in the other answer, but this one is good to know as well.
You can try wrap-region. It will allow you to define what type of string you want to wrap around a selection.
Put this in your init.el and evaluate it.
(wrap-region-global-mode t)
(wrap-region-add-wrapper "#+BEGIN_SRC emacs-lisp\n" "#+END_SRC" "#" 'org-mode)
Then, while you are editing your org files, you can select a block of text and type #, which will wrap it with your string. You can change the # to another character that will do the wrapping.
There is a feature in org-mode to do exactly that. It's like a snippet of some sort where you enter <eland hit TAB, the < char is here to say we're gonna use a template and the el part tells which template to use. But of course, you have to configure it first.
For that, you can just add this to an org-mode file or to your init.el file :
#+begin_src emacs-lisp
;; This is needed as of Org 9.2
(require 'org-tempo)
(add-to-list `org-structure-template-alist `("sh" . "src shell"))
(add-to-list `org-structure-template-alist `("el" . "src emacs-lisp"))
(add-to-list `org-structure-template-alist `("py" . "src python"))
#+end_src
There a bunch of way to use this, it's actually more useful than just use it as a template, you can go check the documentation here.
It is often the case that I want to have :results silent for all the code blocks in an Org-mode document. Do simplify my block headers, I define this in my Org-mode document:
#+PROPERTY: header-args :results silent
That works properly: all the codeblocks uses the :results silent option in the blocks' header.
However, if I specify :results output in one of the code block, it will still be silent. I would have expected that it would overwrite the global setting, but it doesn't seem so.
Am I right by saying that or is there something I am missing to get this behavior?
Here is an example of what I would like to do:
#+PROPERTY: header-args :results silent
...
#+BEGIN_SRC clojure
;; this one is silent
(def foo "bar)
#+END_SRC
...
#+BEGIN_SRC clojure :results output
;; this one is being outputted
(def foo "bar)
#+END_SRC
This seems to be a bug, present even in the most up-to-date version of org-mode. I've reported it on the org-mode mailing list.
EDIT: Charles Berry pointed out on the ML that this is not a bug. The opposite of "silent" is "replace", so the second source block should read:
#+BEGIN_SRC elisp :results output replace
;; this one is being outputted
(princ "foo")
#+END_SRC
See http://thread.gmane.org/gmane.emacs.orgmode/108001/focus=108008
and the :results section in the manual http://orgmode.org/org.html#results
Note that you get to pick one value for every section (collection, type, format, handling) - if you don't pick a value for a section, a default value is picked. In the above, there was no explicit value for "handling", so the default value from the property still controlled.
I'm developing a Stack Exchange mode for Emacs and I'm trying to use literate programming (with org-mode) to organize the project.
I'm finding myself repeating a lot of information.
I'm taking a (possibly over-) structured approach to the document.
Say I have a heading Questions; under that heading exist subheadings Read and Write,
and I have a top-level of
;; some-package.el starts here
<<read methods>>
<<write methods>>
;; some-package.el ends here
How can I alter the properties of the Read and Write headings such that all source code blocks inside, unless otherwise specified, will be placed into their respective noweb tanglings?
Here is what I do currently:
* TODO Stack Mode (Entry Point): =stack-mode=
Stack mode is /the/ major mode. What do I mean by this? Stack mode
is the entry point of the whole package. There is no other way to
obtain the full, original functionality of the package without first
running =M-x stack-mode=. Stack Mode is the only mode available
interactively. It is a dispatcher that decides, based on user
preferences, how the whole system shall behave. It provides the basic
framework upon which the rest of the package is built, and makes sure
all tools are available.
#+name: build-stack-mode
#+begin_src emacs-lisp :tangle elisp/stack.el
;; stack.el starts here
(add-to-list 'load-path "~/github/vermiculus/stack-mode")
<<stack-require-dependencies>>
<<stack-setup-customization>>
<<stack-setup-keymap>>
<<stack-setup-api>>
<<stack-load-children>>
(provide 'stack)
; stack.el ends here
#+end_src
Thus, there are a few packages that it itself requires.
JSON (JavaScript Object Notation) is the standard by which we
communicate with Stack Exchange itself. The details of this
communication has [[id:DC2032C5-BC11-47E2-8DDB-34467C2BC479][already been discussed]] so I will not repeat myself
here. The JSON package provides many utilities for manipulating JSON
snippets within Emacs Lisp, and is required for the operation of this
package. =json.el= is included with Emacs 24+ (and can easily be
obtained from the ELPA if missing).
#+name: stack-require-dependencies
#+begin_src emacs-lisp
(require 'json)
#+end_src
This package also requires =request.el=, a package designed to
simplify making HTTP requests. =request.el= was written by [[http://stackoverflow.com/users/727827][SX#tkf]] and
is maintained and documented on [[http://tkf.github.com/emacs-request/manual.html][GitHub]]. The package is also available
for automatic install via MELPA.
#+name: stack-require-dependencies
#+begin_src emacs-lisp
(require 'request)
#+end_src
#+name: stack-require-dependencies
#+begin_src emacs-lisp
(require 'stack-api)
#+end_src
Simply put, =defgroup= defines a customization group for the graphical
interface within Emacs. Since it pulls all of the customizable
settings together and how to customize them, it is also useful as a
'word bank' of sorts for customizing the package manually. Every
customizable variable in the entire package is listed here.
#+name: stack-setup-customization
#+begin_src emacs-lisp
(defgroup stack-exchange
nil
"Stack Exchange mode."
:group 'environment)
#+end_src
Every mode needs a hook, so we here define one. This hook is run
/after/ stack-mode is finished loading (when called interactively or
from Emacs Lisp).
#+name: stack-setup-customization
#+begin_src emacs-lisp
(defvar stack-mode-hook nil)
#+end_src
In addition to a hook, most if not all major modes define their own
key-map. Stack mode as a whole is no exception, but remembering the
nature of =stack-mode= as a dispatcher, a key-map seems out of place
here. As such, the official key-map for =stack-mode= defines all keys
to be =nil= except those that are necessary for the smooth use of
Emacs as an operating system. Such necessary keystrokes include
=C-g=, =M-x=, and others.
#+name: stack-setup-keymap
#+begin_src emacs-lisp
(defvar stack-mode-map
(let ((map (make-sparse-keymap)))
map)
"Keymap for Stack Exchange major mode. This keymap is not
used.")
#+end_src
...
Here is what I'd like to do:
(Ctrl+F for ** and look at the property drawer.)
* TODO Stack Mode (Entry Point): =stack-mode=
Stack mode is /the/ major mode. What do I mean by this? Stack mode
is the entry point of the whole package. There is no other way to
obtain the full, original functionality of the package without first
running =M-x stack-mode=. Stack Mode is the only mode available
interactively. It is a dispatcher that decides, based on user
preferences, how the whole system shall behave. It provides the basic
framework upon which the rest of the package is built, and makes sure
all tools are available.
#+name: build-stack-mode
#+begin_src emacs-lisp :tangle elisp/stack.el
;; stack.el starts here
(add-to-list 'load-path "~/github/vermiculus/stack-mode")
<<stack-require-dependencies>>
<<stack-setup-customization>>
<<stack-setup-keymap>>
<<stack-setup-api>>
<<stack-load-children>>
(provide 'stack)
; stack.el ends here
#+end_src
** Require Dependencies
:PROPERTIES:
:noweb-key: stack-require-dependencies
:END:
Thus, there are a few packages that it itself requires.
JSON (JavaScript Object Notation) is the standard by which we
communicate with Stack Exchange itself. The details of this
communication has [[id:DC2032C5-BC11-47E2-8DDB-34467C2BC479][already been discussed]] so I will not repeat myself
here. The JSON package provides many utilities for manipulating JSON
snippets within Emacs Lisp, and is required for the operation of this
package. =json.el= is included with Emacs 24+ (and can easily be
obtained from the ELPA if missing).
#+begin_src emacs-lisp
(require 'json)
#+end_src
This package also requires =request.el=, a package designed to
simplify making HTTP requests. =request.el= was written by [[http://stackoverflow.com/users/727827][SX#tkf]] and
is maintained and documented on [[http://tkf.github.com/emacs-request/manual.html][GitHub]]. The package is also available
for automatic install via MELPA.
#+begin_src emacs-lisp
(require 'request)
#+end_src
#+begin_src emacs-lisp
(require 'stack-api)
#+end_src
** Customization
:PROPERTIES:
:noweb-key: stack-setup-customization
:END:
Simply put, =defgroup= defines a customization group for the graphical
interface within Emacs. Since it pulls all of the customizable
settings together and how to customize them, it is also useful as a
'word bank' of sorts for customizing the package manually. Every
customizable variable in the entire package is listed here.
#+begin_src emacs-lisp
(defgroup stack-exchange
nil
"Stack Exchange mode."
:group 'environment)
#+end_src
Every mode needs a hook, so we here define one. This hook is run
/after/ stack-mode is finished loading (when called interactively or
from Emacs Lisp).
#+begin_src emacs-lisp
(defvar stack-mode-hook nil)
#+end_src
** Keymap
:PROPERTIES:
:noweb-key: stack-setup-keymap
:END:
In addition to a hook, most if not all major modes define their own
key-map. Stack mode as a whole is no exception, but remembering the
nature of =stack-mode= as a dispatcher, a key-map seems out of place
here. As such, the official key-map for =stack-mode= defines all keys
to be =nil= except those that are necessary for the smooth use of
Emacs as an operating system. Such necessary keystrokes include
=C-g=, =M-x=, and others.
#+begin_src emacs-lisp
(defvar stack-mode-map
(let ((map (make-sparse-keymap)))
map)
"Keymap for Stack Exchange major mode. This keymap is not
used.")
#+end_src
** Load Children...
The :noweb-ref header (http://orgmode.org/manual/noweb_002dref.html#noweb_002dref) helps propagate the noweb reference names to sub-trees using property inheritance.
Although you found the answer you need, I wanted to point out that
your approach is still quite structured and therefore does not take
full advantage of the power of literate programming. In the famous
wc example, you
can see that definitions and global variables are interspersed
throughout the text. It means that you can spend more time organising
your ideas in a structure which makes more sense to humans than
computers.
Based on your approach, it seems like you are grouping your noweb
blocks into sections based on how they will appear in the tangled
file. That may make sense to you, but there is another way you can do
it. You can, for example, organise your file thematically and group
all of the related code under those subheadings but use the noweb
blocks to group them together in the correct places in the tangled
file.
For example, there are usually a variety of dependencies and the
reason for including them will depend on the particular method of
feature of your programme. In your example, you don't provide enough
for me to give a concrete example, but let's say that you have the
following features or parts:
* Stack Mode
** customisation
** get from stack exchange
** edit post
** send back to stack exchange
I'm not sure if these are relevant or not, but here's the idea. Some
of those features will require certain dependencies. So for example,
you may have something like this:
* Stack Mode (Entry Point): =stack-mode=
Stack mode is /the/ major mode. What do I mean by this? Stack mode
is the entry point of the whole package. There is no other way to
obtain the full, original functionality of the package without first
running =M-x stack-mode=. Stack Mode is the only mode available
interactively. It is a dispatcher that decides, based on user
preferences, how the whole system shall behave. It provides the basic
framework upon which the rest of the package is built, and makes sure
all tools are available.
#+NAME: build-stack-mode
#+HEADER: :noweb tangle
#+HEADER: :comments both
#+HEADER: :tangle elisp/stack.el
#+BEGIN_SRC emacs-lisp
(add-to-list 'load-path "~/github/vermiculus/stack-mode")
<<stack-require-dependencies>>
<<stack-definitions>>
<<stack-initialisation>>
<<stack-customisaton>>
<<stack-functions>>
(provide 'stack)
#+END_SRC
** customisation
*** definitions
:PROPERTIES:
:noweb-ref: stack-definitions
:END:
Simply put, =defgroup= defines a customization group for the graphical
interface within Emacs. Since it pulls all of the customizable
settings together and how to customize them, it is also useful as a
'word bank' of sorts for customizing the package manually. Every
customizable variable in the entire package is listed here.
#+BEGIN_SRC emacs-lisp
(defgroup stack-exchange
nil
"Stack Exchange mode."
:group 'environment)
#+END_SRC
Every mode needs a hook, so we here define one. This hook is run
/after/ stack-mode is finished loading (when called interactively or
from Emacs Lisp).
#+BEGIN_SRC emacs-lisp
(defvar stack-mode-hook nil)
#+END_SRC
*** functions
Whatever is required here
#+NAME: stack-functions
#+BEGIN_SRC emacs-lisp
#+END_SRC
** setup
*** Keymap
In addition to a hook, most if not all major modes define their own
key-map. Stack mode as a whole is no exception, but remembering the
nature of =stack-mode= as a dispatcher, a key-map seems out of place
here. As such, the official key-map for =stack-mode= defines all keys
to be =nil= except those that are necessary for the smooth use of
Emacs as an operating system. Such necessary keystrokes include
=C-g=, =M-x=, and others.
#+NAME: stack-definitions
#+BEGIN_SRC emacs-lisp
(defvar stack-mode-map
(let ((map (make-sparse-keymap)))
map)
"Keymap for Stack Exchange major mode. This keymap is not
used.")
#+END_SRC
** get from stack exchange
*** get post
**** dependencies
:PROPERTIES:
:noweb-ref: stack-require-dependencies
:END:
JSON (JavaScript Object Notation) is the standard by which we
communicate with Stack Exchange itself. The details of this
communication has [[id:DC2032C5-BC11-47E2-8DDB-34467C2BC479][already been discussed]] so I will not repeat myself
here. The JSON package provides many utilities for manipulating JSON
snippets within Emacs Lisp, and is required for the operation of this
package. =json.el= is included with Emacs 24+ (and can easily be
obtained from the ELPA if missing).
#+BEGIN_SRC emacs-lisp
(require 'json)
#+END_SRC
This package also requires =request.el=, a package designed to
simplify making HTTP requests. =request.el= was written by [[http://stackoverflow.com/users/727827][SX#tkf]] and
is maintained and documented on [[http://tkf.github.com/emacs-request/manual.html][GitHub]]. The package is also available
for automatic install via MELPA.
#+BEGIN_SRC emacs-lisp
(require 'request)
#+END_SRC
**** functions
get the actual post
#+NAME: stack-functions
#+BEGIN_SRC emacs-lisp
#+END_SRC
*** parse post
**** dependencies
JSON (JavaScript Object Notation) is the standard by which we
communicate with Stack Exchange itself. The details of this
communication has [[id:DC2032C5-BC11-47E2-8DDB-34467C2BC479][already been discussed]] so I will not repeat myself
here. The JSON package provides many utilities for manipulating JSON
snippets within Emacs Lisp, and is required for the operation of this
package. =json.el= is included with Emacs 24+ (and can easily be
obtained from the ELPA if missing).
#+NAME: stack-require-dependencies
#+BEGIN_SRC emacs-lisp
(require 'json)
#+END_SRC
**** functions
*** display post
** edit post
** send back to stack exchange
*** dependencies
#+NAME: stack-require-dependencies
#+BEGIN_SRC emacs-lisp
(require 'stack-api)
#+END_SRC
*** functions
#+NAME: stack-functions
#+BEGIN_SRC emacs-lisp
(send-back-function)
#+END_SRC
This is just an example, of course, and I don't know how to programme
in lisp, but I just wanted to demonstrate to you and anyone else that
might read this, that you don't have to group your ideas in a way that
makes sense to a computer. In fact, the whole point of literate
programming is to organise things in a manner which make sense to humans. So it might make sense to be explicit sometimes rather than contorting your thought process to match a computer's.
Good luck!
I want to publish a project in Emacs org-mode, which contains several .html files.
There are some python code examples in them that I wanna highlight.
But htmlize.el won't do that for me.
Strangely, when exporting single .html file (using C-c C-e h), the code examples are highlighted .
So how could I get htmlize.el work for project publishing?
In your org-publish-project-alist, set the htmlized-source property to non-nil:
(setq org-publish-project-alist
'(("my-project"
:base-directory ...
:htmlized-source t
...
)))
See the Publishing action section of the Org-mode manual.
You have to put your code inside #+BEGIN_SRC and #+END_SRC . For example
* My python code
#+BEGIN_SRC python
def foo():
if bar == 1:
bar = 2
else:
bar = 3
#+END_SRC
using htmlize.el to highlight your code in orgfile, just add codes listed here to your .emacs file:
(require 'htmlize)
Notes: please make sure htmlize.el in your load-path