ltxkeys (17oct12)

git-svn-id: svn://tug.org/texlive/trunk@28000 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 55 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide-table1.tex b/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide-table1.tex
new file mode 100644
index 00000000000..7a5a614c4cf
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide-table1.tex
@@ -0,0 +1,55 @@
+\documentclass[
+  use-a4-paper,use-10pt-font,final-version,UK-English,
+  no-hyperref-msg,wrapquote,subsidfile,verbose=false
+]{amltxdoc}
+
+\makeatletter
+
+\InputIfFileExists{ltxkeys-guide.cfg}{}{%
+  \ltxmsg@err{No file 'ltxkeys-guide.cfg' or wrong path}\@ehc
+}
+
+\begin{document}
+
+\defltablenote{ltxkeys-1}{%
+  The speed of compilation may be affected by this option, but it is recommended at the pre-production stages of developing keys. The option provide some trace functionality and enables the user to, among other things, follow the progress of the \latex run and to see if a key has been defined and/or set/executed more than once in the current run. The \stform+ of the command \ffx'{\ltxkeysdefinekeys} will always flag an error if a key is being defined twice, irrespective of the state of the package option \fx{verbose}. The \textkey variants (unlike the \textnewkey variants) of key-defining commands don't have this facility, and it may be desirable to know if and when an existing key is being redefined.
+}
+\defltablenote{ltxkeys-2}{%
+  Wherever the \qsemicolon is indicated as a list parser in this guide, it can be replaced by any user-specified one character parser via the package option \fx{keyparser}. To avoid confusing the user-supplied parser with internal parsers, it is advisable to enclose the chosen character in curly braces. The braces will be stripped off internally. Please note that some of the characters that may be passed as a list parser may indeed be active; be careful to make them innocent before using them as a list/key parser. My advice is that the user sticks with the \qsemicolon as the key parser: the chances of it being made active by any package is minimal. If you have the chosen parser as literals in the callbacks of your keys, they have to be enclosed in curly braces.
+}
+\defltablenote{ltxkeys-3}{%
+  The key-setting commands are \ffx'{\ltxkeyssetkeys,\ltxkeyssetrmkeys,\ltxkeyssetaliaskey}. If you must nest these commands beyond level~4, you have to raise the \fx{keydepthlimit} as a package option. The option \fx{keystacklimit} is an alias for \fx{keydepthlimit}.
+}
+\defltablenote{4}{%
+  The use of an empty prefix will normally result from explicitly declaring the prefix as \fx{[]}, rather than leaving it undeclared. Undeclared prefixes assume the default value of \fx{KV}. An empty family will result from submitting the family as empty balanced curly braces \fx{{}}. If keys lack prefix and/or family, there is a strong risk of confusing key macros/functions. For example, without a prefix and/or family, a key named \fx{width} will have a key macro defined as \fx{\width}, which portents sufficient danger.
+}
+
+\extrarowheight=2pt
+\arrayrulecolor{yellow}
+\colone3cm\coltwo2.0cm
+\colthree=\dimexpr\textwidth-(\colone+\coltwo+1.5cm)\relax
+\coltotal=\dimexpr\colone+\coltwo+\colthree\relax
+
+\begingroup\small
+\begin{tabularx}{\linewidth}{|m{3cm}|m{2cm}|X|}
+\caption{Package options\xwmlabel{tab:pkgoptions}}\\\hline
+\rowcolor{pink}
+\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
+\endfirsthead
+\hline
+\multicolumn{3}{|l|}{\emph{Continued from last page}}\\\hline
+\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
+\endhead
+\multicolumn{3}{|r|}{\emph{Continued on next page}}\\\hline
+\endfoot
+\hline
+\endlastfoot
+\fx{verbose} & \hx{false} & The global boolean switch that determines if information should be logged in the transcript for some tasks in the package. \useltablenote[tab:pkgoptions:note1]{ltxkeys-1}\\\hline
+\fx{keyparser} & \texttt{;} & The list parser used by some internal loops in defining keys.\useltablenote[tab:pkgoptions:note2]{ltxkeys-2}\\\hline
+\fx{keydepthlimit} & \hx{4} & This is used to guard against erroneous infinite re-entrance of the package's key-setting commands. The default value of~4 means that neither of these commands can ordinarily be nested beyond level~4.\useltablenote[tab:pkgoptions:note3]{ltxkeys-3}\\\hline
+\fx{reservenopath} & \hx{false} & The \quoted{path} (or roots or bases) of a key is the combination of key prefix, key family and macro prefix, but when dealing with \quoted{path keys} (see \sref{sec:pathkeys}) the term excludes the macro prefix. These can be reserved and unreserved by any user by the tools of \sref{sec:reservedpath}. Subsequent users can, at their own risk, override all previously reserved paths by enabling the package's boolean option \fx{reservenopath}.\\\hline
+\fx{allowemptypath} & \hx{false} & Allow the use of empty key prefix and family. This isn't advisable but some pre-existing packages might have used empty key prefixes and families. \useltablenote[tab:pkgoptions:note4]{4}
+\end{tabularx}
+\endgroup
+
+\end{document} 
\ No newline at end of file