Section 5.9 Author Tools
While your writing project is getting underway, you may want to go in several directions at once. We have two devices, and three reports, which can help you manage this.
You may want to make a forward-reference to some future, not-yet-written material. So you can go
<xref provisional="a reminder of future material"/>
in your source. In your output, you will get a temporary place-holder of sorts.
Comments in the source code of a computer program, labeled
TODO, is a common device to help a programmer remember tasks that need to be completed. You can use a similar device in your PreTeXt source. Use an XML comment, delimited by
-->, and make the first four non-blank characters spell
todo, using any combination of lower- and upper-case you like. Your Author's Report (next) will look even better if you follow that with a colon and a space, but this is not required. So, for example, go
<!-- ToDo: include a section on salamanders and their life-cycle -->
As an XML comment, you can place this anywhere. Contents need to be plain characters, no XML will be active here. Remember to escape the two XML characters, and also be aware that
-- is banned in comments outside of the delimiters.
authors-report.xsl stylesheet, found in the
xsl/utilities directory will report all of the provisional cross-references and all of the properly prefixed todo-comments. Apply it just like you would any of the other stylesheets achieving more complicated conversions (Section 5.1). The report is organized by all of the divisions in use in your project. It is meant to be simple in appearance, just text.
author.tools parameter set equal to
yes and your LaTeX and HTML output will be annotated. (See Section 5.4 for more on parameters.) Provisional cross-references and todo-comments will be visible and highlighted, and in particular, the LaTeX output will display an abundance of extra information (maybe too much). The LaTeX-specific parameter
latex.draft set to
yes will automatically activate the previous features, in addition to a few others appropriate to the printed page. The intent here is to make a rough draft, for an author or collaborator only, reporting as much as possible that is incomplete, pending, or hidden, in the usual output.