path: root/Master/texmf-dist/doc/latex/rvwrite/rvwrite-doc.tex

%%                                   
%%
%% This is file 'rvwrite-doc.tex'.
%%
%% File: rvwrite.sty Copyright (c) 2010 C. V. Radhakrishnan
%%       River Valley, Mepukada, Malayinkil, Trivandrum 695571
%%       http://www.river-valley.com Email: <cvr@river-valley.org>
%%       
%% This package may be distributed under the terms of the LaTeX Project 
%% Public License, as described in lppl.txt in the base LaTeX distribution.
%% Either version 1.0 or, at your option, any later version.
%%
%% $Id: rvwrite-doc.tex,v 1.1 2010/08/27 09:43:57 cvr Exp cvr $
%% 
%%

\documentclass[a4paper]{article}

\makeatletter
\usepackage[dvipsnames,svgnames]{xcolor}

 \colorlet{itemcolor}{brown}
 \colorlet{verbcolor}{Sepia}
 \colorlet{botrulecolor}{orange!25}
 \colorlet{botbgcolor}{orange!15}
 \colorlet{botcolor}{orange!80}
 \colorlet{pgrulecolor}{orange}
 \colorlet{pgbgcolor}{white}

 \colorlet{quicklinkrulecolor}{orange!40}
 \colorlet{quicklinkcolor}{brown}
 \colorlet{topverticalrule}{brown}
 \colorlet{titlecolor}{brown}
 \colorlet{hlinkcolor}{brown}
 \colorlet{hlinktricolor}{orange!70}
 \colorlet{linkcolor}{brown}
 \colorlet{urlcolor}{brown}

 \colorlet{arrayrulecolor}{olive!30}
 \colorlet{seccolor}{brown}

 \colorlet{toprulecolor}{orange!30}
 \colorlet{topbgcolor}{orange!10}
 \colorlet{topcolor}{brown!80}
%
%
\def\floatpagefraction{.99}
\usepackage{geometry}
\geometry{top=2in,
  bottom=1in,
  left=2in,
  right=1in,
  a4paper}

\DeclareRobustCommand{\LaTeX}{L\kern-.25em%
  {\sbox\z@ T%
         \vbox to\ht\z@{%
           \hbox{%
             \check@mathfonts
              \fontsize\sf@size\z@
              \math@fontsfalse\selectfont
              A}%
          \vss}%
        }%
   \kern-.10em%
   \TeX}

\usepackage{comment,xspace}
\def\xml{\textsc{xml}\xspace}
\def\latex{\LaTeX\xspace}
\def\pdf{\textsc{pdf}\xspace}
\def\pdfa{\textsc{pdf/a-1}b\xspace}
\def\pdfx{\textsc{pdf/x-1}a\xspace}
\def\xmp{\textsc{xmp}\xspace}
\def\pdftex{\textsc{pdf\TeX}\xspace}
\def\defmacro#1{\texttt{\bsl#1}}
\def\thanh{H\`an Th\^e Th\`anh\xspace}
\def\gnulinux{\textsc{gnu/linux}\xspace}
\def\bsl{\expandafter\@gobble\string\\}

\let\@DRAFTout@Hook\@empty
\newcommand{\DRAFTout}{\g@addto@macro\@DRAFTout@Hook}
\newcommand{\@DRAFTout@Out}{%
   \afterassignment\@DRAFTout@Test
   \global\setbox\@cclv= %
   }
\newcommand{\@DRAFTout@Test}{%
   \ifvoid\@cclv\relax
      \aftergroup\@DRAFTout@Output
   \else
      \@DRAFTout@Output
   \fi%
   }
\newcommand{\@DRAFTout@Output}{%
   \@DRAFTout@Hook%
   \@DRAFTout@Org@Out\box\@cclv%
   }
\newcommand{\@DRAFTout@Org@Out}{}
\newcommand*{\@DRAFTout@Init}{%
   \let\@DRAFTout@Org@Out\shipout
   \let\shipout\@DRAFTout@Out
   }
\newdimen\OHeight
\setlength\OHeight{\textheight}
\addtolength\OHeight{\headheight}
\addtolength\OHeight{\headsep}
\addtolength\OHeight{\footskip}

\newif\ifoverlay\overlayfalse

\AtBeginDocument{\@DRAFTout@Init}
\newcommand{\@DraftOverlay@Hook}{}
\newcommand{\AddToDraftOverlay}{\g@addto@macro\@DraftOverlay@Hook}
\newcommand{\ClearDraftOverlay}{\let\@DraftOverlay@Hook\@empty}
\newcommand{\@DraftOverlay}{%
  \ifx\@DraftOverlay@Hook\@empty
  \else
    \bgroup
      \@tempdima=1in
      \@tempcnta=\@tempdima
      \@tempcntb=-\@tempdima
      \advance\@tempcntb\paperheight
      \ifoverlay
       \global\setbox\@cclv\vbox{%
        \box\@cclv
        \vbox{\let\protect\relax%
         \unitlength=1pt%
         \pictur@(0,0)(\strip@pt\@tempdima,\strip@pt\@tempdimb)%
          \@DraftOverlay@Hook%
         \endpicture}}%
     \else
       \global\setbox\@cclv\vbox{%
        \vbox{\let\protect\relax%
         \unitlength=1sp%
         \pictur@(0,0)(\@tempcnta,\@tempcntb)%
          \@DraftOverlay@Hook%
         \endpicture}%
         \box\@cclv}%
     \fi 
    \egroup
  \fi
}

\definecolor{gray30}{gray}{.7}
\definecolor{gray20}{gray}{.8}
\definecolor{gray10}{gray}{.9}

\DRAFTout{\@DraftOverlay}
\long\def\puttext(#1)#2{\AddToDraftOverlay{%
  \setlength{\unitlength}{1pt}\thinlines%
  \put(#1){#2}}}

\RequirePackage{shortvrb}
\MakeShortVerb{\|}
\RequirePackage{amsfonts,amssymb}
\IfFileExists{pxfonts.sty}{\RequirePackage{pxfonts}}{}
\IfFileExists{charter.sty}{\RequirePackage{charter}}{}
\IfFileExists{lfr.sty}{\RequirePackage[scaled=.85]{lfr}}{}
\IfFileExists{prima.sty}{\RequirePackage[scaled=.8]{prima}}{}

\def\theCodelineNo{\reset@font\tiny\arabic{CodelineNo}}
 
\def\@seccntformat#1{\llap{\csname the#1\endcsname.\hspace*{6pt}}}
\def\section{\@startsection {section}{1}{\z@}%
      {-3.5ex \@plus -1ex \@minus -.2ex}%
      {2.3ex \@plus.2ex}%
      {\normalfont\large\bfseries\color{seccolor}}}
\def\subsection{\@startsection{subsection}{2}{\z@}%
      {-2.25ex\@plus -1ex \@minus -.2ex}%
      {1.5ex \@plus .2ex}%
      {\normalfont\normalsize\bfseries\color{seccolor}}}
\def\subsubsection{\@startsection{subsubsection}{3}{\z@}%
      {-1.25ex\@plus -1ex \@minus -.2ex}%
      {1.5ex \@plus .2ex}%
      {\normalfont\normalsize\bfseries\color{seccolor}}}

\puttext(0,36){\botstring}%
 \puttext(0,840){\copy\topbox}

\RequirePackage{colortbl}
\arrayrulecolor{arrayrulecolor}
\let\shline\hline
\def\hline{\noalign{\vskip3pt}\shline\noalign{\vskip4pt}}

\RequirePackage[pdftex,colorlinks]{hyperref}
\def\Hlink#1#2{\hyperlink{#2}{\color{hlinktricolor}%
     $\blacktriangleright$~\color{hlinkcolor}#1}}
 \def\@linkcolor{linkcolor}
 \def\@urlcolor{urlcolor}

\pagestyle{empty}
\def\version#1{\gdef\@version{#1}}
\def\@version{1.0}
\def\contact#1{\gdef\@contact{#1}}
\def\author#1{\gdef\@author{#1}}
\def\@author{River Valley Technologies}
\def\@contact{\texttt{support@river-valley.com}}
\def\keywords#1{\gdef\@keywords{#1}}
\def\@keywords{\LaTeX, \xml}

\long\def\Hrule{\\[-4pt]\hspace*{-3em}%
     {\color{quicklinkrulecolor}\rule{\linewidth}{.1pt}}\\}

\long\def\dtxmarkone[#1][#2]#3#4#5{\def\next{#1}%
     \ifcase\next\or\Hlink{#4}{#3}\Hrule \fi}

\newcounter{dtx}

\long\def\dtxmarktwo[#1][#2]#3#4#5{\def\next{#1}%
   \stepcounter{dtx}\parbox{.45\linewidth}%
    {\ifcase\next\or\Hlink{#4}{#3}\fi}%
   \ifodd\thedtx\relax\else\Hrule\fi}

\let\dtxmark\dtxmarkone
\newbox\topbox
\long\def\maketitle{\global\setbox\topbox=\vbox{\hsize=\paperwidth
    \parindent=0pt
    \fcolorbox{toprulecolor}{topbgcolor}%
    {\parbox[t][1.5in][c]{\paperwidth}%
      {\hspace*{15mm}%
       \parbox[c]{.35\paperwidth}{\fontsize{18pt}{20pt}%
          \raggedright\normalfont\sffamily \selectfont
          \color{titlecolor} \@title\\[6pt]
          {\normalsize\rmfamily\scshape\@author}\\%
          {\footnotesize\textsc{keywords:} \@keywords}}%
        \hfill
        \parbox[c][1.5in][c]{1mm}{\color{topverticalrule}%
          \rule{.1pt}{1.5in}}%
        \hfill
        \parbox[c][1.5in][c]{.35\paperwidth}%
        {\normalfont\footnotesize\sffamily\color{quicklinkcolor}%
           \vspace*{6pt} QUICK LINKS\Hrule
            \IfFileExists{tmp.out}{\input tmp.out}{}%
         }\hspace*{5mm}%
      }%
    }%
  }%
}
\gdef\botstring{\fcolorbox{botrulecolor}{botbgcolor}%
    {\parbox[t][.5in][t]{\paperwidth}%
      {\normalfont\sffamily\footnotesize%
        \color{botcolor}%
        \hspace*{5mm}\parbox[c][.5in][c]{.45\paperwidth}%
         {\raggedright River Valley Technologies,
           \href{http://www.river-valley.com}{%
            http://www.river-valley.com}\\
            River Valley Campus, Malayinkil, Trivandrum
           695571, India\\  9, Browns Court, Kennford,
           Exeter, United Kingdom {\scshape ex6 7xy}          
        }\hfill%
       \parbox[c][.5in][c]{1cm}
        {\centering\sffamily\mdseries
          \fcolorbox{pgrulecolor}{pgbgcolor}{\thepage}%
        }\hfill
       \parbox[c][.5in][c]{.45\paperwidth}
        {\raggedleft\begin{tabular}{rl}%
          Version:&\@version\\
          Date:&\@date\\
          Contact:&\@contact
         \end{tabular}\hspace*{5mm}%
        }%
      }%
    }%
  }

\RequirePackage{enumitem}
\setitemize[1]{label={\small\color{itemcolor}$\blacktriangleright$},itemsep=0pt}
\setitemize[2]{label={\small\color{itemcolor}$\triangleright$},itemsep=0pt}
\setenumerate[1]{label={\small\color{itemcolor}\arabic*.},itemsep=0pt}

\def\MacroFont{\fontencoding\encodingdefault
        \fontfamily\ttdefault
        \fontseries\mddefault
        \fontshape\updefault
        \color{verbcolor}\small}%

\def\verbatim@font{\normalfont\color{verbcolor}\ttfamily}

\def\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
  \bgroup
    \verb@eol@error \let\do\@makeother \dospecials
    \verbatim@font\@noligs
    \@ifstar\@sverb\@verb}

\makeatother

\begin{document}

\title{Enhancing \texttt{write} register in \LaTeX{} documents}
\date{2010/08/25}
\version{1.2}
\keywords{\pdf, pdf\TeX, \LaTeX}
\author{c.\,v.\,radhakrishnan}
\contact{\texttt{cvr@river-valley.org}}

\maketitle

\section{Prolog}

The \verb+io+ registers in \TeX{} are often a matter of severe
limitation. When we try to typeset a document that loads a lot of
packages, it becomes a non-trivial task to satisfy register
requirements of various packages that compete with each other. It is
further complicated, if refining the typeset copy involves usage of
more custom packages which want to write out a few streams for reading
during subsequent \TeX{} compilations. \LaTeX{} needs a few registers
by default, some of the packages might need a few more streams thereby
reducing the available number of registers to less than ten. At times,
we have been forced to comment out a few \verb+write+ registers which
are seemingly unused for the document in question to make available
necessary registers for our custom packages. But, this is not an
elegant way, also, it requires developer intervention during the
production process. The package namely, \verb+rvwrite.sty+, is written
to solve this nagging problem.

\section{The theory}

We make use of only one register to write out all our streams,
meaning, all the items of information will be written to one file with
necessary mark-up and delimiters to separate at a latter stage. The
final separation and write out process depend on the literate
programming method developed by
\href{http://tug.org/interviews/gurari.pdf}{Eitan Gurari} and as
provided in his package, \verb+ProTex.sty+ which is part of any
standard \TeX{} distribution. The written out file is further
processed by \TeX{} with the help of \verb+ProTex.sty+ to segregate
all information and collect in separate files for our final usage.

\section{The implementation}

The process involves the following stages:
\begin{enumerate}
\item Mark-up all strings to be written out with special tags. 
\item Run \LaTeX{} in the usual way which will generate
  \verb+\jobname-write.tex+ along with other auxiliary files.
\item Typeset \verb+\jobname-write.tex+ with \LaTeX, this will result
  in several output files as you would expect.
\end{enumerate}

\subsection{New functions}
\begin{description}
\item[\defmacro{newrvwrite}] Every new stream has to be initialized with
  this function. eg.,
  \begin{verbatim}
   \newrvwrite{mex}
\end{verbatim} 
\noindent  This will facilitate a new auxiliary stream, \verb+\jobname-mex.tex+.
\item[\defmacro{rvwrite}] Macro to mark-up strings meant for writing
  out. This has two arguments, first being the file type and the
  second the strings. eg.,
  \begin{verbatim}
   \rvwrite{mex}{$\beta$}
\end{verbatim} 
\noindent  will write \verb+$\beta$+ to \verb+\jobname-mex.tex+ without
  expanding any of the strings even if control sequence.
\item[\defmacro{ervwrite}] Macro to mark-up strings that contain
  \TeX{} control sequences which need to be expanded before writing.
  eg.,
  \begin{verbatim}
   \ervwrite{mex}{Section: \thesection}
\end{verbatim}
\noindent  will write the contents after expanding \verb+\thesection+ to the
  corresponding counter number.
\end{description}

\subsection{The usage}

Package can be loaded with the following command:
\begin{verbatim}
 \usepackage{rvwrite}
\end{verbatim}
\noindent
There are no extra options for the package, nor is there any specific
sequence for loading, it can be loaded anywhere in the preamble.

As explained in the previous section, to define a new output stream,
\verb+\newrvwrite+ shall be used, the usage is provided below:
\begin{verbatim}
 \newrvwrite{info}
\end{verbatim}
This command will finally result in a file, \verb+\jobname-info.tex+
which may be used as such or renamed to suit user's requirements. Each
stream may be initialized with \verb+\newrvwrite+ macros to facilitate
safe writing of output at the end of the process. Even if you miss to
initialize, the first instance of writing will trigger initialization,
but it will be more safer to initialize the stream in the beginning.

\subsection{Examples}

\subsubsection{Source file}

Given below is the source of a test file, \verb+test.tex+ for favor
of your testing:
\begin{verbatim}
  \documentclass[a4paper]{article}
   \usepackage{pxfonts}
   \usepackage{rvwrite}
   \usepackage{lipsum}

  \begin{document}

   \lipsum[1]
   \newrvwrite{info}
   \ervwrite{info}{\dlrchr\string\gamma\dlrchr}
   \rvwrite{info}{$\beta$}
   \ervwrite{info}{JOB: \jobname-\thepage}

   \newrvwrite{tbl}
   \ervwrite{tbl}{\string\def\string\thetable{9}}
   \rvwrite{tbl}{{\itshape Indian \TeX\ Users Group}}
   \rvwrite{tbl}{\LaTeX is a macro package written in \TeX\ language}
   \lipsum[2]

  \end{document}
\end{verbatim}

\subsubsection{Composite stream}

The verbatim source of the composite stream written to
\verb+test-write.tex+ is given below:
\begin{verbatim}
  \documentclass{article}
   \input ProTex.sty
   \AlProTex{tex,<<<>>>,list,title,|,[]}
   \begin{document}
 
   \<test-info\><<<
   $\gamma$
   >>>
   \<test-info\><<<
   $\beta $
   >>>
   \<test-info\><<<
   JOB: test-1
   >>>
   \<test-tbl\><<<
   \def\thetable{9}
   >>>
   \<test-tbl\><<<
   {\itshape Indian \TeX \ Users Group}
   >>>
   \<test-tbl\><<<
   \LaTeX is a macro package written in \TeX \ language
   >>>
  \OutputCode\<test-info\>
  \OutputCode\<test-tbl\>
 
  \end{document}
\end{verbatim}

\subsubsection{Various output files}

Two files will be created (1) \verb+test-info.tex+ and (2)
\verb+test-tbl.tex+, the sources are provided below:

\paragraph{test-info.tex}
\begin{verbatim}
  $\gamma$
  $\beta $
  JOB: test-1
\end{verbatim}

\paragraph{test-tbl.tex}
\begin{verbatim}
  \def\thetable{9}
  {\itshape Indian \TeX \ Users Group}
  \LaTeX is a macro package written in \TeX \ language
\end{verbatim}

\section{Download}

The package, documentation and test files can be downloaded from the
\textsc{url}:\par\medskip
 \url{http://download.river-valley.com/cvr/rvwrite.tar.gz}

\medskip
Bugs, suggestions and feature requests may be posted at
\href{http://www.cvr.cc/write-registers-in-tex/}{http://www.cvr.cc}.

\end{document}