Skip to main content

Section 4.25 Document Information

A <docinfo> element, first below the root <pretext> element, is a small database about your document. Everything in it shares one character: it is a fact required to interpret or build your source. Remove an item and the document no longer means the same thing, or no longer builds. Choices about how the same content is presented belong instead in a publication file (Chapter 45); the dividing line is discussed for authors in Section 5.6 and rigorously in Section 49.2.
A corollary for your workflow: because these items determine words on the page, your prose grows around them—settle them early, and expect some effort to reconsider one later (change the document-wide style of cross-reference text, say, and every sentence written around an <xref> deserves a re-read). Publication file switches are the reverse: they never require revisiting what you wrote, and most can wait until authoring is complete.

Identity and Catalog.

A <document-id> is a stable identifier for the project—make it distinctive, and never change it—with an optional @edition; services that track a project across builds (such as Runestone) rely on it. A <blurb> is a short markup-free description, roughly what you would expect on the back cover of a book, with an optional @shelf that tells Runestone how to categorize the work. An <initialism> is a useful short form of the title, such as FCLA.

The Vocabulary of the Document.

A <rename> element substitutes your name for a PreTeXt element’s, such as calling every <activity> a “Laboratory”; an @xml:lang attribute makes the substitution per-language.

What the Mathematics Needs.

Your <macros> are shared by every conversion (Subsection 4.9.13). A <math-package> element names a package and its MathJax extension so mathematics may rely on both (see Section 4.9).

What the Images Need.

A <latex-image-preamble> and an <asymptote-preamble> supply setup for images described by source code, and a pf:prefigure-preamble does the same for PreFigure (Section 4.14).

Where Files Live.

A <directories> element declares the directories that run with your source. Its @external attribute names the directory of files you curate, such as photographs and movies—a different directory is a different document. Its @data attribute names the directory of data files that images and programs consume. Each value is a path relative to the location of your main PreTeXt source file, to a directory that must exist. So with your source in a source directory, and your curated files in a peer directory named ext, you would write
<directories external="../ext"/>
and then an <image> would say source="photos/whippet.png" for a file at ext/photos/whippet.png, never mentioning ext itself.
The destination for generated files is not a property of your source, so it is a @generated attribute on a <directories> element in a publication file. An @external attribute there is deprecated, and honored only when the <docinfo> does not declare an external directory. To move the declaration, delete the @external attribute from the publication file and place the same value on the <directories> element in <docinfo>: the path does not change, since the publication file value was also relative to the main source file. The full story, with a worked example, is Section 5.7.

Defaults for Authored Attributes.

A document-wide default for an attribute you write on individual elements lives with the source, gathered in a single <defaults> element. Each child is the plural of the element it serves: an <images> child may carry default @width and @margins for every <image> lacking its own; a <programs> child defaults the attributes of <program> elements, notably @language; a <parsons> child defaults the language of Parsons problems; a <slides> child carries a default @valign for the vertical alignment of every slide of a <slideshow> (Section 4.43); an <xrefs> child sets the document-wide style of cross-reference text via its @text attribute (Section 4.5)—that text lands inside sentences you wrote around it.

Compatibility and Identity Marks.

A <doenetml> element records, in its @version attribute, which version of the DoenetML viewer the document’s DoenetML content was authored against. A <logo> element places an image at absolute coordinates of a printed page—the letterhead of a letter or memorandum—via @source, @llx, @lly, an optional @width, and @pages electing the first page (default) or every page.

No Longer Here.

Several items once configured in <docinfo> have found better homes, and old placements are honored with a warning during a transition. The masthead brand logo and requests for image archive links are publication file entries (Subsection 45.5.3, Subsection 45.5.8). An <event>—the occasion of a presentation—is bibliographic content and resides in the <bibinfo> (Section 4.26). Analytics, search, favicon, base URL, and worksheet-margin configuration all moved to the publication file in years past.
A <docinfo> exercising most of this could read:
<docinfo>
    <document-id edition="2">fauna-guide</document-id>
    <blurb shelf="Mathematics">A field guide to the fauna of PreTeXt.</blurb>
    <initialism>FG</initialism>
    <rename element="activity">Laboratory</rename>
    <macros>\newcommand{\adjoint}[1]{#1^\ast}</macros>
    <math-package latex-name="cancel" mathjax-name="cancel"/>
    <latex-image-preamble>\usepackage{pgfplots}</latex-image-preamble>
    <directories external="../ext" data="../data"/>
    <defaults>
        <images width="60%"/>
        <xrefs text="type-global"/>
        <programs language="python"/>
        <parsons language="natural"/>
    </defaults>
    <doenetml version="0.7"/>
</docinfo>
You have attempted of activities on this page.
PrevTopNext