* This headline won't export :noexport:
These are some comments for the user and maintainers
of this document. Describing our formatting and
practices.
* This headline will export
And here's the text describing some message format.
And here's a table showing the layout:
| Word | 12-15 | 8-11 | 4-7 | 0-3 |
| 0 | WordCnt | TimeTag| ... | ... |
And here's the source for this as a C struct, but
it's a work in progress. So we won't export it yet.
#+NAME: MSGXXX_struct
#+BEGIN_SRC c :exports none
typedef struct {
...
} MSGXXX_t
#+END_SRC
No one has to see that stuff until I'm done with it. Or, other tags could be used so I can explicitly select what gets exported depending on the audience. The customer doesn't need the code (at this point). But fellow devs (local, or at partner organizations) may.In my (maybe skewed) experience though once 2 or more people start adding comments on the same place of code things can get very confusing quickly -- with mishmash of different styles, commented out comments, multiple copy-paste, etc., so the only way to understand what is going on is to delete the whole Kunstkamera and look only at the code.
You can get code only views, no deletion necessary. Run tangle, which will spit out all the source files (which is part of the compilation/execution step anyways), or use (org-mode specific): C-c C-v C-v (org-babel-expand-src-block). The latter gives you the expanded (this assumes you're using something like noweb[0]) view of the code in a read-only buffer.
Org uses optional noweb notation to include blocks of code in other blocks:
#+NAME: print_hello_world
#+BEGIN_SRC c
printf("Hello, World!\n");
#+END_SRC
#+BEGIN_SRC c :noweb yes :tangle hello.c
#include<stdio.h>
int main(int argc, char** argv) {
<<print_hello_world>>
return 0;
}
#+END_SRC
<<name>> will be substituted with the contents of the other block. The expand-src-block will give you a view with all substitutions made. C-c C-v C-t (org-babel-tangle) will generate hello.c (could be prefixed with a directory, my preferred way, so it'd be "src/hello.c").A more useful case than the above, I have a switch/case statement. Each case gets broken into its own source block with documentation around it like:
* Handling different message types
#+BEGIN_SRC c :noweb yes
switch(msg.type) {
<<msg_101>>
<<msg_102>>
<<default>>
}
#+END_SRC
** Message 101
Documentation
#+NAME: msg_101
#+BEGIN_SRC c
case 101:
// handle 101
break;
#+END_SRC
** Message 102
Documentation
#+NAME: msg_102
#+BEGIN_SRC c
case 102:
// handle 102
break;
#+END_SRC
** Default case
Documentation
#+NAME: default
#+BEGIN_SRC c
default:
// handle default
#+END_SRC
It seems literate programming assumes that the person doing development is the same as the one reading documentation. That is not always the case. And when it is not the case, the code embedded in documentation can hurt readability.
For example, I try to get all interface specs distributed, discussed and confirmed ASAP, usually WAY before the code is mature enough to be shown outside. Also, getting others to read, think about and comment on even short ICDs is difficult as is. Getting them to read early ICDs interspersed with early code? Not going to fly. My 2c.