News for hackers. Stuff that matters.
Re:Ferret: a Lisp implementation for real time embedded cont... by Jtsummers on Tuesday July 31, 2018 @12:10PM (#17654416)
I mean, it isn't, if you organize your file identically to the source tree. But I break it out differently when I use this approach. I'll use the noweb references and scatter my code across the document in a logical way that's not reflective of the generated source tree.

For instance, I group all include or equivalent statements in an appendix, rather than within the primary code discussion. If a block of code can't be directly reused, but for some reason needs to be in every (or several) source files (think standard boilerplate), I'll write it once in a place that makes sense, and reference it from all the places where it actually gets tangled into the output.

Additionally, I include the Makefile (or whatever equivalent) and other scripts within this same document. Learning docker? Make a dockerfile in here, fully annotated, along with the shell commands to actually deploy it.

Mine will only mirror the original source tree if it's:

Very simple.

I've imported a bunch of code into it and don't, yet, know how to break it down.

An example C project may look like:

  * Purpose Statement
  * README
  * Usage
  This program can be executed from the command line by calling:
  #+BEGIN_EXAMPLE
    $ ./foo
  #+END_EXAMPLE
  It accepts the following command line parameters:
  - =-c= :: something
  - =-d= :: something else
  ** Implementation
  To process the command line flags we use <some library>.
  it has the following API calls...

  Here's the code for processing our commands...
  * Business Logic
  We communicate with the server via some REST API described in <location>
  and <library> to make the calls.
  -- Here I'd intermingle the REST API I'm using and the C API I'm producing
  -- for my own consumption, or something similar.
  * Code that's not fully organized yet
  ** Main Function
  This is the entry point, blah, blah, blah:
  #+BEGIN_SRC c :noweb yes :tangle src/main.c
  #+END_SRC
  * Appendix: Includes

There are no comments on this comment yet.