SPHEREx TeX document resources and Docker environment.
Contents:
To compile a document using the Docker image and the default SPHEREx Makefiles:
docker run -v `pwd`:/workspace -w /workspace ghcr.io/spherex/spherex-tex:latest sh -c 'make'Learn more about Docker and how to install it.
spherex-tex provides a custom class, named spherex, for formatting TeX documents. This section describes the commands and options that are provided by the spherex class.
Use the spherex class through the \documentclass command:
\documentclass[MS]{spherex}In this example, the MS option shows that the document is a module specification (see below).
Each SPHEREx document category has a corresponding option:
| Option | Document category | Example |
|---|---|---|
| RQ | Requirements | \documentclass[RQ]{spherex} |
| PM | Project Management | \documentclass[PM]{spherex} |
| MS | Module Specification | \documentclass[MS]{spherex} |
| DP | Data Products | \documentclass[DP]{spherex} |
| TN | Technical Note | \documentclass[TN]{spherex} |
| IF | Interface | \documentclass[IF]{spherex} |
| TR | Test/Technical Report | \documentclass[TR]{spherex} |
| RV | Review Materials | \documentclass[RV]{spherex} |
| OP | Operations Procedures | \documentclass[OP]{spherex} |
spherex provides several commands that you can use in the preamble (before \begin{document}) to set metadata that appears in the document's title and header/footer.
The document's handle. For example:
\spherexHandle{SSDC-MS-000}See also: \thehandle macro.
This command specifies the document's version:
\version{1.0}See also: \theversion macro.
This command specifies the publication date in YYYY-MM-DD format:
\docDate{2021-01-01}In the SPHEREx document templates, the \docDate is automatically set from Git metadata. However, you can override that date by setting the date with this command after the \input{meta} line in the preamble.
For most document categories, use the \title command to set the documents title. You can optionally also set an abbreviated title with the \shortTitle command that is used in page headers:
\title{Technical note title}
\shortTitle{Short Title}This command specifies the document's SPHEREx lead author:
\spherexlead[email=galileo@example.com]{Galileo Galilei}This command specifies the document's IPAC lead author:
\ipaclead[email=galileo@example.com]{Galileo Galilei}This command specifies the document's interface partner (for SSDC-IF documents):
\interfacepartner{ABC}Aside from the lead authors (\ipaclead and \spherexlead), authors are specified with the \author command. Each author is on a separate line (using \\) and marked-up with a \person command:
\author{
\person[email=galileo@example.com]{Galileo~Galilei} \\
\person{Isaac~Newton}
}You can optionally set an author's email address with the email keyword option.
This command provides metadata about the document's approval:
\approved{2021-01-01}{Edwin Hubble}The first argument is the date of approval (YYYY-MM-DD format).
The second argument is the approver's name.
For module specification (MS) documents, this command sets the name of the module:
\modulename{Example Module}This command replaces the standard \title command for setting the document's title in MS documents.
See also: \themodulename macro.
For module specification (MS) documents, this command sets the pipeline level:
\pipelevel{L2}See also: \thepipelevel macro.
For module specification (MS) documents, this command sets the diagram index:
\diagramindex{13}See also: \thediagramindex macro.
For module specification (MS) documents, this command sets the "difficulty" metadata:
\difficulty{Low}
\difficulty{Medium}
\difficulty{High}
\difficulty{Unassigned}See also: \thedifficulty macro.
The verification activity DOORS ID, with the URL as an optional argument. For SSDC-TR documents.
\VADoorsID[https://...]{12345}The requirement DOORS ID, with the URL as an optional argument. For SSDC-TR documents.
\ReqDoorsID[https://...]{12345}An IPAC Jira issue ID.
For SSDC-TR documents, can be set in conjunction with \VADoorsID or \ReqDoorsID.
\IPACJiraID{SVV-999}The title page is generated by the \maketitle command, which you should include right after the \begin{document} command. The spherex class customizes the appearance of the title page based on the document category and the available metadata.
The \dochistory environment creates a table with a document's change history.
Within the dochistory environment, you can add individual change records with the \addtohist command:
\begin{dochistory}
\addtohist{0.1}{2020-01-01}{Initial draft.}{Galileo Galilei}
\addtohist{1.0}{2021-01-01}{Initial accepted version.}{Galileo Galilei}
\end{dochistory}The arguments to the \addtohist command are:
- Version
- Date
- Description of change
- Responsible persons
The spherex class provides common macros. See the bottom of the spherex.cls source for a listing.
Use the \thediagramindex macro to print the pipeline module's diagram index, which is set in the preamble by the \diagramindex command.
Use the \thedifficulty macro to print the pipeline module's difficulty level, which is set in the preamble by the \difficulty command.
Use the \thehandle macro to print the document's handle, which is set in the preamble by the \spherexhandle command.
Use the \themodulename macro to print the pipeline module name, which is set in the preamble by the \modulename command.
Use the \thepipelevel macro to print the pipeline module's level, which is set in the preamble by the \pipelevel command.
Use the \theversion macro to print the document's version, which is set in the preamble by the \version command.
spherex-tex includes a centrally maintained BibTeX file for the SPHEREx project: texmf/bibtex/bib/spherex.bib. To use this bibliography from documents, include:
\bibliography{spherex}When adding or removing files from the texmf directory, also update the texmf/ls-R file:
mktexlsr --verbose texmfThe test directory contains sample documents that are configured to compile using the locally-cloned texmf directory. You can compile all test documents:
cd test
./test.sh