summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/modroman/modroman-en.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-04-09 23:57:50 +0000
committerKarl Berry <karl@freefriends.org>2010-04-09 23:57:50 +0000
commitbc760bf42782cd2acdebbd360ceca4a5609c658a (patch)
tree7bc3662ef867522c199595929dfe2d71bc15aecd /Master/texmf-dist/doc/latex/modroman/modroman-en.tex
parentb00d598c405e2f58e2be6d3511013787b40954dd (diff)
modroman 1 (9apr10)
git-svn-id: svn://tug.org/texlive/trunk@17778 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/modroman/modroman-en.tex')
-rw-r--r--Master/texmf-dist/doc/latex/modroman/modroman-en.tex462
1 files changed, 462 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/modroman/modroman-en.tex b/Master/texmf-dist/doc/latex/modroman/modroman-en.tex
new file mode 100644
index 00000000000..d1945dc6ff7
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/modroman/modroman-en.tex
@@ -0,0 +1,462 @@
+%%
+%% This is file `modroman-en.tex',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% modroman.dtx (with options: `doc,en')
+%%
+%% This is a generated file.
+%%
+%% Copyright (C) 2003, 2004, 2008, 2010 by Yvon Henel,
+%% dit «le TeXnicien de surface» <le.texnicien.de.surface@wanadoo.fr>
+%%
+%% This file may be distributed and/or modified under the conditions of
+%% the LaTeX Project Public License, either version 1.2 of this license
+%% or (at your option) any later version. The latest version of this
+%% license is in:
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% and version 1.2 or later is part of all distributions of LaTeX version
+%% 1999/12/01 or later.
+%%
+\documentclass[a4paper]{ltxdoc}
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{modroman}[2010/04/09]
+\usepackage{xspace}
+\usepackage{array}
+\usepackage{ifthen}
+\usepackage{MODRdoctools}
+\IfFileExists{lmodern.sty}{\usepackage{lmodern}}{}
+\usepackage[frenchb,english]{babel}
+\usepackage[colorlinks=true,
+ linkcolor=blue,
+ urlcolor=blue,
+ citecolor=blue]{hyperref}
+
+\begin{document}
+\renewcommand\thepage{\textit{\modroman{page}}}
+\title{The package \textsf{modroman}\thanks{
+ This document corresponds to the file
+ \textsf{modroman}~\fileversion, dated \filedate.}}
+\author{\href{mailto:le.texnicien.de.surface@wanadoo.fr}{Le \TeX
+ nicien de surface}}
+
+\maketitle
+
+\begin{abstract}
+\begin{otherlanguage}
+{french}
+\bfseries{}
+ Documentation anglaise pour l'utilisateur final de l'extension
+ \Pkg{modroman}.
+ La documentation française est disponible sous le nom de
+ \texttt{modroman-fr}.
+\end{otherlanguage}
+
+\vspace{6pt}
+\noindent\hrulefill
+\vspace{6pt}
+
+This is the English documentation of \Pkg{modroman} for the final
+user.
+
+\MODRdescroen
+\end{abstract}
+
+\tableofcontents{}
+
+\section{Introduction}
+
+\subsection{Motivation}
+
+The ways of writing numbers with roman numerals are more diverse than
+it could be thought when one considers the \TeX{} \cs{romannumeral}
+and \LaTeX{} \cs{roman} and \cs{Roman}. Many other forms were used at
+a time or another through history. I saw, many years ago, the form
+\nbshortroman{8} in a manuscript. The first versions \TO from 0.1 to
+0.4\TF of this package provided just that form, with, user willing,
+the use of a~|u| to denote a group of~5 as in `xuij' for~17.
+
+The interested reader could cast a glance on the page wikipedia
+devotes to roman numerals to see that the world is not always as
+simple as one would like it to be.
+
+\subsection{
+Technical Remarks
+}
+
+The code of the first versions enable one to number the pages with
+\emph{modified} roman numerals but one could not then use the
+reference tools such as \cs{label} and \cs{ref} or even hope to see
+the page numbers correctly written in the table of contents.
+
+As the years go by I don't really become more clever but, for I read
+not a few documentations of packages, I end with knowing a bit more
+and I happen to stumble upon the solution to a problem I had just
+caught a glimpse of.
+
+I don't forget what I owe to T.~\textsc{Lachand}-\textsc{Robert}
+in~\cite{tlachand} -- numerous ideas, detailed examples, clear
+explanations -- but I now use other sources --
+\texttt{source2e}~\cite{source2e} to be accurate. That is where I have
+found the \emph{trick} which enables me to provide this new version of
+\Pkg{modroman}. The reader who would like to know more should have a
+look at the definition of the macro \cs{Roman} and its auxiliary
+macros.
+
+While rewriting the code I happen to understand that I was able to go
+a bit farther than I have gone previously without a tremendous extra
+cost. That's why one will now find more macros and more presentations
+of the roman numerals and an additional macro.
+
+This version~1 keeps the compatibility with the previous version but
+the code has been completely rewritten and the package now provides to
+the user in addition to \cs{modroman} and \cs{modromannumeral} about
+fifteen other macros.
+
+However, the main change introduced by this version~1 is the fact that
+from now on \cs{modroman} \TO and its pals \TF is purely expandable
+\TO see page~\pageref{puredev} for more details. One can then use it
+to number pages and obtain the correct thing in the table of content
+-- which was not the case until now. Caution, I do \emph{not} say that
+\cs{modromannumeral} is purely expandable -- it is not.
+
+\subsection{
+Purely Expandable Macros
+}
+
+One could, if one understands French, read the thread
+`\foreignlanguage{frenchb}{test de développabilité pure ?}' on the
+news group \texttt{fr.comp.text.tex} to see that that notion is not as
+simple as one could think at n-th sight \texttt{:-)} however, here,
+when I will say that a macro is `purely expandable' I will understand
+what follows.
+
+Let's assume that the macro \cs{thing} is such that
+\cs{thing}\marg{12} gives `xij' \TO does it ring a bell?\TF
+then\label{puredev}
+\begin{enumerate}
+\item the macro \cs{THING} defined by
+ |\edef|\BOP|\TRUC|\BOP|{|\BOP|\truc|\BOP|{|\BOP|12|\BOP|}|\BOP|}|
+ is such that:
+ \begin{enumerate}
+ \item \cs{THING} gives `xij' and
+ \item |\meaning\THING| gives `\texttt{macro:->xij}'
+ \end{enumerate}
+\item moreover, if one defines \cs{Axij} then the construct
+ |\csname| |A|\BOP|\truc|\BOP|{|\BOP|12|\BOP|}|\BOP|\endcsname|
+ truly calls the macro \cs{Axij}.
+\end{enumerate}
+
+\section{
+Usage
+}
+
+\subsection{
+The Macros
+}
+
+Macros the name of which ends with \texttt{numeral} are to be used as
+\TeX{} \cs{romannumeral}. They must be followed by a number and eat
+the spaces which are after it, e.~g.
+|\longromannumeral| \verb*+368 AND+ gives `\longromannumeral
+368 AND'.
+
+Macros the name of which begins with \cs{nb} take a number as argument
+such as |\nbLongRoman{127}| which gives `\nbLongRoman{127}'.
+
+Macros the name of which doesn't begin with \cs{nb} but ends with
+\texttt{roman} are used as \LaTeX{} \cs{roman}: their only argument is
+the name of a counter. With |\newcounter{machin}|,
+|\setcounter{machin}{124}|, |\shortroman{machin}| one obtains
+`\nbshortroman{124}'.
+
+In what follows \meta{nbr} denotes a number, \meta{ctr} denotes the
+\LaTeX{} name of a counter such as \texttt{page} or \texttt{chapter}.
+
+Here comes a presentation of all the macros available with this
+package. They are grouped by family where a family is defined with
+respect to the obtained presentation of roman numerals.
+
+After the macro's syntax, there will be \PD to mean that the macro is
+purely expandable \TO see page~\pageref{puredev}\TF, \LT to mean that
+it is used the \LaTeX{} way, \TX to mean that it is used as the \TeX{}
+\cs{romannumeral}.
+
+The examples are governed by the default options: \Option{jfinal},
+\Option{vpourv}, \Option{court}, \Option{min}.
+
+\subsubsection{
+shortroman
+Family
+}
+
+\begin{macro}{\shortroman}
+ \cs{shortroman}\marg{ctr} \PD \LT
+\end{macro}
+
+\begin{macro}{\shortromannumeral}
+ \cs{shortromannumeral} \meta{nbr} \TX
+\end{macro}
+
+\begin{macro}{\nbshortroman}
+ \cs{nbshortroman}\marg{nbr} \PD \LT
+\end{macro}
+
+\Exemples{shortroman}
+
+\subsubsection{
+longroman
+Family
+}
+
+\begin{macro}{\longroman}
+ \cs{longroman}\marg{ctr} \PD \LT
+\end{macro}
+
+\begin{macro}{\longromannumeral}
+ \cs{longromannumeral} \meta{nbr} \TX
+\end{macro}
+
+\begin{macro}{\nblongroman}
+ \cs{nblongroman}\marg{nbr} \PD \LT
+\end{macro}
+
+\Exemples{longroman}
+
+\subsubsection{
+LongRoman
+Family
+}
+
+\begin{macro}{\LongRoman}
+ \cs{LongRoman}\marg{ctr} \PD \LT
+\end{macro}
+
+\begin{macro}{\LongRomannumeral}
+ \cs{LongRomannumeral} \meta{nbr} \TX
+\end{macro}
+
+\begin{macro}{\nbLongRoman}
+ \cs{nbLongRoman}\marg{nbr} \PD \LT
+\end{macro}
+
+\Exemples{LongRoman}
+
+\subsubsection{
+roman
+Family
+}
+
+\TeX{} provides \cs{romannumeral} and \LaTeX{} \cs{roman}. I
+complete the family with \cs{nbroman}.
+
+\begin{macro}{\nbroman}
+ \cs{nbroman}\marg{nbr} \PD \LT
+\end{macro}
+
+\Exemples{roman}
+
+\subsubsection{
+Roman
+Family
+}
+
+\LaTeX{} provides \cs{Roman}. I complete the family with \cs{nbRoman} and
+\cs{Romannumeral}.
+
+\begin{macro}{\Romannumeral}
+ \cs{Romannumeral} \meta{nbr} \TX
+\end{macro}
+
+\begin{macro}{\nbRoman}
+ \cs{nbRoman}\marg{nbr} \PD \LT
+\end{macro}
+
+\Exemples{Roman}
+
+\subsubsection{
+modroman
+Family
+}
+
+The output of the macros \cs{modroman}, \cs{modromannumeral}, and
+\cs{nbmodroman} is determined by the chosen options. By default:
+
+\begin{macro}{\modroman}
+ \cs{modroman}\marg{ctr} $=$ \cs{shortroman}\marg{ctr} \PD \LT
+\end{macro}
+
+\begin{macro}{\modromannumeral}
+ \cs{modromannumeral}\meta{nbr} $=$ \cs{shortromannumeral}\meta{nbr} \TX
+\end{macro}
+
+\begin{macro}{\nbmodroman}
+ \cs{nbmodroman}\marg{nbr} $=$ \cs{nbshortroman}\marg{nbr} \PD \LT
+\end{macro}
+
+\Exemples{modroman}
+
+\subsubsection{
+Other macros
+}
+
+One can redefine the behaviour of families \cs{shortroman} and
+\cs{longroman} with the macro \cs{RedefineMRmdclxvij}.
+
+\begin{macro}{\RedefineMRmdclxvij}
+ \cs{RedefineMRmdclxvij}\oarg{ISOL}\BOP\marg{M}\BOP\marg{D}\BOP\marg{C}%
+ \BOP\marg{L}\BOP\marg{X}\BOP\marg{V}\BOP\marg{I}\BOP\marg{J}
+\end{macro}
+
+The above arguments determine the look of the roman numerals produced
+after \TO one should take care of the side effects and one would have
+to limit the scope of the redefinition ot a group if necessary\TF by
+the families \cs{shortroman}, \cs{longroman}, and, if it is linked to
+one of the two preceding, \cs{modroman}.
+
+The optional argument \meta{ISOL} gives the look of the isolated |i| \CAD the
+number~1. If one doesn't give the argument the look of the isolated
+|i| is the look of the non-final |i| determined by \meta{I}
+
+The look of the final~|i| is given by the argument \meta{J}. All other
+arguments give the look of the corresponding (lowercase) digit,
+e.~g. \meta{M} gives the look of~|m|.
+
+\begin{macro}{\printntimes}
+ \cs{printntimes}\marg{nbr}%
+\marg{text}
+\end{macro}
+
+Here are two examples using the macro.
+
+|$\ast$ \texttt{\printntimes{15}{*-*}} $\ast$|
+
+gives
+
+$\ast$ \texttt{\printntimes{15}{*-*}} $\ast$
+
+\bigskip
+
+|\newcommand\truc{\par\centering ***\par}|\par
+|\newcommand\saut{\par\noindent\hrulefill\par}|\par
+|\saut\texttt{\printntimes{5}{\truc}}\saut|
+
+gives
+
+\newcommand\truc{\par\centering ***\par}
+\newcommand\saut{\par\noindent\hrulefill\par}
+\saut\texttt{\printntimes{5}{\truc}}\saut
+
+\subsection{
+The Options
+}
+
+There exist -- since the version~0.2 -- options \Option{vpourv} and
+\Option{upourv}. The default option is \Option{vpourv} with which
+\cs{modromannumeral}|5| is written as `v'. With the option
+\Option{upourv} the same \cs{modromannumeral}|5| is written as `u'. It
+was a special requirement from \emph{one} person posting on
+\url{fr.comp.text.tex}. \emph{The (almost) French `vpourv' stands for
+ `v for v'.}
+
+For sake of symetry, I add, with this version~1, two
+antithetical options \Option{jfinal} -- final j -- the default, and
+\Option{ifinal} -- final i -- by which one can choose if the last~i of
+the number will be written as a~|j| or not.
+
+I add also two pairs of antithetic options. First \Option{min} \TO
+\CAD \emph{minuscule} lowercase, default option \TF and \Option{maj}
+\TO \CAD \emph{majuscule} uppercase\TF then \Option{court} \TO short,
+default option \TF and \Option{long}.
+
+Last, with this version~1, I add the option \Option{sansmod} --
+without modification -- which makes the macros of the \cs{modroman}
+family aliases of those of \cs{roman} family.
+
+The last five options determine the behaviour of the macros of the
+family \cs{modroman}.
+
+\DescribeOption{upourv}
+With that option, the roman numeral `v' is turn into an~`u' and one
+obtains, e.g., `xuij' for~17.
+
+\DescribeOption{vpourv}
+That option, enforced by default, is the opposite of the previous
+one. With it, one obtains \Exemple{17} for~17.
+
+The next three options appear with the version~1 of the package.
+
+\DescribeOption{jfinal}
+With that default option, if the processed number is greater than~1
+and if the last roman \emph{digit} is an~i then it is turned into
+a~j. See the examples above.
+
+\DescribeOption{ifinal}
+That option is the opposite of the previous one. When enforced, one
+obtains \romannumeral 17{} for~17.
+
+\DescribeOption{sansmod}
+With that option \cs{modroman}, \cs{modromannumeral} and
+\cs{nbmodroman} are just aliases -- obtained with \cs{let} -- of
+\cs{roman}, \cs{romannumeral}, and \cs{nbroman} respectively.
+
+If one choses options \Option{vpourv}, , \Option{court}, \Option{min},
+and \Option{ifinal} together, one enforces the option
+\Option{sansmod}.
+
+\bigskip
+
+The following table shows which family is linked to the \cs{modroman}
+family according to the chosen options when \Option{sansmod} is not
+enforced.
+
+\begin{center}
+ \begin{tabular}{|*{3}{c|}}\hline
+ & \Option{court} & \Option{long}\\ \hline
+ \Option{min} & \cs{shortroman} & \cs{longroman} \\ \hline
+ \Option{maj} & \cs{Roman} & \cs{LongRoman} \\ \hline
+ \end{tabular}
+\end{center}
+
+\input{MODRbiblio}
+
+\iffalse
+\newpage
+\section{
+Numbers from \nbmodroman{1} to \nbmodroman{1000}
+}
+
+\newcounter{machin}\setcounter{machin}{1}
+\noindent
+\whiledo{\value{machin}<1001}{%
+ \mbox{\arabic{machin} -- \shortroman{machin} -- \longroman{machin}
+ -- \LongRoman{machin}}\stepcounter{machin}\par\noindent}
+\newpage
+\fi
+\vspace*{\stretch{4}}
+\noindent\hrulefill
+\begin{center}
+In the preambule of this document, there is
+\\
+|\renewcommand\thepage{\textit{\modroman{page}}}|
+\\
+hence the page numbering.
+\end{center}
+\noindent\hrulefill
+
+\vspace*{\stretch{2}}
+
+\begin{center}
+\framebox{
+ Here ends the documentation of \Pkg{modroman}.
+}
+\end{center}
+\vspace*{\stretch{4}}
+\end{document}
+\endinput
+%%
+%% End of file `modroman-en.tex'.