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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
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}
|
