How can I implicitly organize literate code with org-mode? - emacs

Question

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...

Answer 1

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.

Answer 2

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!