Skip to main content

Section 5.10 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 -->, 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.

Use the author.tools parameter set equal to yes and your and HTML output will be annotated. (See Section 5.5 for more on parameters.) Provisional cross-references and todo-comments will be visible and highlighted, and in particular, the output will display an abundance of extra information (maybe too much). The -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.

For users of xsltproc, the 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. See Section 43.7.