summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/vhistory/doc/en_vhistory.tex
blob: 6610cd5b0d6083b8944e9fd5c07031a7edaadb9c (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
110
111
112
113
114
115
116
117
\section{The package vhistory}

The purpose of this package was described in detail in section \ref{introduction}.
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 revision history 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. Normally 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 Croatian, Dutch, English, French and German. If you use an unsupported language, all captions (like ``Revision history'' 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}.

\paragraph{tablegrid:} Setting this option will display a grid in the table representing the revision history.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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 two runs of \LaTeX, because some data is written to external files.

\subsubsection{Creating the revision history}\label{begin}
The revision history 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 revision history itself is set in an ``ltxtable''. As a result of that, the revision history 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 by vhistory an has the ending ``ver''.

\subsubsection{Getting the current version number}
The current version number---i.\,e.: 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 in 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 revision history. 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| as shown below.\\
\mbox{}\hspace{2em}\verb|\newcommand{\JW}{Jochen Wertenauer}|\\
In the revision history, 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 form 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.

\subsubsection{Adjusting the column with in the revision history}
If the width of the columns for authors and changes in the revision history does not meet your requirements, you can change the with ratio of the two columns. The commands\\
\mbox{}\hspace{2em}\verb|\renewcommand \vhAuthorColWidth{.8\hsize}|\\
\mbox{}\hspace{2em}\verb|\renewcommand \vhChangeColWidth{1.2\hsize}|\\
change the ratio to 2:3 (default is 1:3). When changing the widths, please take care that the widths add up to \verb|2\hsize|.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Language support}\label{languages}
As mentioned in section \ref{load}, vhistory supports the languages Croatian, 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 unsupported 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 ``Description'', you have to write\\
\mbox{}\hspace{2em}\verb|\renewcommand{\vhchangename}{Improvements}|\\
to get the desired result.

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

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