summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/wtref/wtref.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-06-16 03:02:40 +0000
committerNorbert Preining <norbert@preining.info>2020-06-16 03:02:40 +0000
commit305bf45bf758ea76ec5be2a737bd8eb491f68921 (patch)
treea0d6ad7bdfc7a258d831c6dd746484263ff66b10 /macros/latex/contrib/wtref/wtref.tex
parent539648a9305d6107a588ecdff34b5cdce48fb930 (diff)
CTAN sync 202006160302
Diffstat (limited to 'macros/latex/contrib/wtref/wtref.tex')
-rw-r--r--macros/latex/contrib/wtref/wtref.tex173
1 files changed, 173 insertions, 0 deletions
diff --git a/macros/latex/contrib/wtref/wtref.tex b/macros/latex/contrib/wtref/wtref.tex
new file mode 100644
index 0000000000..bfd9bfa913
--- /dev/null
+++ b/macros/latex/contrib/wtref/wtref.tex
@@ -0,0 +1,173 @@
+%#!pdflatex
+\documentclass[a4paper]{article}
+
+\usepackage{enumitem}
+\usepackage{shortvrb}
+
+\MakeShortVerb{\|}
+\newcommand{\PkgName}[1]{\textsf{#1}}
+\newcommand{\ThisPkg}{\PkgName{WTRef}}
+\newcommand{\Meta}[1]{$\langle$\mbox{}\textit{#1}\mbox{}$\rangle$}
+\newenvironment{syntax}{\begin{quote}\small}{\end{quote}}
+
+\title{The {\ThisPkg} Package (v0.4.0)}
+\author{Takuto ASAKURA (wtsnjp)}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+WT Series collects macros which are useful to create {\LaTeX} documents.
+{\ThisPkg} package is a part of this WT Series that extends cross-reference
+system of {\LaTeX}. It makes enable to divide namespace and scope, further
+arrows users to customise reference formats. {\LaTeXe} on any kind of {\TeX}
+engine is supported. The package requires Package \PkgName{xparse} and
+\PkgName{xkeyval}.
+\end{abstract}
+
+\section{System Requirements}
+
+System requirements of {\ThisPkg} are shown bellow:
+%
+\begin{itemize}
+\item {\TeX} engine: any engine
+\item {\TeX} format: \LaTeXe
+\item Document class: any class
+\item Required packages: \PkgName{xparse} and \PkgName{xkeyval}
+\end{itemize}
+
+\section{Loading the {\ThisPkg} Package}
+
+To use {\ThisPkg} package, load \texttt{wtref.sty} file with |\usepackage| command in preamble.
+No package option is available.
+%
+\begin{syntax}
+|\usepackage{wtref}|
+\end{syntax}
+
+\section{Cross-Reference Commands}
+
+\subsection{Definition of New Cross-Reference Commands}
+
+|\newref| command creates a set of cross-reference commands. This command can only be used
+in preamble.
+%
+\begin{syntax}
+|\newref[|\Meta{options}|]{|\Meta{ref types}|}|
+\end{syntax}
+%
+\Meta{ref types} are comma-separated list of \Meta{ref type}. All characters of \Meta{ref type}
+must be able to use in control sequence (only ordinary alphabet is recommended) and can not be
+empty. Notice that leading and trailing spaces and successive spaces arround commas are ignored.
+
+|\newref| command defines two commands: |\|\Meta{ref type}|label|, |\|\Meta{ref type}|ref|.
+In this document, the formar are called \textbf{label commands} and the latter are called
+\textbf{reference commands}. |\newref| command overwrites existing commands, so \Meta{ref name}
+should be decided carefully.
+
+In \Meta{options}, you can set following parameters by key-value list:
+%
+\begin{description}[font=\normalfont]
+\item[|namespace=|\Meta{string}]
+Set \Meta{namespace} to ``\Meta{string}:''. If neither |namespace| nor |nonamespace| are
+specified, or in case \Meta{string} of |namespace| is empty, \Meta{namespace} is set to
+``\Meta{ref type}:''.
+%
+\item[|nonamespace|]
+Set \Meta{namespace} to empty. That is to say, invalidation of function that dividing
+namespace. It should be noted that you can specify value for |nonamespace| and that
+will not make any errors, but the value will simply be ignored.
+%
+\item[|scope=|\Meta{counter}]
+Specify counter which used as scope. You can specify any {\LaTeX} counter to \Meta{counter}
+but one which has uniqueness in a document is desirable. This key sets \Meta{scope} to
+``|\the|\Meta{counter}:''.
+\end{description}
+%
+These optional settings apply to all cross-referece commands relate to \Meta{ref type}
+in specified \Meta{ref types}.
+
+Identically, if any keys do not specified in \Meta{options}, \Meta{namespace} is set to
+``\Meta{ref type}'' and \Meta{scope} is set to empty. In other words, the function of
+namespace is active and function of scope is inactive as default.
+
+\subsection{Label Commands}
+
+\subsubsection{Function and Usage}
+
+Label commands are used to create new labels. Usage of those are same to |\label| command
+of standard {\LaTeX}. Usage of |\exlabel| is shown bellow as an example:
+%
+\begin{syntax}
+|\exlabel{|\Meta{label}|}|
+\end{syntax}
+
+\subsubsection{Internal Processing}
+
+Label commands finaly are expanded to following format:
+%
+\begin{syntax}
+|\label{|\Meta{namespace}\Meta{scope}\Meta{label}|}|
+\end{syntax}
+
+\subsection{Reference Commands}
+
+Reference commands print contents of counters which labeled by label commands in specified
+formats. Usage of |\exref| is shown bellow as an example:
+%
+\begin{syntax}
+|\exref[|\Meta{the scope}|]{|\Meta{label list}|}|
+\end{syntax}
+
+The option argument \Meta{the scope} can be ommited when refering label exists in the
+same scope. You can refer outside of scope by writing down the output of proper
+|\the|\Meta{counter}. Notice that if the function of scope is inactive
+(i.e. in case |scope| key does not specified in \Meta{options} of |\newref|), this argument
+is always unnecessary, and in other words it will be ignored all the time.
+
+In argument \Meta{label list}, plural labels can be written in comma-separated. Note that
+leading and trailing spaces and successive spaces arround commas are ignored. If actually
+plural labels are filled in, pertinent counters should be printed out in comma-separate
+form in default. You can change this format flexibly with |\setrefstyle| command.
+
+\section{Setting Referece Style}
+
+The output format of reference commands can be customised with |\setrefstyle| command.
+The syntax of |\setrefstyle| is shown bellow:
+%
+\begin{syntax}
+|\setrefstyle{|\Meta{ref types}|}{|\Meta{options}|}|
+\end{syntax}
+
+The |\setrefstyle| command can be used any place of {\LaTeX} document (not only preamble),
+and change reference format locally.
+
+In \Meta{options}, you can set following parameters by key-value list:
+%
+\begin{description}[font=\normalfont]
+\item[|refcmd=|\Meta{command}]
+Specified \Meta{command} repeated for the number of labels which filled in \Meta{label list}
+time. String |#1| in \Meta{command} may be replaced into appropriate label name. The default
+value is |\ref{#1}|.
+%
+\item[|sep=|\Meta{command}]
+Specified \Meta{command} is output as a separater of each |refcmd| when more than three
+labels filled in \Meta{label list}. Notice that last one separater is given by |last sep|.
+The default value is |{,\space}|.
+%
+\item[|last sep|(|=|\Meta{command})]
+Specified \Meta{command} is output as a last separater when plura labels filled in
+\Meta{label list}. Behind the |=| can be ommited, and in that case |last sep| is set
+to identical value of |sep| (and this is the default).
+%
+\item[|prefix=|\Meta{command}]
+Specified \Meta{command} put out first when referece command used. The default value is |{}|.
+%
+\item[|suffix=|\Meta{command}]
+Specified \Meta{command} put out last when referece command used. The default value is |{}|.
+\end{description}
+%
+Parameters which do not set explicitly will not be changed.
+
+\end{document}