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.
- H. P. Langtangen.
A Document for Testing Doconce,
Simula Research Laboratory,
2015,
http://hplgit.github.io/doconce/test/demo_testdoc.html.