summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex')
-rw-r--r--Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex382
1 files changed, 231 insertions, 151 deletions
diff --git a/Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex b/Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex
index a146dcf8f97..751f4aa391f 100644
--- a/Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex
+++ b/Master/texmf-dist/doc/latex/changes/userdoc/changes.en.tex
@@ -6,7 +6,7 @@ This package provides means for manual change markup.
Any comments, thoughts or improvements are welcome.
The package is maintained at \emph{gitlab}, please see
-\url{http://edgesoft.de/projects/latex/changes/}
+\url{https://edgesoft.de/projects/changes/}
for links to source code access, bug and feature tracker, etc.
If you want to contact me directly, please send an email to \href{mailto:ekleinod@edgesoft.de}{ekleinod@edgesoft.de}.
@@ -35,23 +35,23 @@ Please refer to these examples for inspiration and first problem solving.
%^^A ---- usage
\cleardoublepage
-\section{Using the \chpackage{changes}-package}
+\section{Using the \docpackage{changes}-package}
\label{sec:usage}
-In this section a typical use case of the \chpackage{changes}-package is described.
+In this section a typical use case of the \docpackage{changes}-package is described.
You can find the detailed description of the package options and new commands in \autoref{sec:ui}.
We start with the text you want to change.
You want to markup the changes for each author individually.
Such a change markup is well-known in WYSIWYG text processors such as \emph{LibreOffice}, \emph{OpenOffice}, or \emph{Word}.
-The \chpackage{changes}-package was developed in order to support such change markup.
+The \docpackage{changes}-package was developed in order to support such change markup.
The package provides commands for defining authors, and for marking text as added, deleted, or replaced.
Additionally, text can be highlighted or commented.
In order to use the package, you should follow these steps:
\begin{enumerate}
- \item use \chpackage{changes}-package
+ \item use \docpackage{changes}-package
\item define authors
\item markup text changes
\item highlight and comment text
@@ -61,9 +61,9 @@ In order to use the package, you should follow these steps:
\end{enumerate}
-\minisec{Use \chpackage{changes}-package}
+\minisec{Use \docpackage{changes}-package}
-In order to activate change management, use the \chpackage{changes}-package as follows:
+In order to activate change management, use the \docpackage{changes}-package as follows:
\chinline{usepackage_changes}
@@ -72,14 +72,14 @@ respectively
\chinline{usepackage_options_changes}
You can use the options for defining the layout of the change markup.
-You can change the layout after using the \chpackage{changes}-package as well.
+You can change the layout after using the \docpackage{changes}-package as well.
For detailed information please refer to \autoref{sec:ui:options} and \autoref{sec:ui:customizingoutput}.
\minisec{Define authors}
-The \chpackage{changes}-package provides a default anonymous author.
+The \docpackage{changes}-package provides a default anonymous author.
If you want to track your changes depending on the author, you have to define the needed authors as follows:
\chinline{definechangesauthor}
@@ -142,9 +142,9 @@ You can print a list of changes using:
The list is meant to be the analogon to the list of tables, or the list of figures.
-Stating the style is optional, default is \choption{style=list}.
-In order to print a quick overview of the number and kind of changes of every author, use the option \choption{style=summary} or \choption{style=compactsummary}.
-Show only specific changes by using the \choption{show} option.
+Stating the style is optional, default is \docoption{style=list}.
+In order to print a quick overview of the number and kind of changes of every author, use the option \docoption{style=summary} or \docoption{style=compactsummary}.
+Show only specific changes by using the \docoption{show} option.
By running \hologo{LaTeX} the data of the list is written into an auxiliary file.
This data is used in the next \hologo{LaTeX} run for typesetting the list of changes.
@@ -178,16 +178,18 @@ For detailed information please refer to \autoref{sec:remove-markup}.
\section{Limitations and possible enhancements}
\label{sec:limitations}
-The \chpackage{changes}-package was carefully programmed and tested.
+The \docpackage{changes}-package was carefully programmed and tested.
Yet the possibility of errors in the package exists, you might encounter problem during use, or you might miss functionality.
-In that case, please go to
-\url{http://changes.sourceforge.net/}
+You can find a list of th emost important known problems and possible solutions in \autoref{sec:known-problems}.
+Please refer to the section first if your problem is known and is a solution exists.
+More errors, problems, and solutions are provided at:
-There you find information on how to report errors or improvements, give advice to other users, or participate in the development of the package.
+\url{https://edgesoft.de/projects/changes/}
-You can find a list of known problems and possible solutions in \autoref{sec:known-problems}.
-Please refer to the section first if your problem is known and is a solution exists.
+or
+
+\url{https://gitlab.com/ekleinod/changes/-/issues}
You can write me an email too, please send it to \href{mailto:ekleinod@edgesoft.de}{ekleinod@edgesoft.de}.
In that case, please start your email subject with \texttt{[changes]}.
@@ -207,13 +209,14 @@ You can try putting such text in an extra file and include in with \texttt{input
This works sometimes, give it a try.
Kudos to Charly Arenz for this tip.
+If you experience errors about already defined macros, please see option \docoption{commandnameprefix}, \autoref{sec:ui:options:commandnameprefix}.
%^^A ---- user interface
\cleardoublepage
-\section{User interface of the \chpackage{changes}-package}
+\section{User interface of the \docpackage{changes}-package}
\label{sec:ui}
-This section describes the user interface of the \chpackage{changes}-package, i.e.\ all options and commands of the package.
+This section describes the user interface of the \docpackage{changes}-package, i.e.\ all options and commands of the package.
Every option and new command is described.
If you want to see the options and commands in action, please refer to the examples in
@@ -239,39 +242,75 @@ The following options are defined:
\chinline{usepackage_draft_changes}
-The \choption{draft}-option enables markup of changes.
-The list of changes is available via \chcommand{listofchanges}.
+The \docoption{draft}-option enables markup of changes.
+The list of changes is available via \doccommand{listofchanges}.
This option is the default option, if no other option is selected.
-The \chpackage{changes} package reuses the declaration of \choption{draft} in \chcommand{documentclass}.
-The local declaration of \choption{final} overrules the declaration of \choption{draft} in \chcommand{documentclass}.
+The \docpackage{changes} package reuses the declaration of \docoption{draft} in \doccommand{documentclass}.
+The local declaration of \docoption{final} overrules the declaration of \docoption{draft} in \doccommand{documentclass}.
\subsubsection{final}
\chinline{usepackage_final_changes}
-The \choption{final}-option disables markup of changes, only the correct text will be shown.
+The \docoption{final}-option disables markup of changes, only the correct text will be shown.
The list of changes is disabled, too.
-The \chpackage{changes} package reuses the declaration of \choption{final} in \chcommand{documentclass}.
-The local declaration of \choption{draft} overrules the declaration of \choption{final} in \chcommand{documentclass}.
+The \docpackage{changes} package reuses the declaration of \docoption{final} in \doccommand{documentclass}.
+The local declaration of \docoption{draft} overrules the declaration of \docoption{final} in \doccommand{documentclass}.
+
+
+\subsubsection{commandnameprefix}
+\label{sec:ui:options:commandnameprefix}
+
+\chinline{usepackage_commandnameprefix_changes}
+
+The \docoption{commandnameprefix} option sets the prefixing strategy for the markup commands.
+This is useful if another package already defined commands, e.g. \doccommand{comment} or \doccommand{highlight}.
+
+Per default an error is raised if a command is already defined and no prefixing takes place (option not given or set to \docoption{none}).
+
+If a prefix strategy is set, the command in question is prefixed with "ch".
+The strategy determines which commands are prefixed.
+
+This option only provides prefixed names for the markup commands:
+
+\begin{itemize}
+ \item \doccommand{added} \ensuremath{\to} \doccommand{chadded}
+ \item \doccommand{deleted} \ensuremath{\to} \doccommand{chdeleted}
+ \item \doccommand{replaced} \ensuremath{\to} \doccommand{chreplaced}
+ \item \doccommand{highlight} \ensuremath{\to} \doccommand{chhighlight}
+ \item \doccommand{comment} \ensuremath{\to} \doccommand{chcomment}
+\end{itemize}
+
+The following strategies for \emph{commandnameprefix} are provided:
+
+\begin{description}
+ \item [\docoption{none}] no prefix, a command already defined raises an error (default strategy)
+ \item [\docoption{ifneeded}] if a command is already defined, \docpackage{changes} prefixes this command and raises a warning.
+ Depending on the commands already defined, the document will contain a mix of prefixed and not prefixed markup commands.
+ This is mostly used if only \doccommand{comment} or \doccommand{highlight} are already defined and you mainly want to use the change commands \doccommand{added}, \doccommand{deleted}, and \doccommand{replaced}.
+ \item [\docoption{always}] all commands are prefixed, an according message is written to the log
+\end{description}
+
+\chexample{usepackage_commandnameprefix_changes}
\subsubsection{markup}
\chinline{usepackage_markup_changes}
-The \choption{markup} option chooses a predefined visual markup of changed text.
+The \docoption{markup} option chooses a predefined visual markup of changed text.
The default markup is chosen if no explicit markup is given.
-The markup chosen with \choption{markup} can be overwritten with the more special markup options \choption{addedmarkup}, \choption{deletedmarkup}, \choption{commentmarkup}, or \choption{highlightmarkup}.
+The markup chosen with \docoption{markup} can be overwritten with the more special markup options \docoption{addedmarkup}, \docoption{deletedmarkup}, \docoption{commentmarkup}, or \docoption{highlightmarkup}.
The following values for \emph{markup} are defined:
\begin{description}
- \item [\choption{default}] default markup for added and deleted text, comments and highlighted text (default markup)
- \item [\choption{underlined}] underlined for added text, wavy underlined for highlighted text, default for deleted text, and comments
- \item [\choption{bfit}] bold added text, italic deleted text, default for comments and highlighted text
- \item [\choption{nocolor}] no colored markup, underlined for added text, wavy underlined for highlighted text, default for deleted text and comments
+ \item [\docoption{default}] default markup for added and deleted text, comments and highlighted text (default markup)
+ \item [\docoption{underlined}] underlined for added text, wavy underlined for highlighted text, default for deleted text, and comments
+ \item [\docoption{bfit}] bold added text, italic deleted text, default for comments and highlighted text
+ \item [\docoption{nocolor}] no colored markup, underlined for added text, wavy underlined for highlighted text, default for deleted text and comments
\end{description}
\chexample{usepackage_markup_changes}
@@ -283,23 +322,23 @@ Please ignore the errors, they vanish in the second run.
\chinline{usepackage_addedmarkup_changes}
-The \choption{addedmarkup} option chooses a predefined visual markup of added text.
+The \docoption{addedmarkup} option chooses a predefined visual markup of added text.
The default markup is chosen if no explicit markup is given.
-The option \choption{addedmarkup} overwrites the markup chosen with \choption{markup}.
+The option \docoption{addedmarkup} overwrites the markup chosen with \docoption{markup}.
The following values for \emph{addedmarkup} are defined:
\begin{description}
- \item [\choption{colored}] no text markup, just coloring -- {\color{orange} example} (default)
- \item [\choption{uline}] underlined text -- \uline{example}
- \item [\choption{uuline}] double underlined text -- \uuline{example}
- \item [\choption{uwave}] wavy underlined text -- \uwave{example}
- \item [\choption{dashuline}] dashed underlined text -- \dashuline{example}
- \item [\choption{dotuline}] dotted underlined text -- \dotuline{example}
- \item [\choption{bf}] bold text -- \textbf{example}
- \item [\choption{it}] italic text -- \textit{example}
- \item [\choption{sl}] slanted text -- \textsl{example}
- \item [\choption{em}] emphasized text -- \emph{example}
+ \item [\docoption{colored}] no text markup, just coloring -- {\color{orange} example} (default)
+ \item [\docoption{uline}] underlined text -- \uline{example}
+ \item [\docoption{uuline}] double underlined text -- \uuline{example}
+ \item [\docoption{uwave}] wavy underlined text -- \uwave{example}
+ \item [\docoption{dashuline}] dashed underlined text -- \dashuline{example}
+ \item [\docoption{dotuline}] dotted underlined text -- \dotuline{example}
+ \item [\docoption{bf}] bold text -- \textbf{example}
+ \item [\docoption{it}] italic text -- \textit{example}
+ \item [\docoption{sl}] slanted text -- \textsl{example}
+ \item [\docoption{em}] emphasized text -- \emph{example}
\end{description}
The output of replaced text is a combination of added and deleted text, thus any change in their layout influences the layout of replaced text.
@@ -312,25 +351,25 @@ The output of replaced text is a combination of added and deleted text, thus any
\chinline{usepackage_deletedmarkup_changes}
-The \choption{deletedmarkup} option chooses a predefined visual markup of deleted texty.
+The \docoption{deletedmarkup} option chooses a predefined visual markup of deleted texty.
The default markup is chosen if no explicit markup is given.
-The option \choption{deletedmarkup} overwrites the markup chosen with \choption{markup}.
+The option \docoption{deletedmarkup} overwrites the markup chosen with \docoption{markup}.
The following values for \emph{deletedmarkup} are defined:
\begin{description}
- \item [\choption{sout}] striked out text -- \sout{example} (default)
- \item [\choption{xout}] crossed out text -- \xout{example}
- \item [\choption{colored}] no text markup, just coloring -- {\color{orange} example}
- \item [\choption{uline}] underlined text -- \uline{example}
- \item [\choption{uuline}] double underlined text -- \uuline{example}
- \item [\choption{uwave}] wavy underlined text -- \uwave{example}
- \item [\choption{dashuline}] dashed underlined text -- \dashuline{example}
- \item [\choption{dotuline}] dotted underlined text -- \dotuline{example}
- \item [\choption{bf}] bold text -- \textbf{example}
- \item [\choption{it}] italic text -- \textit{example}
- \item [\choption{sl}] slanted text -- \textsl{example}
- \item [\choption{em}] emphasized text -- \emph{example}
+ \item [\docoption{sout}] striked out text -- \sout{example} (default)
+ \item [\docoption{xout}] crossed out text -- \xout{example}
+ \item [\docoption{colored}] no text markup, just coloring -- {\color{orange} example}
+ \item [\docoption{uline}] underlined text -- \uline{example}
+ \item [\docoption{uuline}] double underlined text -- \uuline{example}
+ \item [\docoption{uwave}] wavy underlined text -- \uwave{example}
+ \item [\docoption{dashuline}] dashed underlined text -- \dashuline{example}
+ \item [\docoption{dotuline}] dotted underlined text -- \dotuline{example}
+ \item [\docoption{bf}] bold text -- \textbf{example}
+ \item [\docoption{it}] italic text -- \textit{example}
+ \item [\docoption{sl}] slanted text -- \textsl{example}
+ \item [\docoption{em}] emphasized text -- \emph{example}
\end{description}
The output of replaced text is a combination of added and deleted text, thus any change in their layout influences the layout of replaced text.
@@ -342,16 +381,16 @@ The output of replaced text is a combination of added and deleted text, thus any
\chinline{usepackage_highlightmarkup_changes}
-The \choption{highlightmarkup} option chooses a predefined visual markup for highlighted text.
+The \docoption{highlightmarkup} option chooses a predefined visual markup for highlighted text.
The default markup is chosen if no explicit markup is given.
-The option \choption{highlightmarkup} overwrites the markup chosen with \choption{markup}.
+The option \docoption{highlightmarkup} overwrites the markup chosen with \docoption{markup}.
The following values for \emph{highlightmarkup} are defined:
\begin{description}
- \item [\choption{background}] markup by background color -- \colorbox{orange!30}{example} (default)
- \item [\choption{uuline}] double underlined text -- \uuline{example}
- \item [\choption{uwave}] wavy underlined text -- \uwave{example}
+ \item [\docoption{background}] markup by background color -- \colorbox{orange!30}{example} (default)
+ \item [\docoption{uuline}] double underlined text -- \uuline{example}
+ \item [\docoption{uwave}] wavy underlined text -- \uwave{example}
\end{description}
\chexample{usepackage_highlightmarkup_changes}
@@ -362,17 +401,17 @@ The following values for \emph{highlightmarkup} are defined:
\chinline{usepackage_commentmarkup_changes}
-The \choption{commentmarkup} option chooses a predefined visual markup for comments.
+The \docoption{commentmarkup} option chooses a predefined visual markup for comments.
The default markup is chosen if no explicit markup is given.
-The option \choption{commentmarkup} overwrites the markup chosen with \choption{markup}.
+The option \docoption{commentmarkup} overwrites the markup chosen with \docoption{markup}.
The following values for \emph{commentmarkup} are defined:
\begin{description}
- \item [\choption{todo}] comment as todo note, which is not added to list of todos \todo{example comment}(default)
- \item [\choption{margin}] comment in margin\marginpar{example comment}
- \item [\choption{footnote}] comment as footnote\footnote{example comment}
- \item [\choption{uwave}] wavy underlined text -- \uwave{example comment}
+ \item [\docoption{todo}] comment as todo note, which is not added to list of todos \todo{example comment}(default)
+ \item [\docoption{margin}] comment in margin\marginpar{example comment}
+ \item [\docoption{footnote}] comment as footnote\footnote{example comment}
+ \item [\docoption{uwave}] wavy underlined text -- \uwave{example comment}
\end{description}
\chexample{usepackage_commentmarkup_changes}
@@ -382,17 +421,17 @@ The following values for \emph{commentmarkup} are defined:
\chinline{usepackage_authormarkup_changes}
-The \choption{authormarkup} option chooses a predefined visual markup of the author's identification.
+The \docoption{authormarkup} option chooses a predefined visual markup of the author's identification.
The default markup is chosen if no explicit markup is given.
The following values for \emph{authormarkup} are defined:
\begin{description}
- \item [\choption{superscript}] superscripted text -- text\textsuperscript{author} (default)
- \item [\choption{subscript}] subscripted text -- text\textsubscript{author}
- \item [\choption{brackets}] text in brackets -- text(author)
- \item [\choption{footnote}] text in footnote -- text\footnote{author}
- \item [\choption{none}] no author identification
+ \item [\docoption{superscript}] superscripted text -- text\textsuperscript{author} (default)
+ \item [\docoption{subscript}] subscripted text -- text\textsubscript{author}
+ \item [\docoption{brackets}] text in brackets -- text(author)
+ \item [\docoption{footnote}] text in footnote -- text\footnote{author}
+ \item [\docoption{none}] no author identification
\end{description}
\chexample{usepackage_authormarkup_changes}
@@ -402,14 +441,14 @@ The following values for \emph{authormarkup} are defined:
\chinline{usepackage_authormarkupposition_changes}
-The \choption{authormarkupposition} option chooses the position of the author's identification.
+The \docoption{authormarkupposition} option chooses the position of the author's identification.
The default value is chosen if no explicit markup is given.
The following values for \emph{authormarkupposition} are defined:
\begin{description}
- \item [\choption{right}] right of the text -- text\textsuperscript{author} (default)
- \item [\choption{left}] left of the text -- \textsuperscript{author}text
+ \item [\docoption{right}] right of the text -- text\textsuperscript{author} (default)
+ \item [\docoption{left}] left of the text -- \textsuperscript{author}text
\end{description}
\chexample{usepackage_authormarkupposition_changes}
@@ -420,24 +459,37 @@ The following values for \emph{authormarkupposition} are defined:
\chinline{usepackage_authormarkuptext_changes}
-The \choption{authormarkuptext} option chooses the text that is used for the author's identification.
+The \docoption{authormarkuptext} option chooses the text that is used for the author's identification.
The default value is chosen if no explicit markup is given.
The following values for \emph{authormarkuptext} are defined:
\begin{description}
- \item [\choption{id}] author's id -- text\textsuperscript{id} (default)
- \item [\choption{name}] author's name -- text\textsuperscript{authorname}
+ \item [\docoption{id}] author's id -- text\textsuperscript{id} (default)
+ \item [\docoption{name}] author's name -- text\textsuperscript{authorname}
\end{description}
\chexample{usepackage_authormarkuptext_changes}
+
+\subsubsection{defaultcolor}
+
+\chinline{usepackage_defaultcolor_changes}
+
+The \docoption{defaultcolor} option defines the default color for authors, including the color for the default (anonymous) author.
+You can use colors of the \docpackage{xcolor} package.
+
+The default color is \emph{blue}.
+
+\chexample{usepackage_defaultcolor_changes}
+
+
\subsubsection{todonotes}
\chinline{usepackage_todonotes_changes}
-Options for the \chpackage{todonotes} package can be specified as parameters of the \choption{todonotes}-option.
+Options for the \docpackage{todonotes} package can be specified as parameters of the \docoption{todonotes}-option.
Several options or options with special characters have to be put in curly brackets.
\chexample{usepackage_todonotes_changes}
@@ -448,7 +500,7 @@ Several options or options with special characters have to be put in curly brack
\chinline{usepackage_truncate_changes}
-Options for the \chpackage{truncate} package can be specified as parameters of the \choption{truncate}-option.
+Options for the \docpackage{truncate} package can be specified as parameters of the \docoption{truncate}-option.
Several options or options with special characters have to be put in curly brackets.
\chexample{usepackage_truncate_changes}
@@ -458,7 +510,7 @@ Several options or options with special characters have to be put in curly brack
\chinline{usepackage_ulem_changes}
-Options for the \chpackage{ulem} package can be specified as parameters of the \choption{ulem}-option.
+Options for the \docpackage{ulem} package can be specified as parameters of the \docoption{ulem}-option.
Several options or options with special characters have to be put in curly brackets.
\chexample{usepackage_ulem_changes}
@@ -468,7 +520,7 @@ Several options or options with special characters have to be put in curly brack
\chinline{usepackage_xcolor_changes}
-Options for the \chpackage{xcolor} package can be specified as parameters of the \choption{xcolor}-option.
+Options for the \docpackage{xcolor} package can be specified as parameters of the \docoption{xcolor}-option.
Several options or options with special characters have to be put in curly brackets.
\chexample{usepackage_xcolor_changes}
@@ -485,11 +537,11 @@ Several options or options with special characters have to be put in curly brack
\chinline{added}
-The command \chcommand{added} marks newly added text.
+The command \doccommand{added} marks newly added text.
The new text is given in curly braces.
The optional argument contains key-value-pairs for author-id and comment.
-The author-id has to be defined using \chcommand{definechangesauthor}.
+The author-id has to be defined using \doccommand{definechangesauthor}.
If the comment contains special characters or spaces, use curly brackets to enclose the comment.
If a comment is given, the direct author markup at the changes text is omitted, because the author is printed in the comment.
@@ -502,10 +554,10 @@ If a comment is given, the direct author markup at the changes text is omitted,
\chinline{deleted}
-The command \chcommand{deleted} marks deleted text.
+The command \doccommand{deleted} marks deleted text.
The deleted text is given in curly braces.
-For the optional arguments see \chcommand{added} (\autoref{sec:ui:cmd:added}).
+For the optional arguments see \doccommand{added} (\autoref{sec:ui:cmd:added}).
\chexample{deleted}
\chresult{deleted}
@@ -516,10 +568,10 @@ For the optional arguments see \chcommand{added} (\autoref{sec:ui:cmd:added}).
\chinline{replaced}
-The command \chcommand{replaced} marks replaced text.
+The command \doccommand{replaced} marks replaced text.
The new and the replaced text are given in this order in curly braces.
-For the optional arguments see \chcommand{added} (\autoref{sec:ui:cmd:added}).
+For the optional arguments see \doccommand{added} (\autoref{sec:ui:cmd:added}).
The output of replaced text is a combination of added and deleted text, thus any change in their layout influences the layout of replaced text.
@@ -538,10 +590,10 @@ The output of replaced text is a combination of added and deleted text, thus any
\chinline{highlight}
-The command \chcommand{highlight} highlights text.
+The command \doccommand{highlight} highlights text.
The highlighted text is given in curly braces.
-For the optional arguments see \chcommand{added} (\autoref{sec:ui:cmd:added}).
+For the optional arguments see \doccommand{added} (\autoref{sec:ui:cmd:added}).
\chexample{highlight}
\chresult{highlight}
@@ -551,11 +603,11 @@ For the optional arguments see \chcommand{added} (\autoref{sec:ui:cmd:added}).
\chinline{comment}
-The command \chcommand{comments} adds a comment to the document.
+The command \doccommand{comments} adds a comment to the document.
The comment is given in curly braces.
The command has only one optional argument: a key-value-pair for the author-id.
-The author-id has to be defined using \chcommand{definechangesauthor}.
+The author-id has to be defined using \doccommand{definechangesauthor}.
The comments are numbered automatically, the number is printed in the comment.
@@ -574,46 +626,46 @@ The comments are numbered automatically, the number is printed in the comment.
\chinline{listofchanges}
-The command \chcommand{listofchanges} outputs a list or summary of changes.
+The command \doccommand{listofchanges} outputs a list or summary of changes.
The first \hologo{LaTeX}-run creates an auxiliary file, the second run uses the data of this file.
Therefore you need two \hologo{LaTeX}-runs for an up-to-date list of changes.
There are three optional arguments:
\begin{description}
- \item[\choption{style}] list style
- \item[\choption{title}] individual title
- \item[\choption{show}] markup types
+ \item[\docoption{style}] list style
+ \item[\docoption{title}] individual title
+ \item[\docoption{show}] markup types
\end{description}
\paragraph{style}
-The \choption{style} argument defines the layout of the list of changes.
+The \docoption{style} argument defines the layout of the list of changes.
Three styles are defined:
\begin{description}
- \item[\choption{list}] prints the list of changes like a list of figures (default)
- \item[\choption{summary}] prints the number of changes grouped by author
- \item[\choption{compactsummary}] same as \choption{summary} but entries with count 0 are omitted
+ \item[\docoption{list}] prints the list of changes like a list of figures (default)
+ \item[\docoption{summary}] prints the number of changes grouped by author
+ \item[\docoption{compactsummary}] same as \docoption{summary} but entries with count 0 are omitted
\end{description}
\paragraph{title}
-The \choption{title} argument is used to change the title for the list.
+The \docoption{title} argument is used to change the title for the list.
If you want to use special characters or spaces in the title, enclose it in curly braces.
\paragraph{show}
-The \choption{show} argument defines which types of change markup are shown in the list of changes.
+The \docoption{show} argument defines which types of change markup are shown in the list of changes.
You can combine the values using the \texttt{|} character.
For example if you want to show all additions and deletions, use \texttt{show=added|deleted}.
The following values are defined:
\begin{description}
- \item[\choption{all}] show all types (default)
- \item[\choption{added}] show only additions
- \item[\choption{deleted}] show only deletions
- \item[\choption{replaced}] show only replacements
- \item[\choption{highlight}] show only highlights
- \item[\choption{comment}] show only comments
+ \item[\docoption{all}] show all types (default)
+ \item[\docoption{added}] show only additions
+ \item[\docoption{deleted}] show only deletions
+ \item[\docoption{replaced}] show only replacements
+ \item[\docoption{highlight}] show only highlights
+ \item[\docoption{comment}] show only comments
\end{description}
\chexample{listofchanges}
@@ -628,7 +680,7 @@ The following values are defined:
\chinline{definechangesauthor}
-The command \chcommand{definechangesauthor} defines a new author for changes.
+The command \doccommand{definechangesauthor} defines a new author for changes.
You have to define a unique author's id, special characters or spaces are not allowed within the author's id.
You may define a corresponding color and the author's name.
@@ -651,8 +703,8 @@ The package predefines one anonymous author without id.
\chinline{setaddedmarkup}
-The command \chcommand{setaddedmarkup} defines the layout of added text.
-The default markup is colored text, or the markup set with the option \choption{markup} respectively \choption{addedmarkup}.
+The command \doccommand{setaddedmarkup} defines the layout of added text.
+The default markup is colored text, or the markup set with the option \docoption{markup} respectively \docoption{addedmarkup}.
Values for definition:
@@ -670,8 +722,8 @@ The output of replaced text is a combination of added and deleted text, thus any
\chinline{setdeletedmarkup}
-The command \chcommand{setdeletedmarkup} defines the layout of deleted text.
-The default markup is striked-out, or the markup set with the option \choption{markup} respectively \choption{deletedmarkup}.
+The command \doccommand{setdeletedmarkup} defines the layout of deleted text.
+The default markup is striked-out, or the markup set with the option \docoption{markup} respectively \docoption{deletedmarkup}.
Values for definition:
@@ -689,15 +741,15 @@ The output of replaced text is a combination of added and deleted text, thus any
\chinline{sethighlightmarkup}
-The command \chcommand{sethighlightmarkup} defines the layout of highlighted text.
-The default markup is via a background color, or the markup set with the option \choption{markup} respectively \choption{highlightmarkup}.
+The command \doccommand{sethighlightmarkup} defines the layout of highlighted text.
+The default markup is via a background color, or the markup set with the option \docoption{markup} respectively \docoption{highlightmarkup}.
Values for definition:
\begin{itemize}
\item any \hologo{LaTeX}-commands
\item highlighted text can be used with ``\#1''
- \item \chpackage{ifthenelse} boolean test for colored text ``\chcommand{isColored}''
+ \item \docpackage{ifthenelse} boolean test for colored text ``\doccommand{isColored}''
\item author's color can be used with color ``authorcolor''
\end{itemize}
@@ -708,8 +760,8 @@ Values for definition:
\chinline{setcommentmarkup}
-The command \chcommand{setcommentmarkup} defines the layout of comments.
-The default markup is a margin note, or the markup set with the option \choption{markup} respectively \choption{commentmarkup}.
+The command \doccommand{setcommentmarkup} defines the layout of comments.
+The default markup is a margin note, or the markup set with the option \docoption{markup} respectively \docoption{commentmarkup}.
Values for definition:
@@ -718,8 +770,8 @@ Values for definition:
\item comment can be used with ``\#1''
\item author's id can be used with ``\#2''
\item author output (id or name) can be used with ``\#3''
- \item \chpackage{ifthenelse} boolean test for anonymous author ``\chcommand{isAnonymous}''
- \item \chpackage{ifthenelse} boolean test for colored text ``\chcommand{isColored}''
+ \item \docpackage{ifthenelse} boolean test for anonymous author ``\doccommand{isAnonymous}''
+ \item \docpackage{ifthenelse} boolean test for colored text ``\doccommand{isColored}''
\item author's color can be used with color ``authorcolor''
\item comment count of the autor can be used with counter ``authorcommentcount''
\end{itemize}
@@ -731,7 +783,7 @@ Values for definition:
\chinline{setauthormarkup}
-The command \chcommand{setauthormarkup} defines the layout of the author's markup in the text.
+The command \doccommand{setauthormarkup} defines the layout of the author's markup in the text.
The default markup is a superscripted author's text.
Values for definition:
@@ -748,14 +800,14 @@ Values for definition:
\chinline{setauthormarkupposition}
-The command \chcommand{setauthormarkupposition} defines the position of the author's markup relative to the changed text.
+The command \doccommand{setauthormarkupposition} defines the position of the author's markup relative to the changed text.
The default position is right of the changed text.
The following values for \emph{authormarkupposition} are defined:
\begin{description}
- \item [\choption{right}] right of the text -- text\textsuperscript{author} (default)
- \item [\choption{left}] left of the text -- \textsuperscript{author}text
+ \item [\docoption{right}] right of the text -- text\textsuperscript{author} (default)
+ \item [\docoption{left}] left of the text -- \textsuperscript{author}text
\end{description}
\chexample{setauthormarkupposition}
@@ -765,14 +817,14 @@ The following values for \emph{authormarkupposition} are defined:
\chinline{setauthormarkuptext}
-The command \chcommand{setauthormarkuptext} defines the text for the author's markup.
+The command \doccommand{setauthormarkuptext} defines the text for the author's markup.
The default markup is the author's id.
The following values for \emph{authormarkuptext} are defined:
\begin{description}
- \item [\choption{id}] author's id -- text\textsuperscript{id} (default)
- \item [\choption{name}] author's name -- text\textsuperscript{authorname}
+ \item [\docoption{id}] author's id -- text\textsuperscript{id} (default)
+ \item [\docoption{name}] author's name -- text\textsuperscript{authorname}
\end{description}
\chexample{setauthormarkuptext}
@@ -783,8 +835,8 @@ The following values for \emph{authormarkuptext} are defined:
\chinline{settruncatewidth}
-The command \chcommand{settruncatewidth} sets the width of the truncation in the list of changes to the given width.
-The default width is \texttt{0.6}\chcommand{textwidth}.
+The command \doccommand{settruncatewidth} sets the width of the truncation in the list of changes to the given width.
+The default width is \texttt{0.6}\doccommand{textwidth}.
\chexample{settruncatewidth}
@@ -794,8 +846,8 @@ The default width is \texttt{0.6}\chcommand{textwidth}.
\chinline{setsummarywidth}
-The command \chcommand{setsummarywidth} sets the width of the list of changes in summary style to the given width.
-The default width is \texttt{0.3}\chcommand{textwidth}.
+The command \doccommand{setsummarywidth} sets the width of the list of changes in summary style to the given width.
+The default width is \texttt{0.3}\doccommand{textwidth}.
\chexample{setsummarywidth}
@@ -805,17 +857,34 @@ The default width is \texttt{0.3}\chcommand{textwidth}.
\chinline{setsummarytowidth}
-The command \chcommand{setsummarytowidth} sets the width of the list of changes in summary style to the width of the given text.
+The command \doccommand{setsummarytowidth} sets the width of the list of changes in summary style to the width of the given text.
\chexample{setsummarytowidth}
+\chnewcmd{setlocextension}
+
+\chinline{setlocextension}
+
+The command \doccommand{setlocextension} sets the extension of the auxiliary file for the list of changes (loc-file\footnote{%
+ ``loc'' stands for ``list of changes''.
+}).
+The default extension is ``\texttt{loc}''.
+
+In the example, the loc-file for ``\texttt{foo.tex}'' would be named ``\texttt{foo.listofchanges}'' resp.\ ``\texttt{foo.lochg}'' instead of the default name ``\texttt{foo.loc}''.
+
+\chexample{setlocextension}
+
+\chimportant{Do not use a \hologo{LaTeX} standard file extension, such as ``toc'' or ``lof'', as this would collide with the normal \hologo{LaTeX} run.}
+
+
+
\chnewcmd{setsocextension}
\chinline{setsocextension}
-The command \chcommand{setsocextension} sets the extension of the auxiliary file for the summary of changes (soc-file\footnote{%
+The command \doccommand{setsocextension} sets the extension of the auxiliary file for the summary of changes (soc-file\footnote{%
``soc'' stands for ``summary of changes''.
}).
The default extension is ``\texttt{soc}''.
@@ -824,7 +893,7 @@ In the example, the soc-file for ``\texttt{foo.tex}'' would be named ``\texttt{f
\chexample{setsocextension}
-\chimportant{Do not use a \hologo{LaTeX} standard file extension, such as ``toc'' or ``loc'', as this would collide with the normal \hologo{LaTeX} run.}
+\chimportant{Do not use a \hologo{LaTeX} standard file extension, such as ``toc'' or ``lof'', as this would collide with the normal \hologo{LaTeX} run.}
@@ -832,21 +901,21 @@ In the example, the soc-file for ``\texttt{foo.tex}'' would be named ``\texttt{f
\subsection{Used packages}
\label{sec:ui:packages}
-The \chpackage{changes}-package uses already existing packages for it's functions.
+The \docpackage{changes}-package uses already existing packages for it's functions.
You will find detailed description of the packages in their distributions.
-The following packages are always required and have to be installed for the \chpackage{changes}-package:
+The following packages are always required and have to be installed for the \docpackage{changes}-package:
\begin{description}
- \item [xifthen] provides an enhanced \chcommand{if}-command as well as a \texttt{while}-loop
- \item [xkeyval] provides options with key-value-pairs
+ \item [etoolbox] provides an enhanced \doccommand{if}-commands, \emph{bools}, or list operations
+ \item [truncate] truncation of texts (used for list of changes)
+ \item [xkeyval] provides key-value-lists for parameters
\item [xstring] improves string operations
\end{description}
The following packages are sometimes required and have to be installed if used by the corresponding option:
\begin{description}
- \item [pdfcolmk] loaded if colored text is used for markup (default markup); solves the problem of colored text and page breaks (with pdflatex)
\item [todonotes] loaded if comments are layouted as todo notes (default markup)
- \item [ulem] loaded if text has to be striked or exed out (default markup)
+ \item [ulem] loaded if text has to be striked, wavylined or exed out (default markup)
\item [xcolor] loaded if colored text is used for markup (default markup)
\end{description}
@@ -917,18 +986,18 @@ There is a problem of typesetting footnotes or margin notes in special environme
Avoid such markup when using these environments.
-\subsection{The \chpackage{ulem} package}
+\subsection{The \docpackage{ulem} package}
-I am using the \chpackage{ulem} package for striking out text as default.
+I am using the \docpackage{ulem} package for striking out text as default.
This leads to problems with some commands or environments, e.g.
\begin{itemize}
\item in math mode
- \item when using the \chpackage{siunitx} package
- \item when using the \chcommand{citet} or \chcommand{citep} command
+ \item when using the \docpackage{siunitx} package
+ \item when using the \doccommand{citet} or \doccommand{citep} command
\end{itemize}
-In that case there are only a few good solutions, the best way is to avoid using the \chpackage{ulem} package by defining your own deletion markup.
+In that case there are only a few good solutions, the best way is to avoid using the \docpackage{ulem} package by defining your own deletion markup.
See
\begin{itemize}
@@ -937,12 +1006,23 @@ See
\end{itemize}
+\subsection{Command already defined}
+
+Some package define the markup commands as well, especially \doccommand{comment} and \doccommand{highlight} are not exclusively used by \docpackage{changes}.
+
+If needed, \docpackage{changes} can prefix it's markup commands in order to avoid name clashes.
+This is set with the option \docoption{commandnameprefix}, see \autoref{sec:ui:options:commandnameprefix} for the documentation.
+
+In order for this to work, the \docpackage{changes} package has to be used after the other package defining the command.
+
+
+
%^^A -- Authors -------------------------------------------------------------
\cleardoublepage
\section{Authors}
\label{sec:authors}
-Several authors contributed to the \chpackage{changes}-package.
+Several authors contributed to the \docpackage{changes}-package.
Many bugs and problems were solved or their solution inspired via de.comp.text.tex.
Thanks.
@@ -982,7 +1062,7 @@ If you are interested in planned new features, please see
\cleardoublepage
\section{Distribution, Copyright, License}
-Copyright 2007-2020 Ekkart Kleinod (\href{mailto:ekleinod@edgesoft.de}{ekleinod@edgesoft.de})
+Copyright 2007-2021 Ekkart Kleinod (\href{mailto:ekleinod@edgesoft.de}{ekleinod@edgesoft.de})
This work may be distributed and/or modified under the conditions of the \hologo{LaTeX} Project Public License, either version~1.3 of this license or any later version.
The latest version of this license is in \url{http://www.latex-project.org/lppl.txt} and version~1.3 or later is part of all distributions of \hologo{LaTeX} version 2005/12/01 or later.