Traversing the TeXmacs documentation

As a general rule, you should avoid the use of sectioning commands inside the TeXmacs documentation and try to write small help pages on well identified topics. At a second stage, you should write recursive “meta help files” which indicate how to traverse the documentation in an automatic way. This allows the reuse of a help page for different purposes (a printed manual, a web-oriented tutorial, etc.).

The tmdoc style provides three markup macros for indicating how to traverse documentation. The traverse macro is used to encapsulate regions with traversal information. The branch macro indicates a help page which should be considered as a subsection and the continue macro indicates a follow-up page. Both the branch and the continue macro take two arguments. The first argument describes the link and the second argument gives the physical relative address of the linked file.

Typically, at the end of a meta help file you will find several branch or continue macros, inside one traverse macro. At the top of the document, you should also specify a title for your document using the tmdoc-title macro. When generating a printed manual from the documentation, a chapter-section-subsection structure will automatically be generated from this information and the document titles. Alternatively, one might automatically generate additional buttons for navigating inside the documentation using a browser.