Section 48.4 Documentation
Careful documentation must accompany new features. You cannot leave this task for somebody else to clean-up after you, and writing the documentation is likely to cause you to revisit your code to introduce small improvements or squash bugs.
New PreTeXt language elements are described briefly in the overview at Chapter 3. This should make new authors aware of what elements are available, and maybe have enough instruction to get them started. Then the topics at Chapter 4 should have full details. These two sections should link back-and-forth to each other. Examples are welcome, but should be short and succinct. Elaborate examples should be contributed to the Showcase Article.
New options for publishers should be detailed very tersely in the reference section, Chapter 44. This section is organized lexicographically with respect to the XPath expressions describing the entries of the publication file. Then a more careful description, with examples if necessary, should appear in one of the chapters of the publisher part (Part IV) according to which aspects of a conversion are affected. These two sections should link back-and-forth to each other.
Here are some conventions to follow, which will help authors and publishers have a better experience wandering through the Guide. Please observe them in your own contributions.
-
The Guide.We usually just say “the Guide” or “in this Guide”, with no additional formatting, and just the capital “G” indicative of a formal title.
-
Modularization.When an author’s source is modularized (Section 5.3) we refer to the outermost, or main, file as the “top-level” file. This is the one file that has the overall
<pretext>element in it. -
Git Branches.Reference the primary branch of a git repository as
main.
