MICADO-document-template/README.md

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), which was based on other ESO LaTeX documentation templates using dmd-doc.
• Some features have been adapted from this Overleaf template.
• I've taken inspiration from the SRON document template of Paul Ton (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.