0

I am attempting to write a company manual in LaTeX. I've done reports before but this manual is a bit different.

It must track subsection revision status. The idea being that each subsection has it's own revision state. Which is listed on the line after the subsection title. Then a table which contains, subsection number, revision number and revision date is generated in the front matter.

My first thought is that this is not all that different than a table of contents, perhaps a TOC macro could be bent to my needs?

  • Depends on the concrete requirements. E.g. quite often such tables should be sorted by revision number and not in the order they appear in the document. – Ulrike Fischer Jun 7 '18 at 12:33
  • In this case, the order in which they appear is the desired outcome. Having the ability to suppress the initial release (ie Rev. 0) entries from displaying in the table would also be useful. – KJC Jun 7 '18 at 12:51
  • The TOC idea seems good. Two different methods come to mind: the \subsection is modified to add extra data to the .toc file, or it is not modified but always followed by some mark-up with the revision data. That macro will write to toc file in controlled manner. The \l@subsection macro must then be redefined to fetch this. Package etoc could help. But without knowing what kind of mark-up you have in source, it is shot in the dark to decide what's best for your use case. – user4686 Jun 9 '18 at 21:42
1

This is just a start. Many things can be changed and improved. But this largely depends on how you want to track revisions and which class and packages you are using for the manual.

Here revisions and dates are set manually, which of course would be painful to do, especially if you want an overall revision. There are two macros \setrevision and \printrevision. The first sets revision, date and name (meant to be the name of the last person who modified the subsection). The second prints the information and writes it to a file \jobname.lor. These commands can easily combined into one, but I deliberately used two to make it easier to adapt this to some package supporting some revision control system (example below).

The list of revisions can be inserted with \listofrevisions, which contains the subsection number, the name, the date and the revision. It works with hyperref, so the subsection numbers are links to the subsections.

Here is the code:

\documentclass[a4paper]{scrbook}
\usepackage{xcolor}
\usepackage[colorlinks,linkcolor=blue]{hyperref}

\makeatletter
\newcommand*{\curr@revision}{}
\newcommand*{\curr@date}{}
\newcommand*{\curr@author}{}

% #1: revison
% #2: date
% #3: author (last modified by)
\newcommand*{\setrevision}[3]{%
    \def\curr@revision{#1}%
    \def\curr@date{#2}%
    \def\curr@author{#3}%
}
\newcommand*{\printrevision}{%
    \begingroup
    \ifnum\c@section=0\relax
        \let\the@sec@number\thechapter
    \else
        \ifnum\c@subsection=0\relax
            \let\the@sec@number\thesection
        \else
            \let\the@sec@number\thesubsection
        \fi
    \fi
    \addtocontents{lor}{\protect\revisionline{\the@sec@number}{\curr@revision}{\curr@date}{\curr@author}{\@currentHref}}%
    \parfillskip0pt\color{gray}
    last modified by: \textit{\curr@author}\dotfill
    date: \textsf{\curr@date}\quad
    revision: \textsf{\hbox to 2em{\hfill \curr@revision}}%
    \par\endgroup\noindent
}
\newcommand*{\listofrevisions}{%
    \chapter*{Revisions\@mkboth{Revisions}{Revisions}}%
    \@starttoc{lor}%
}
\newcommand*{\revisionline}[5]{%
    \ifx\\#5\\%
        \@revisionline{#1}{#2}{#3}{#4}%
    \else
        \ifcase\Hy@linktoc % none
            \@revisionline{#1}{#2}{#3}{#4}%
        \or % (section) section number
            \@revisionline{%
                \hyper@linkstart{link}{#5}{#1}\hyper@linkend
            }{#2}{#3}{#4}%
        \or % (page) revision number
            \@revisionline{#1}{%
                \hyper@linkstart{link}{#5}{#2}\hyper@linkend
            }{#3}{#4}%
        \else % all
            \@revisionline{%
                \hyper@linkstart{link}{#5}{#1}\hyper@linkend
            }{%
                \hyper@linkstart{link}{#5}{#2}\hyper@linkend
            }{%
                \hyper@linkstart{link}{#5}{#3}\hyper@linkend
            }{%
                \hyper@linkstart{link}{#5}{#4}\hyper@linkend
            }%
        \fi
    \fi
}
\newcommand*{\@revisionline}[4]{%
    \noindent\parskip\z@\hbox to 3em{#1}\dotfill
    \textit{#4}\quad\textsf{#3}\quad\hbox to 2em{\hfill#2}\par
}
\makeatother

\begin{document}
\frontmatter
\begin{titlepage}
\centering
{\Huge The big Company Manual}

\vspace{1cm}
{\Large The inner workings of some big company}

\vspace{2cm}
\begin{tabular}{ll}
Authors & Harry Bigboss\\
        & Ruth Cando\\
        & Amelia Nicecode
\end{tabular}
\end{titlepage}

\tableofcontents

\listofrevisions

\mainmatter
\chapter{Overview}
\section{Status of this Manual}
\subsection{Usage}
\label{sec:usage}
\setrevision{123}{2018-06-10}{Harry Bigboss}
\printrevision
This manual is for internal use only. It must never leave the company.
Those who take it out, will be fired.

\subsection{Completeness}
\setrevision{55}{2018-06-11}{Ruth Cando}
\printrevision
This manual is in a pre-release state. We are still negotiating with Harry about
the contents of \autoref{sec:usage}.

\section{Goals of the Manual}
\subsection{Introduction}
\setrevision{783}{2018-06-10}{Amelia Nicecode}
\printrevision
The manual can be used as an introduction to the procedures used in this company.

\subsection{Reference}
\setrevision{2233}{2018-06-12}{Amelia Nicecode}
\printrevision
The manual is intended to be a reference of the companies internal procedures.

\end{document}

And the result:

enter image description here

enter image description here

Revision control systems:

If you want to use a revision control system, which I would highly recommend, you would have to put each subsection into its own file in order to get the revision for individual subsections.

There are helpful packages, at least for subversion and git. If you want to use subversion, there is the svn-multi package, which supports getting the revision of individual files, groups of files and the whole document.

Disclaimer: I never used this package, so this is straight from the manual. If I get something wrong, all of you feel free to correct me.

In the code above you would have to replace \setrevision with e.g. \svnid{$Id$}. Then in \printrevision you would have to replace \curr@revision, \curr@date and \curr@author with \svnfilerev, \svnfiledate and \svnfileauthor. The svn-multi package also has a \tableofrevisions (much more sophisticated then `\listofrevisions), but it gives out file names, not subsection numbers.

The workflow is as follows: edit the manual, when finished, commit the files. Subversion will then insert/change the revision information in the changed files. After that, you have to compile your manual again, to get the revision numbers right.

  • This is excellent work, gets me everything I needed and has given me good direction in managing this kind of stuff in LaTeX. Thanks. – KJC Jun 11 '18 at 18:01

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.