vruler doc update (21mar10)

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

4 files changed, 239 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/vruler/miscdoc.sty b/Master/texmf-dist/doc/latex/vruler/miscdoc.sty
new file mode 100644
index 00000000000..878ff148692
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/vruler/miscdoc.sty
@@ -0,0 +1,111 @@
+\ProvidesPackage{miscdoc}[2010/01/20 v1.2 documentation macros misc latex pkgs]
+
+% miscdoc.sty
+% Copyright 2010 Robin Fairbairns
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% 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.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+% 
+% The Current Maintainer of this work is Robin Fairbairns.
+%
+% This work consists of the file miscdoc.sty (only)
+
+\setcounter{errorcontextlines}{1274}
+
+% The package arose from a small exercise to document packages whose
+% previous documentation consisted solely of comments in the package files.
+% The macros here defined are lifted from the author's faq.sty
+% (written for the UK TeX FAQ, CTAN:help/uk-tex-faq) or are inspired
+% by others' work (credited where the author is known) ... except
+% where they came as a flash of inspiration while actually writing the
+% documentation.
+
+% this option suggested by Heiko Oberdiek, 2010-01-29
+\DeclareOption{hyper}{%
+  \AtEndOfPackage{%
+    \RequirePackage[pdfusetitle]{hyperref}
+    \RequirePackage{bookmark}
+    \bookmarksetup{numbered,open,openlevel=1}
+  }
+}
+\ProcessOptions\relax
+
+% note: T1 encoding assumed
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+\usepackage{booktabs}
+
+% from faq.sty
+\newcommand\cs[1]{\texttt{\char`\\#1}}
+\let\csx\cs
+\def\bsbs{\cs{\char`\\}}
+
+% \cmdinvoke\cs<argument sequence>
+% \cs typeset as above
+% <argument sequence> may consist of optional or mandatory arguments;
+%
+% the `arguments' are simply typesett \texttt, as yet -- if something
+% fancier is needed, there's a bunch of code needs rewriting here...
+\DeclareRobustCommand\cmdinvoke{\@ifstar
+  {\let\@tempa\emph\@scmdinvoke}%
+  {\let\@tempa\relax\@scmdinvoke}%
+}
+\def\@scmdinvoke#1{\texttt{\symbol{92}#1}%
+  \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke{\ifx\@let@token\bgroup
+    \let\@tempb\@cmdinvoke@lbrace
+  \else
+    \ifx\@let@token[% ]
+      \let\@tempb\@cmdinvoke@lbrack
+    \else
+      \ifx\@let@token(% )
+        \let\@tempb\@cmdinvoke@lparen
+      \else
+        \let\@tempb\@empty
+      \fi
+    \fi
+  \fi
+  \@tempb
+}
+\def\@cmdinvoke@lbrace#1{\penalty0\hskip0pt\relax
+  \texttt{\symbol{123}\@tempa{#1}\symbol{125}}%
+  \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke@lbrack[#1]{\penalty-150\hskip0pt\relax
+  \texttt{[\@tempa{#1}]}%
+  \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke@lparen(#1){\penalty-150\hskip0pt\relax
+  \texttt{(\@tempa{#1})}%
+  \futurelet\@let@token\@cmdinvoke
+}
+% and extension -- versions that take a single extra (delimiter)
+% argument, such as \delcmdinvoke{lscrunge}( ... awful syntax, but...
+\DeclareRobustCommand\delcmdinvoke{\@ifstar
+  {\let\@tempa\emph\@sdelcmdinvoke}%
+  {\let\@tempa\relax\@sdelcmdinvoke}%
+}
+\def\@sdelcmdinvoke#1#2{\texttt{\symbol{92}#1#2}%
+  \futurelet\@let@token\@cmdinvoke
+}
+
+% sui generis
+\newcommand\newitem{\par\addvspace{1ex}\noindent}
+
+% inspired by doc.sty in latex distribution
+\newcommand\meta[1]{\ensuremath{\langle}\emph{#1}\ensuremath{\rangle}}
+
+% meaningful names, as in faq.sty
+\let\environment\texttt
+\let\Package\textsf
+\def\option{\@ifnextchar[\@optionb\@option}% ]
+\def\@optionb[#1]{[{\normalfont\ttfamily#1}]}
+\def\@option#1{\texttt{#1}}
diff --git a/Master/texmf-dist/doc/latex/vruler/vruler-example.tex b/Master/texmf-dist/doc/latex/vruler/vruler-example.tex
new file mode 100644
index 00000000000..75569d1566d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/vruler/vruler-example.tex
@@ -0,0 +1,34 @@
+% Application example, for the use of vruler.sty
+
+\documentclass[twoside]{article}
+\usepackage{vruler}
+       \setlength{\textwidth}{2.5in}
+       \setlength{\oddsidemargin}{3cm}
+       \setlength{\evensidemargin}{6cm}
+       \overfullrule=0pt \parindent=0pt
+\begin{document}
+\advance\textwidth 3cm %2cm is better for plain TeX
+\setvruler [][][][][][\textwidth]
+         This is a simple example, in which we have
+         placed vertical rulers on the left for
+         odd numbered pages and on the right for
+         even numbered pages. \newpage
+
+         This is the second page and is thus an even
+         numbered page. Please see that the vertical
+         ruler is now on the right, and is approximately
+         of the same distance from the text margin as
+         the vertical ruler on the first page from
+         the left margin there. \newpage
+\unsetvruler
+         The following pages, in fact only this page, will
+         not be appended with the vertical rulers.\newpage
+\setvruler[][\rulercount]
+         This page will be added with the vertical ruler again.
+         Here the numbering marking of the vertical ruler picks
+         up where it was left. Nevertheless, we may start with
+         any new number. \newpage
+
+         This is another page. Please see that both this and
+         the previous pages have vruler on the left side.
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/vruler/vruler.pdf b/Master/texmf-dist/doc/latex/vruler/vruler.pdf
new file mode 100644
index 00000000000..c7954e62322
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/vruler/vruler.pdf
diff --git a/Master/texmf-dist/doc/latex/vruler/vruler.tex b/Master/texmf-dist/doc/latex/vruler/vruler.tex
new file mode 100644
index 00000000000..3f5f5c16359
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/vruler/vruler.tex
@@ -0,0 +1,94 @@
+\documentclass[a4paper]{article}
+\usepackage[T1]{fontenc}
+\usepackage{underscore,amstext}
+\usepackage[a4paper]{geometry}
+\usepackage{miscdoc}
+\usepackage[scaled=0.85]{luximono}
+\newcommand\nl{\par\noindent}
+\begin{document}
+\title{The \Package{vruler} package~---\\
+  Vertical rulers in \LaTeX{}, Plain \TeX{} and ams\TeX{}}
+\author{Zhuhan Jiang\thanks{University of New England, Australia NSW 2351}}
+\date{October 1996, version v2.3\thanks{%
+    This documentation created 2010-03-21, by Robin Fairbairns}}
+\maketitle
+
+\section{What's the package for?}
+
+Make a vertical ruler, numbering consecutively so that any part of an
+article can be pinpointed immediately.  The vruler may be moved freely
+up and down, left and right.
+         
+There are no formally released packages that number lines in general
+text one by one without missing certain lines, particularly when there
+are many maths equations in the text. So \Package{vruler} is a good
+alternative for people writing text of versatile format or lots of
+maths formulas.
+
+\section{The commands}
+
+\cmdinvoke*{setvruler}[scale][initial_count][step][digits][mode]%
+[odd_hshift][even_hshift][vshift][height]\nl
+defines the start of vertical rulers, where:
+\par\addvspace{1ex}
+\noindent
+\meta{scale} is the distance between two consecutive markings on the
+vruler\nl
+\meta{initial_count} is the value on the first mark on the ruler\nl
+\meta{step} is the mark increment\nl
+\meta{digits} is the number of digits needed for ruler markings\nl
+$\text{\meta{mode}}=0$ if each page has the same ruler marking, $=1$
+otherwise\nl
+\meta{odd_hshift} is the horizontal shift for odd pages, from the
+default\nl
+\meta{even_hshift} is the horizontal shift for even pages, from the
+default\nl
+\meta{vshift} is the the vertical shift, from the default value, and\nl
+\meta{height} is the height of the vertical ruler.
+\par\addvspace{1ex}
+\noindent\cs{unsetvruler} stops vrulers.
+\par\addvspace{1ex}
+\noindent\cmdinvoke*{setdefault}{cmdname}{n}{default_1}{\dots{}}{default_n}\nl
+(re)sets macro \meta{n} defaults for
+\cmdinvoke{cmdname}[\#1][\dots{}][\#n] to take \meta{default_1} to
+\meta{default_n} respectively, so that \cmdinvoke*{cmdname}[][xy] is
+the same as
+\cmdinvoke{cmdname}*[\meta{default_1}][xy][\meta{default\dots{}}].
+
+You don't need to use \cs{setdefault} unless you would like to change
+the default setting for macros in \Package{vruler} or elsewhere.
+\par\addvspace{1ex}
+\noindent\cs{vrulecount} holds the next mark value to be used on the
+vertical rules.
+
+\subsection*{Defaults}
+
+The parameters of \cs{setvruler} admit defaults.  With no arguments,
+the command is equivalent to:\nl
+\leavevmode\quad\cmdinvoke{setvruler}[10pt][1][1][4][1][0pt][0pt][0pt][\cs{textheight}]\nl
+and\nl
+\leavevmode\quad\cmdinvoke{setvruler}[][20] has the same effect as:\nl
+\leavevmode\quad\cmdinvoke{setvruler}[10pt][20]
+
+\section{Notes}
+
+\begin{enumerate}
+\item If you are using the \Package{multicol} package, then you might
+  want to move the vruler into the center to separate the columns.
+\item If you use a value of \cs{topskip} other than the default, then
+  you will have to alter \meta{vshift} and \meta{height} parameters in
+  \cs{setvruler} accordingly (which is simple).
+\item It is best to choose the value \cs{baselineskip} \meta{scale} so
+  that line synchronisation is often optimal.  Use (e.g.\@) ``5+'' to
+  denote the line immediately after marking number ``5'' if
+  necessary.
+\item In twosided \Package{book} class in \LaTeXe{}, the initial
+  numbering of title page via \cmdinvoke{begin}{titlepage} is actually
+  one page away.  To overcome this, either do not include the title
+  page in the region covered by vruler, or set the initial count
+  (\texttt{\#2}) to a number (a page ahead) so that the resulting
+  initial number is what one needs.
+\item The file \texttt{vruler-example.sty} in the distribution offers
+  an example of use.
+\end{enumerate}
+\end{document}