summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/vhistory/en_vhistory.tex
blob: 18dc5d662c4deef5d124002fdd1c54225708406f (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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
\section{The package vhistory}

The purpose of this package was described in detail in section \ref{introduction}.
I told you, it is worth reading, didn't I? In this section the usage of vhistory is described in detail.

\subsection{Loading the package}\label{load}
As usual the package is loaded by using the command\\
\mbox{}\hspace{2em}\verb|\usepackage{vhistory}|\\
in the preamble. Vhistory requires \LaTeXe\ and the packages sets and ltxtable (which requires longtable and tabularx). If this packages are not already loaded, vhistory will load them.

Vhistory understands several options to control its behaviour. These are listed below. An example for using options would be\\
\mbox{}\hspace{2em}\verb|\usepackage[tocentry, owncaptions]{vhistory}|.

\paragraph{nochapter:} If this option is used, the history of versions will no be placed in an own chapter---respectively an own section, if you use the document classes article or scrartcl.

\paragraph{tocentry:} With this option you can cause an entry in the table of contents. Normaly there won't be such an entry. If the option nochapter is used, tocentry has no effect and you are responsible for toc entries.

\paragraph{owncaptions:} vhistory supports the languages Dutch, English, French and German. If you use an unsopported language, all captions (like ``History of versions'' or ``Chan\-ges'') will be in English. In this case you might want to change captions yourself. The option own\-capt\-ions supports you in this case. More information on this topic can be found in subsection \ref{languages}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Usage}\label{usage}
The Usage of vhistory is rather easy and is to be described in this subsection.
It is important to know that vhistory needs to runs of \LaTeX, because some data is written to external files.

\subsubsection{Creating the history of versions}\label{begin}
The history of versions is an environment:\\
\mbox{}\hspace{2em}\verb|\begin{versionhistory}|\\
\mbox{}\hspace{2em}\verb|<entries>|\\
\mbox{}\hspace{2em}\verb|\end{versionhistory}|

An entry generally looks like:\\
\mbox{}\hspace{2em}\verb@\vhEntry{<Version>}{<Date>}{<Authors>}{<Changes>}@

The authors are written in the set notation of the package sets, i.\,e. the character \texttt{|} is used as the separator. An example for entry could therefore be:\\
\mbox{}\hspace{2em}\verb@\vhEntry{1.1}{13.05.04}{JW|AK|KL}{Typos corrected.}@

The \verb|\begin|\ldots starts a new chapter (or a new section respectively, if article is used), if not disabled as described above.

The history of versions itself is set in an ``ltxtable''. As a result of that, the history of versions can consist of more than one page. Lines in the columns ``Author(s)'' and ``Changes'' are broken automatically. The package ltxtable requires the table to be in a separate file. This file is generated be vhistory an has the ending ``ver''.

\subsubsection{Getting the current version number}
The current version number---precisely: the version number of the last entry---can be read with the command\\
\mbox{}\hspace{2em}\verb|\vhCurrentVersion|.\\
The command is available right after loading the package.

\subsubsection{Getting the current date}
Analogous to the current version number, the date of the last change can be printed. By using the command\\
\mbox{}\hspace{2em}\verb|\vhCurrentDate|\\
you will get this data. The command is available right after loading the package, too.

\subsubsection{Putting a list of all authors}
You can get a list of all authors on two ways. Via the command\\
\mbox{}\hspace{2em}\verb|\vhAllAuthorsSet|\\
you can get the authors as a set as described in section \ref{sets}. The more convenient way is using the command\\
\mbox{}\hspace{2em}\verb|\vhListAllAuthors|.

This command returns an alphabetically sorted list of authors. The items of the list are comma separated. If you want another separator---e.\,g. \texttt{\&} for usage in a table---to be used instead, you can redefine the command\\
\mbox{}\hspace{2em}\verb|\setsepararator|\\
from the package sets (compare section \ref{inspectors}).

Sometimes you want the list to contain full names like ``Jochen Wer\-ten\-au\-er'' instead of the short form ``JW'', which would probably be used in the history of versions. By using the command\\
\mbox{}\hspace{2em}\verb|\vhListAllAuthorsLong|\\
you can get this behaviour. In this case you still write ``JW'' in the \verb|\entry| command (note: there is no backslash here!), but also define a macro \verb|\JW| like shown below.\\
\mbox{}\hspace{2em}\verb|\newcommand{\JW}{Jochen Wertenauer}|\\
In the history of versions, the text ``JW'' will be shown in the authors column, but  \verb|\vhListAllAuthorsLong| will use the macro \verb|\JW|. If the macro is undefined, the short for will be shown (for this author).

Instead of \verb|\vhListAllAuthorsLong| you can also use\\
\mbox{}\hspace{2em}\verb|\vhListAllAuthorsLongWithAbbrev|,\\
which prints the short form in brackets after the complete name, e.\,g. ``Jochen Wertenauer (JW)''. Name und short form are separated by the command\\
\mbox{}\hspace{2em}\verb|\vhAbbrevSeparator|,\\
which defaults to ``\verb*|\ |''. In order to avoid line breaks, you can redefine the command with\\
\mbox{}\hspace{2em}\verb|\renewcommand{\vhAbbrevSeparator}{~}|.\\
In order to change the brackets you can redefine the commands\\
\mbox{}\hspace{2em}\verb|\vhAbbrevLeft| and\\
\mbox{}\hspace{2em}\verb|\vhAbbrevRight|\\
as needed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Language support}\label{languages}
As mentioned is section \ref{load}, vhistory supports the languages Dutch, English, French and German. All language dependent captions with their defaults are listed in table \ref{tab:languages}. If the document is written in a unsopported language, the English version will be used.

By providing the option ``owncaptions'' you can use custom captions. This option causes vhistory to default the commands in the language that was selected, when vhistory is loaded. Therefore it makes sense to load packages like babel or ngerman before vhistory.

A caption can be changed via the command\\
\mbox{}\hspace{2em}\verb|\renewcommand{<Command>}{<custom text>}|.\\
If you prefer to use ``Improvements'' instead of ``Canges'', you have to write\\
\mbox{}\hspace{2em}\verb|\renewcommand{\vhchangename}{Improvements}|\\
to get the desired result.

\begin{table}%[htb]
\begin{center}
\begin{small}
\begin{tabular}{lllll}\hline
\textbf{Command} & \textbf{German} & \textbf{English} & \textbf{French} & \textbf{Dutch}\\ \hline
\verb|\vhhistoryname| & Versionshistorie & Revision History & Historique & Wijzigingen \\
\verb|\vhversionname| & Version & Revision History & Version & Herziening \\
\verb|\vhdatename| & Datum & Date & Date & Datum\\
\verb|\vhauthorname| & Autor(en) & Author(s) & Auteur(s) & Auteur(s) \\
\verb|\vhchangename| & Änderungen & Description & Modifications & Beschrijving \\ \hline
\end{tabular}
\end{small}
\caption{language dependent captions}
\label{tab:languages}
\end{center}
\end{table}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Example}
\input{en_example}