# 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`.