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

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

Irreligious

I'm sorry but the question is not clear to me. Could you provide a (less minimal) example of what you do, and what you'd like to do instead? – Erny

Would :noweb-ref (orgmode.org/manual/noweb_002dref.html#noweb_002dref) help? It uses property inheritance to propagate the name of the noweb block. – Crescendo

@AlexVorobiev That's done the trick! Can you post it as an answer so that it can be accepted? – Irreligious

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.

Crescendo

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!

Employee