3 ms·
I haven't figured out literate programming with a large group yet, but I do use it (with org mode) for my own projects (solo or small group). A nice thing, at l
by Jtsummers 10y ago
I haven't figured out literate programming with a large group yet, but I do use it (with org mode) for my own projects (solo or small group). A nice thing, at least with org-mode, is that I can choose whether or not to export a particular bit of content.
* 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.
- ptero 10y agoThat is reasonable for a solo project, which naturally has a common style readable to the author. 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.
- Jtsummers 10y agoNOTE: The plain text mode here doesn't do the org-file content I've included justice. Copy it into emacs and switch to org-mode to see how this'd actually look and work. And I agree, right now I've only figured out how to do this with myself and one or two other people. I use this for both work and side projects. I also tend to work on smaller code teams (max 3 people) so that helps if I want to use this at work on a specific project. You also have to get buy in on the tool (emacs and org-mode, in this case, which is a hard sell these days). I imagine there are ways to make this scale, but I've not figured it out yet. It'll require more tooling and finer-grained access for editing. Merging with this in git could be a pain in the ass with more than a couple people. 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