Test of one author at one institution

John Doe (doe at cyberspace.net)

Cyberspace Inc.

Mar 1, 2021


Generalized References


Sometimes a series of individual documents may be assembled to one large document. The assembly impacts how references to sections are written: when referring to a section in the same document, a label can be used, while references to sections in other documents are written differently, sometimes involving a link (URL) and a citation. Especially if both the individual documents and the large assembly document are to exist side by side, a flexible way of referencing is needed. For this purpose, DocOnce offers generalized references which allows a reference to have two different formulations, one for internal references and one for external references. Since LaTeX supports references to labels in external documents via the xr package, the generalized references in DocOnce has a syntax that may utilize the xr feature in LaTeX.

The syntax of generalized references reads
ref[internal][cite][external]
If all standard ref references (with curly braces) in the text internal are references to labels in the present document, the above ref command is replaced by the text internal. Otherwise, if cite is non-empty and the format is latex or pdflatex one assumes that the references in internal are to external documents declared by a comment line # Externaldocuments: testdoc, mydoc (usually after the title, authors, and date). In this case the output text is internal cite and the LaTeX package xr is used to handle the labels in the external documents. When referring to a complete chapter (not a section in it), which corresponds to a complete external document, it does not make sense to write out internal cite since the internal reference is a chapter number. In such cases, the internal syntax can be used, and if the label is in another LaTeX document, the output is just cite. For all output formats other than latex and pdflatex, the external text will be the output.

Here is an example on a specific generalized reference to a section in a document:
As explained in
ref[Section ref{subsec:ex}][in "Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
cite{testdoc:12}][a "section":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
the document "A Document for Testing DocOnce":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}], DocOnce documents may include tables.
With latex or pdflatex as output, this translates to
As explained in
Section ref{subsec:ex}, DocOnce documents may include tables.
if the label {subsec:ex} appears in the present DocOnce source, and otherwise
As explained in
Section ref{subsec:ex} in "Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
cite{testdoc:12}, DocOnce documents may include tables.
In a format different from latex and pdflatex, the effective DocOnce text becomes
As explained in
a "section":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
the document "A Document for Testing DocOnce":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}, DocOnce documents may include tables.
The rendered text in the current format html becomes

As explained in a section in the document A Document for Testing DocOnce [1], DocOnce documents may include tables.

A reference to an entire external document, which is usually a chapter if the reference is internal in the DocOnce source, applies the refch syntax:

As explained in
refch[Chapter ref{ch:testdoc}]["Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}][the document
"A Document for Testing DocOnce":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}], DocOnce documents may include tables.
The output now if ch:testdoc is not a label in the document, becomes in the latex and pdflatex case

As explained in
"Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}, DocOnce documents may include tables.
That is, the internal reference Chapter ... is omitted since it is not meaningful to refer to an external document as "Chapter". The resulting rendered text in the current format html becomes

As explained in the document A Document for Testing DocOnce [1], DocOnce documents may include tables.

Note that LaTeX cannot have links to local files, so a complete URL on the form https://... must be used.

And here is another example with internal references only:

Generalized references are described in ref[Section ref{genrefs}][dummy1][
dummy2].
The text is rendered to

Generalized references are described in the section Generalized References.

Test of math


Inline math, \( a=b \), is the only math in this document.

  1. H. P. Langtangen. A Document for Testing Doconce, Simula Research Laboratory, 2015, http://hplgit.github.io/doconce/test/demo_testdoc.html.