c++emacsorg-modeorg-babelnoweb

Preserving content of source blocks when exporting literate program to HTML with ReadTheOrg

Minimal example

I wrote a program in org-mode using literate programming technique with :noweb extension(?). Typical piece of code looks like this:

* Section

In order to do foo with bar, we define a function ~do_foo~, which initializes object of a class ~BarParser~ with a value of parameter of the type ~bar_t~.

#+name: section_function_blockname
#+begin_src cpp
void do_foo
( bar_t bar
, <<additional_parameter_to_do_foo>>
) {
  BarParser barParser(bar);

  <<section_function_do_fooBody>>
} 
#+end_src

The function will require additional parameter for the purposes of the /FizzBazz/ module. We will discuss them in a [[*Decoding FizzBazz messages][later_section]].

Entire content of the program is stored in a single file, which at the top has #+SETUP: theme-readtheorg.setup. The setup file is not the problem, because the HTML generates correctly, only with not the content I want.

Problem

To generate the code, I use (org-babel-tangle). This produces all the files I'd expect for all the blocks with :tangle parameter. The files have the content I expect them to have and code compiles and runs the way it should.

To generate the documentation I'd like to publish along the code, I use (org-html-export-to-html). What I expected to happen was that either:

  1. the <<tags>> will get substituted with their expected value, which wouldn't be ideal but at least acceptable, or
  2. the <<tags>> will be left untouched the way they are presented,when editing the org-file with Emacs.

However the output to (org-html-export-to-html) is quite different and unexpected - all the <<tags>> are replaced with a newline character. This leaves me with all the code blocks having incorrect content that cannot be understood without either looking at the generated code or original org-file which completely defeats the purpose of the documentation being in the separate file. I cannot force everyone I work with to switch to Emacs to let them browse the documentation!

Question

As stated above, the problem is with noweb <> being procesed by some call inside (org-html-export-to-html). The question I have regarding this issue is:

How can I force (org-html-export-to-html) to leave the contents of source blocks as they are, without stripping away the noweb <<tags>>?

Solution

  • IIUC, you need to specify an appropriate :noweb header. Try this:

    #+begin_src cpp :noweb no-export

    and refer to the noweb section in the manual for other values and more details.