This document embodies a JS program and its documentation. It's written in such a way that it serves to be self-documenting. The program itself is made up of several modules.
(Since this is just a demonstration, the modules we present are extremely basic and are few. There are only two, to be exact. Consider them placeholders and a good opportunity to "fork" this document and fill it in with modules of your own.)
You don't have to be an astute observer to notice that these modules don't really do anything.
A program written this way, however, can both serve a useful purpose and be incredibly effective in its presentation. This style of programming enables a top-down approach, where the reader may begin at the top of the document and read to the bottom, unlike the unnatural way many programmers are forced to lay out a codebase or are forced to approach a program written by someone else.
If we had a full fledged program here instead of the stubs, one thing we'd do is make sure the very last JS block contains the program "entry point". (The modules specified above can be considered "inert", as each one only declares the existence of the module itself and defines its behavior, but beyond those definitions, no code block includes any top-level mutable state or "static initialization" logic.) Program initialization actually occurs here—note that the way this is written means it constitutes an "immediately invoked function expression":
In a sense, the block containing main is a sort of
"meta-module", since its role is predicated upon intimate knowledge of the
particulars of script evaluation.
If we were especially clever, we could include other modules (suppose we relegated them to be contained to an "Appendix B" below, to follow Appendix A), after the end of the main text. These, too, could be "meta-modules".
For example, suppose we expected users to edit the HTML in this file by hand—we have strived, too, up to this point to also make this file readable even in in its plain text HTML representation. Further meta-modules might serve a useful purpose in that case.
If we were willing to include another meta-module or three, those
modules might contain code to validate at runtime (i.e. when the document
is opened) the invariants that this document assumes, e.g. validating
internal links and such or even verifying that the script and
style elements' before and after
pseudo elements have the exact plaintext representation as the
ones that are faked with the CSS content rules. If we were really
serious, we might even go beyond validation and make sure these meta
modules actually modify the DOM for any affected elements, inserting rules
and such so that if, say, someone were to add some arbitrary attributes to
a script element represented here, then those extra
attributes would be found at runtime and that element's representation
changed to match. To go even further than that, we could include some
meta modules that similarly fix up the DOM at runtime so that references
to code in non-normative, descriptive text or even within code blocks
themselves can be appropriately linked to the bit of code referred to,
e.g. matching function call sites to their implementation.
For completeness, we also present the stylesheet for this document, since presentation in this form would not be possible otherwise, and the styling rules serve as much of a purpose (albeit an auxiliary one) as the code blocks above.
These style rules are deliberately selected for their ratio of utility versus heft. The idea is that, even with this style sheet being fairly barebones, the end result is an attractive enough document to sit down and read. The rules for effecting that balance are as follows: