[ParetoOptimal]

> I'm not entirely sure that trying to not have boilerplate of any kind is a worthy goal.

I think it's a worthy goal for nearly all readers. However I also believe that literate programmers should be written with many different readers in mind.

So you could have one version that is written in a "typical code" style like:

    * library 1
    ** module 1
    *** source file 1
    ** module 2
    *** source file 2

That doesn't need to be where it ends though and arguably shouldn't be. Write multiple books using the same code but represented differently as it's justified.

For example:

    * typical program style
    ** library 1
    *** module 1
    **** source file 1
    *** module 2
    **** source file 2

    * new to language X presentation of program

    ** link to various parts of library 1 alongside prose to describe concepts to language newcomer

    * typical hire presentation of program

    ** business domain focused exposition presenting code via transclusion as needed from typical program style

[cxr]

People will inevitably complain that what you're advocating for involves too much duplication, but I've independently reached the same conclusion that you have. Besides, in a good LP system, the toolchain would be able to consume the second part and transform and emit the first part.

See also this conversation about the unreadability of Knuth's .web files: <https://news.ycombinator.com/item?id=29203798#29205840>