126 lines
6.0 KiB
Markdown
126 lines
6.0 KiB
Markdown
# LaTeX Document template for MICADO technical documentation
|
|
|
|
For technical documentation requiring equations, code snippets, easier referencing or version control using Git, LaTeX can be preferable over WYSIWYG software packages.
|
|
This repository provides a template for the typical layout of MICADO technical documentation during the Phase B and Phase C parts of
|
|
the project.
|
|
|
|
I've based the layout on previous documentation for the Preliminary and Final Design review, as well as some of my own technical notes.
|
|
To minimize the differences between the documentation written in Microsoft Office and this, I've tried to match the layout, font, tables
|
|
footers and headers as closely as possible.
|
|
|
|
## Sources and inspiration
|
|
- The original document was adapted from the MICADO PDR Calibration Plan ([gitlab.astro-wise.org](https://gitlab.astro-wise.org/micado/calibrationplan)),
|
|
which was based on other ESO LaTeX documentation templates using `dmd-doc`.
|
|
- Some features have been adapted from [this](https://www.overleaf.com/latex/templates/ic-materials-materials-characterisation-exercise-template/grtxttnbrskb) Overleaf template.
|
|
- I've taken inspiration from the SRON document template of Paul Ton ([https://personal.sron.nl/~pault/](https://personal.sron.nl/~pault/))
|
|
|
|
## Features
|
|
- Change between *Draft*, *Review*, *Technical Note* or *Memo* by changing a single argument in the document pre-amble: `\usepackage[draft]{micado}`.
|
|
This changes the layout of the document. When using `draft`, the title page will display this clearly and the header on each table will show it too.
|
|
Using `technote` removes the title page entirely.
|
|
- Document information can be filled in in the prepared document preamble.
|
|
- References placed into `ApplicableDocuments.bib` and `ReferenceDocuments.bib` will be treated as Applicable Documents and Reference Documents, respectively.
|
|
They receive the appropriate label ([AD...] and [RD...]) and are placed in separate reference tables. All references in the `ApplicableDocuments.bib` file are
|
|
printed in the Applicable Documents table, but only the reference documents that are cited in text are printed in the Reference Documents table.
|
|
- Fill the change record table in the document pre-amble. Depending on the document type, the location of the Change Record table might change.
|
|
- Many acronyms used in MICADO documentation are already included in the `acronyms.tex` file. Use in the text with `\ac{}`, `\acs{}` or `\acl{}`.
|
|
- Nested acronyms are possible. Both will be printed in the acronym list. For example, MICADO - The Multi-AO Imaging CamerA for Deep Observations - uses AO in the
|
|
long version. Therefore, AO - Adaptive Optics - will also be printed in the acronyms list.
|
|
- Extensive comments explaining what is what in the `.tex` and `.sty` files.
|
|
|
|
## An example document
|
|
Please, check the provided example PDFs to get a feel for what the document types might look like.
|
|
|
|
```
|
|
\documentclass[twoside,11pt,a4paper]{article}
|
|
\usepackage[draft]{micado}
|
|
|
|
% General Document information
|
|
\dmdTitle{Document title} % Document title
|
|
\dmdDocId{XXX-XXX-XXX-XXXXX-XXXX} % Document number
|
|
\dmdIssue{1.0} % Version number
|
|
\dmdDate{12.04.2021} % Issue Date
|
|
\dmdPreparedBy{Author Name} % Author(s)
|
|
\dmdPreparedOn{\today} % Date that document was signed
|
|
|
|
% Change record
|
|
\dmdChangeRecord{ % Change record table. Fill as a four column table.
|
|
1.0 & 09/03/2021 & All & Initial document \\
|
|
}
|
|
|
|
% Only for (draft)review
|
|
\dmdPreparedSig{} % Who is submitting the document?
|
|
\dmdApprovedBy{} % Who approved the document?
|
|
\dmdApprovedOn{} % When is the document approved?
|
|
\dmdApprovedSig{} % Signature of the person approving the document
|
|
\dmdReleasedBy{} % Who releases the document?
|
|
\dmdReleasedOn{} % When is the document being released?
|
|
\dmdReleasedSig{} % Signature of the person releasing the document
|
|
|
|
% Definition required to get references in tables
|
|
\makeatletter
|
|
\def\fixextblx@setrefcontext{%
|
|
\expandafter\blx@setdefaultrefcontext\expandafter{\abx@field@entrykey}}
|
|
|
|
% Defines the function that prints references in a table
|
|
\defbibtabular{bibtabular}{
|
|
\begin{center}
|
|
% \setlength\LTleft{10pt}
|
|
% \setlength\LTright{0pt}
|
|
\begin{longtable}{@{\extracolsep{\fill}}|c|p{0.3\linewidth}|p{0.3\linewidth}|c|c|@{}}
|
|
\hline \textbf{RD Nr} & \textbf{Document Number} & \textbf{Document Title}
|
|
& \textbf{Issue} & \textbf{Date}\endhead
|
|
\hline
|
|
}
|
|
{
|
|
\hline
|
|
\end{longtable}
|
|
\end{center}}{
|
|
\anchorlang{%
|
|
\fixextblx@setrefcontext
|
|
\printtext[labelnumberwidth]{%
|
|
\printfield{labelprefix}%
|
|
\printfield{labelnumber}}}
|
|
& \plainlang{\printfield{label}}
|
|
& \plainlang{\usebibmacro{title}} \plainlang{\usebibmacro{author}}
|
|
& \plainlang{\printfield{issue}}
|
|
& \plainlang{\printdate}\\ \hline}
|
|
\makeatother
|
|
|
|
|
|
\begin{document}
|
|
|
|
\dmdmaketitle
|
|
|
|
\section{Scope}
|
|
|
|
|
|
\section{References}
|
|
\subsection{Applicable Documents}\label{sec:AD}
|
|
\defbibnote{ADnote}{The following \ac{AD} of the exact issue contain provisions (statements, instructions,
|
|
recommendations or requirements) that are ruling over - and implicate provisions in the present
|
|
document.}
|
|
\nocite{*} % This nocite is necessary for printing all applicable documents!
|
|
\newrefcontext[labelprefix=AD]
|
|
\printbibtabular[heading=none, notkeyword={RD}]
|
|
|
|
\subsection{Reference Documents}\label{sec:RD}
|
|
\defbibnote{RDnote}{The following \ac{RD} contains useful information relevant to the subject of the present
|
|
document.}
|
|
\newrefcontext[labelprefix=RD]
|
|
\printbibtabular[prenote=RDnote, heading=none, keyword={RD}]
|
|
|
|
\subsection{Acronyms}
|
|
\input{acronyms}
|
|
\newpage
|
|
|
|
\section{Introduction}
|
|
|
|
\vspace{4cm}
|
|
\centering \textbf{End of Document}
|
|
\end{document}
|
|
```
|
|
|
|
#### Disclaimer
|
|
The template works on my PC using Overleaf. No warranty on any TeX compiler is provided. Your mileage may vary.
|