summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/rvwrite/rvwrite-doc.tex
blob: 61399f0ef86fdceb24d4ceeae81b585c4caedee5 (plain)
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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
%%                                   
%%
%% 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}