summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/vhistory/doc/en_introduction.tex
blob: d4d99fb9e56cfba5339c5d716a896ff93ba22497 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
\section{Introduction}\label{introduction}
It's clear to me that nobody reads introductions. Nevertheless I recommend not to skip this section, as it tries to explain why I developed the packages sets and vhistory.
By reading the following you can see if these packages meet your requirements.

During software projects (hopefully) a lot of documents like specification or design are created. These are normally revised several times. To reconstruct changes, documents should contain a so called \emph{revision history} aka change log. This is a table whose entries contain the following data:
\begin{itemize}
	\item a version number,
	\item the date of the change,
	\item some kind of identification code (e.\,g.\ the initials) of the persons that
	made the changes (the authors),
	\item a summary of the changes.
\end{itemize}

Certain data of the revision history shall often be repeated at other parts of the document. Typically the title page shall quote the most recent version number and all authors of the document. The version number should although be repeated on every page, e.\,g. in a footer. By doing this, it is easy to verify if a page is part of the most recent version or if it is outdated.

Normally the data that is placed on say the title page, is not (automatically) taken from the revision history, but stated at another part of the document. The entries in the revision history are normally always updated. Due to stress and rush updating the data on the title page is often forgotten. This results in inconsistent documents.
From my own experience I know that the list of authors is practically never correct, especially when several people edited a document in the course of time.

Therefore it would be nice if the author of a document only had to take care of the revision history. The informations on title page and in footers should be generated from the revision history automatically.

These requirements cannot be implemented without any effort, because the title page for instance is processed by \LaTeX\ before the revision history is even read. 
All relevant data therefore has to be written to a file and read again before processing the title page. As for some applications even the moment when the aux-file is read is too late, an own file with the extension hst is created.
The table containing the revision history needs an own file, too, but this topic will be discussed later.


Another problem is the list of authors. This list cannot be created by simply concatenating the author entries, because this would result in duplicate entries. At this time the package sets was born allowing to manage simple sets of text. At every entry in the revision history, the set of authors is merged with the set of authors given at this entry. The alphabetically sorted set of authors can then be printed wherever one likes---normally on the tile page.

The following to sections describe the two packages in more detail and explain how to use them. I decided not to repeat anything of source code here. Those who are interested can take a look at the sources. I tried to structure and comment the sources in a way that makes it readable for humans.