summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/refman/lay_e2.tex
blob: 9590edbfb40573c1a23c7a78f63a3f2ef28bf356 (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
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
% LAY_e2.TEX - Anhang von LAYOUT.TEX (PA 1988)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\clearpage

\section*{Appendix}
\addcontentsline{toc}{section}{Appendix}

\appendix

\section{The page structure in \LaTeX}

This appendix describes how the actual page is build from its 
components and how they are influenced by \TeX{}'s parameters. 
(\seealso{Fig.\,\ref{bild}} Figure~\ref{bild} has been created by 
Nelson Beebe at the University of Utah.)

\begin{description}

\item[text area]
	The normal text area (``Body'') contains the running text 
	including footnotes, tables and figures.  The headings, footer 
	and margin notes do \emph{not} belong to the text area.
        
	The text area has the width \cs{textwidth} 
	and the height \cs{text\-height}.
        
	In a two column layout the text area is split into two columns, with
	the width \cs{columnwidth} each and a space of \cs{columnsep} between
	them.  Thus the \cs{columnwidth} is a little bit smaller than half
	the \cs{textwidth}.
	
	\cs{textwidth} and \cs{columnwidth} should be a multiple of the
	width of one character in the \texttt{tt} font.
	
	\cs{textheight} should be multiple of the line height
	\cs{baselineskip}, increased by the constant value of \cs{topskip}.
	
	Indentations inside the text area are defined with \cs{leftskip} and
	\cs{rightskip}.  These parameters should not be changed explicitly
	by the user but rather implicitly through environments.
	
\item[left margin]
	The left margin is either \cs{odd-} or \cs{evensidemargin} plus
	1~inch.  Both parameters have the same value, unless the
	\texttt{twoside} option is given.

\item[top margin]
	The top margin is the sum of \cs{topmargin}, \cs{headheight} and 
	\cs{headsep} plus 1~inch.

\item[right margin]
	The right margin is the paper width minus the left margin and 
	the text area.

\item[bottom margin]
	The bottom margin is the paper height minus the top margin and 
	the text area.
       
\item[heading]\index{headings}
	The heading is inside the top margin with a space of \cs{headsep}
	between the lower border of the header and the upper border of the
	text area.  Above the header is a free space of \cs{topmargin}
	increased by 1~inch.
      
\item[footing]\index{footings} The footer is inside the bottom margin with a
	space of \cs{footskip} between the lower border
	of the text area and the lower border of the footer.
	
\item[margin notes]\index{margin notes} Margin notes are inside the left or
	right margin.  They have a width of \cs{marginparwidth} and a space
	of \cs{marginparsep} between the margin note and the text area.  The
	vertical space between two margin notes is \cs{marginparpush}.
		    
\end{description}

The \texttt{paperheight} consists of the following elements (from top to 
bottom):
\begin{verse}
1 inch \\*[2pt]
\cs{topmargin} \\*[2pt]
\cs{headheight} \\*[2pt]
\cs{headsep} \\*[2pt]
\cs{textheight} \\*[2pt]
\cs{footskip} \\*[2pt]
remaining page.
\end{verse}

On pages with margin notes in the right margin the \texttt{paperwidth} consists 
of the following elements:
\begin{verse}
1 inch\\*[2pt]
\cs{oddsidemargin}
\ \ or\ \ 
\cs{evensidemargin}\\*[2pt]
\cs{textwidth}\\*[2pt]
\cs{marginparsep}\\*[2pt]
\cs{marginparwidth}\\*[2pt]
remaining page
\end{verse}
With the option \texttt{twoside} the left pages change to
\begin{verse}
1 inch\\*[2pt]
\cs{evensidemargin}\\*[2pt]
\cs{textwidth}\\*[2pt]
remaining page
\end{verse}

\marginlabel{Comments:} The parameters \cs{topmargin}, \cs{oddsidemargin},
and \cs{evensidemargin} may be negative.  In this case, the margin will be
smaller than 1~inch.  The same is true for \cs{leftskip} and \cs{rightskip}
which leads to text that is wider than the text area.

Extensive treatment and figures to this subject may be found in the
\textsc{TUGboat} Vol.9, No.1 (April 1988).

The parameter \cs{footheight} is no longer defined 
in \LaTeXe\ since no-one used it.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{fullpage}
%%%%%%%%%%%%%%%%


% Bild von Nelson Beebe, mit geringen "Anderungen von PA:
\newcommand{\X}[1]{{#1}\index{{#1}}}
% NB: For computed dimension parameters, we cannot use
% \newcommand{}, because this expands to a TeX \def which does
% not evaluate the definition before assigning it to the control
% sequence name; we use \xdef directly to force evaluation
\newcount\T      % temporary counter for arithmetic calculations
\T=0

% **********************************************************************
% WARNING: Do not insert ANY aditional whitespace in these
% macros--otherwise it ends up in the TeX boxes and ruins the
% positioning, sigh....
% **********************************************************************

% NAMEBOX{x}{y}{dx}{dy}{width}{height}{pos}{label} -- framed label with
% box lower-left corner at (x+dx,y+dy)
\newcommand{\NAMEBOX}[8]{\put(#1,#2){\begin{picture}(0,0)(-#3,-#4)\ignorespaces
    \framebox(#5,#6)[#7]{#8}\end{picture}}}

% HARROW{x}{y}{dx}{dy}{length}{side}{pos}{label} -- horizontal
% labeled arrow with left point at (x+dx,y+dy), label on bottom
% (side=b) or top (side=t) of arrow, in makebox[pos]
\newcommand{\HARROW}[8]{\put(#1,#2){\begin{picture}(0,0)(-#3,-#4)\ignorespaces
    \put(0,0){\vector(1,0){#5}}\ignorespaces
    \put(#5,0){\vector(-1,0){#5}}\ignorespaces
    \ifthenelse{\equal{#6}{b}}{\ignorespaces
      \put(0,-\TAD){\makebox(#5,0)[#7]{#8}}
    }{\ignorespaces
    \ifthenelse{\equal{#6}{t}}{}{\ignorespaces
      \typeout{Side #6 must be ``b'' or ``t''--``t'' assumed}}\ignorespaces
      \put(0,\TAD){\makebox(#5,0)[#7]{#8}}
    }
    \end{picture}}}

% VARROW{x}{y}{dx}{dy}{length}{side}{pos}{label} -- vertical
% labeled arrow with left point at (x+dx,y+dy), label on left
% (side=l) or right (side=r) of arrow, in makebox[pos]
\newcommand{\VARROW}[8]{\put(#1,#2){\begin{picture}(0,0)(-#3,-#4)\ignorespaces
    \put(0,0){\vector(0,1){#5}}\ignorespaces
    \put(0,#5){\vector(0,-1){#5}}\ignorespaces
    \ifthenelse{\equal{#6}{l}}{\ignorespaces
      \put(-\TAD,0){\makebox(0,#5)[#7]{#8}}
    }{\ignorespaces
      \ifthenelse{\equal{#6}{r}}{}{\ignorespaces
        \typeout{Side #6 must be ``r'' or ``l''--``r'' assumed}}\ignorespaces
        \put(\TAD,0){\makebox(0,#5)[#7]{#8}}
    }
    \end{picture}}}

% VRULE{x}{y}{dx}{dy}{length}{side}{pos}{label} -- vertical
% rule with left point at (x+dx,y+dy), label on left
% (side=l) or right (side=r) of rule, in makebox[pos]
\newcommand{\VRULE}[8]{\put(#1,#2){\begin{picture}(0,0)(-#3,-#4)\ignorespaces
    \put(0,0){\line(0,1){#5}}\ignorespaces
    \ifthenelse{\equal{#6}{l}}{\ignorespaces
      \put(0,0){\makebox(0,#5)[#7]{$\rightarrow${}#8}}
    }{\ignorespaces
      \ifthenelse{\equal{#6}{r}}{}{\ignorespaces
        \typeout{Side #6 must be ``r'' or ``l''--``r'' assumed}}\ignorespaces
        \put(0,0){\makebox(0,#5)[#7]{$\leftarrow${}#8}}
    }
  \end{picture}}}
% **********************************************************************
% If you wish to change any of these values:
%       * definitions are mostly in alphabetical order
%       * remember units are in centipoints for accurate
%         positioning
%       * most parameters are taken directly from values in
%         BK11.STY, but in order to improve the appearance of the
%         figure, a few have been increased to avoid overlap of
%         labels and/or boxes, or to loosen up the figure
%       * ALL parameters which depend on others are defined by
%         computation and \xdef's below; they must NEVER be
%         changed
%
%- For 11pt BOOK style, \textwidth / \pagewidth(8.5in) = 0.5294
%- Anything larger than this will generate an overfull box.  We
%- choose 0.50 since that makes scaling trivial for the reader
%- \newcommand{\UNITLENGTH}{0.005pt}
%- \newcommand{\SCALEFACTOR}{50\%}
%
%-----> We use a larger picture with 0.70 on our DIN-A4 paper:
\newcommand{\UNITLENGTH}{0.007pt}
\newcommand{\SCALEFACTOR}{70\%}
% <------------------------------
%
% US papersize...
%
\newcommand{\PAGEHEIGHT}{79497}         % 11in in centipoints
\newcommand{\PAGEWIDTH}{61430}          % 8.5in in centipoints
%
% Typical dimensions from BK10.DOC
%
\newcommand{\BASELINESKIP}{2000}        % really 1000, but this is
                                        % too tight for the figure
\newcommand{\COLUMNSEP}{1000}
\newcommand{\COLUMNSEPRULE}{0}

% DVI drivers put top left corner at (1in,1in) from physical page
% left corner
\newcommand{\DVIXOFFSET}{7227}
\newcommand{\DVIYOFFSET}{7227}

\newcommand{\EVENSIDEMARGIN}{10841}

\newcommand{\FOOTHEIGHT}{2400} % really 1200, but too tight
\newcommand{\FOOTNOTESEP}{665}
\newcommand{\FOOTSKIP}{4207}    % really 2529, but too tight; for symmetry,
                                % make FOOTSKIP=HEADSEP+FOOTHEIGHT
\newcommand{\HEAdHEIGHT}{2400}  % really 1200, but too tight
\newcommand{\HEADSEP}{1807}

\newcommand{\MARGINPARPUSH}{2000}       % really 500, but too tight
\newcommand{\MARGINPARSEP}{2800}        % really 700, but too tight
\newcommand{\MARGINPARWIDTH}{7227}
\newcommand{\MARGINNOTEHEIGHT}{4444}    % arbitrary value (holds
                                        % ``Margin Note A'' on
                                        % 2 lines)

\newcommand{\ODDSIDEMARGIN}{3613}
%
% Upper left page corner (0,0) is at (1in,1in) on physical page
% for DVI drivers.  Position the LOWER left corner at
% (\PAGEXORIGIN,\PAGEYORIGIN), where \PAGEYORIGIN is computed
% below
\newcommand{\PAGEXORIGIN}{\DVIXOFFSET}

\newcommand{\TAD}{800}     % how far to move labels from their arrows
\newcommand{\TEXTHEIGHT}{50400}
\newcommand{\TEXTWIDTH}{32522}
\newcommand{\TOPMARGIN}{5420}

% **********************************************************************
% DO NOT CHANGE any of these computed parameters
%

%
\T=\TEXTWIDTH
\advance\T by -\COLUMNSEP
\divide\T by 2
\xdef\COLUMNWIDTH{\the\T}

\T=\TEXTWIDTH
\divide\T by 2
\advance\T by \ODDSIDEMARGIN
\xdef\COLUMNXMIDDLE{\the\T}     % 0.5*TEXTWIDTH+ODDSIDEMARGIN

\T=\COLUMNWIDTH
\advance\T by \ODDSIDEMARGIN
\advance\T by \COLUMNSEP
\xdef\COLUMNTWOX{\the\T}        % COLUMNWIDTH+COLUMNSEP+ODDSIDEMARGIN

\T=\FOOTSKIP
\advance\T by \TEXTHEIGHT
\advance\T by \HEADSEP
\xdef\HEADYORIGIN{\the\T}           % FOOTSKIP+TEXTHEIGHT+HEADSEP
%
% Inner TeX page dimensions are (\INNERWIDTH,\INNERHEIGHT).  All TeX
% coordinates are relative to (0,0) at upper-left corner of this
% page, although for the figures, we put (0,0) at lower-left
% corner.
%
\T=\TOPMARGIN
\advance\T by \HEAdHEIGHT
\advance\T by \HEADSEP
\advance\T by \TEXTHEIGHT
\advance\T by \FOOTSKIP
% INNERHEIGHT=TOPMARGIN+HEAdHEIGHT+HEADSEP+TEXTHEIGHT+FOOTSKIP
\xdef\INNERHEIGHT{\the\T}

\T=\ODDSIDEMARGIN
\advance\T by \TEXTWIDTH
\advance\T by \EVENSIDEMARGIN
\xdef\INNERWIDTH{\the\T}  % ODDSIDEMARGIN+TEXTWIDTH+EVENSIDEMARGIN

\T=\ODDSIDEMARGIN
\advance\T by \TEXTWIDTH
\advance\T by \MARGINPARSEP
\xdef\MARGINNOTEXORIGIN{\the\T} % ODDSIDEMARGIN+TEXTWIDTH+MARGINPARSEP

\T=\TEXTHEIGHT
\multiply\T by 75
\divide\T by 100
\advance\T by \FOOTSKIP
\xdef\MARGINNOTEYA{\the\T}      % .75*TEXTHEIGHT+FOOTSKIP

\T=\MARGINNOTEYA
\advance\T by -\MARGINNOTEHEIGHT
\advance\T by -\MARGINPARPUSH
\xdef\MARGINNOTEYB{\the\T}      % MARGINNOTEYA-MARGINNOTEHEIGHT-MARGINPARPUSH

\T=\MARGINNOTEYA
\advance\T by \MARGINNOTEHEIGHT
\xdef\MARGINNOTEYC{\the\T}      % MARGINNOTEYA+MARGINNOTEHEIGHT

\T=\PAGEHEIGHT
\advance\T by -\DVIYOFFSET
\xdef\PAGEYTOP{\the\T}          % PAGEHEIGHT-DVIYOFFSET

\T=\PAGEYTOP
\advance\T by -\INNERHEIGHT
\xdef\PAGEYORIGIN{\the\T}       % PAGEYTOP-INNERHEIGHT

\T=\ODDSIDEMARGIN
\advance\T by \TEXTWIDTH
\xdef\RIGHTEDGE{\the\T}         % ODDSIDEMARGIN+TEXTWIDTH

\T=\TEXTHEIGHT
\multiply\T by 4
\divide\T by 10
\xdef\TEXTY{\the\T}             % TEXTY = 0.4*TEXTHEIGHT (we put
                                % sample text here)

\T=\TEXTHEIGHT
\divide\T by 3
\xdef\TEXTWIDTHY{\the\T}        % TEXTWIDTHY = TEXTHEIGHT/3 (we
                                % put \textwidth label here)
  \begin{figure}
  %%%%%%%%%%%%%%

 \caption{Page layout}
 \label{bild}

    \begin{center}
      \begin{small}       % make text somewhat smaller
      \setlength{\unitlength}{\UNITLENGTH}
        \begin{picture}(\PAGEWIDTH,\PAGEHEIGHT)   % sizes in centipoints

%
          \NAMEBOX{0}{0}{0}{0}{\PAGEWIDTH}{\PAGEHEIGHT}{}{}
%
          \HARROW{0}{\PAGEYTOP}{0}{0}{\PAGEXORIGIN}{b}{}{1in}
%
          \VARROW{\PAGEXORIGIN}{\PAGEYTOP}{0}{0}{\DVIYOFFSET}{r}{l}{1in}
%
          \put(\PAGEXORIGIN,\PAGEYORIGIN){
          \begin{picture}(\INNERWIDTH,\INNERHEIGHT)
            % Draw 3-sided inner page frame--no bottom side
            % because it is not significant for dimensioning
            \put(0,0){\line(0,1){\INNERHEIGHT}}
            \put(0,\INNERHEIGHT){\line(1,0){\INNERWIDTH}}
            \put(\INNERWIDTH,0){\line(0,1){\INNERHEIGHT}}
%
            \NAMEBOX{\ODDSIDEMARGIN}{\TEXTY}{0}{0}{\TEXTWIDTH}{
                \BASELINESKIP}{l}{A line of text\ldots}
            \NAMEBOX{\ODDSIDEMARGIN}{\TEXTY}{0}{-\BASELINESKIP}{
                \TEXTWIDTH}{\BASELINESKIP}{l}{Next line\ldots}
%
            \VARROW{\COLUMNXMIDDLE}{\TEXTY}{0}{-\BASELINESKIP}{
              \BASELINESKIP}{r}{l}{\tt\string\baselinestretch
              $\times$\string\baselineskip}
%
            \HARROW{0}{\TEXTHEIGHT}{0}{0}{\ODDSIDEMARGIN}{t}{}{
              \tt\string\oddsidemargin}
            \HARROW{0}{\TEXTHEIGHT}{0}{0}{\ODDSIDEMARGIN}{b}{}{
              \tt\string\evensidemargin}
            %
            % Page text label
            \NAMEBOX{\ODDSIDEMARGIN}{\FOOTSKIP}{0}{0}{\TEXTWIDTH}{
              \TEXTHEIGHT}{}{Page Text}
            % Page footer box, arrow, and label
            \NAMEBOX{\ODDSIDEMARGIN}{0}{0}{0}{\TEXTWIDTH}{
              \FOOTHEIGHT}{}{Page Footer}
            %
            \VARROW{\ODDSIDEMARGIN}{0}{-\TAD}{0}{\FOOTHEIGHT}{l}{r}{
              \tt\string\footheight}
            %
            % Footskip arrow and label
            \VARROW{\RIGHTEDGE}{0}{\TAD}{0}{\FOOTSKIP}{r}{l}{
              \tt\string\footskip}
            %
            \HARROW{\ODDSIDEMARGIN}{\TEXTWIDTHY}{0}{0}{\TEXTWIDTH}{b}{}{
              \tt\string\textwidth}
            %
            \VARROW{\ODDSIDEMARGIN}{\FOOTSKIP}{-\TAD}{0}{
              \TEXTHEIGHT}{l}{r}{\tt\string\textheight$\rightarrow$}
            %
            \VARROW{\ODDSIDEMARGIN}{\HEADYORIGIN}{-\TAD}{0}{
              \HEAdHEIGHT}{l}{r}{\tt\string\headheight}
            %
            \VARROW{\RIGHTEDGE}{\HEADYORIGIN}{\TAD}{-\HEADSEP}{
              \HEADSEP}{r}{l}{\tt\string\headsep}
            %
            \VARROW{\RIGHTEDGE}{\INNERHEIGHT}{\TAD}{-\TOPMARGIN}{
              \TOPMARGIN}{r}{l}{\tt\string\topmargin}
            %
            \NAMEBOX{\ODDSIDEMARGIN}{\HEADYORIGIN}{0}{0}{\TEXTWIDTH}{
              \HEAdHEIGHT}{}{Page Header}
            %
            \NAMEBOX{\MARGINNOTEXORIGIN}{\MARGINNOTEYA}{0}{0}{
              \MARGINPARWIDTH}{\MARGINNOTEHEIGHT}{}{\shortstack{
              Margin\\note A}}
            %
            \VARROW{\MARGINNOTEXORIGIN}{\MARGINNOTEYA}{-\TAD}{
              -\MARGINPARPUSH}{\MARGINPARPUSH}{l}{r}{
            \tt\string\marginparpush}
            %
            \NAMEBOX{\MARGINNOTEXORIGIN}{\MARGINNOTEYB}{0}{0}{
              \MARGINPARWIDTH}{\MARGINNOTEHEIGHT}{}{\shortstack{Margin\\note B}}
            %
            \HARROW{\MARGINNOTEXORIGIN}{\MARGINNOTEYB}{0}{-\TAD}{
              \MARGINPARWIDTH}{b}{}{\tt\string\marginparwidth}
            %
            \HARROW{\MARGINNOTEXORIGIN}{\MARGINNOTEYC}{
              -\MARGINPARSEP}{\TAD}{\MARGINPARSEP}{t}{}{
              \tt\string\marginparsep}
            %
          \end{picture}}
        \end{picture}
      \end{small}
    \end{center}
  \end{figure}
  %%%%%%%%%%%%

  \clearpage
  %%%%%%%%%%

\end{fullpage}
%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Description of the refman-class family}
\label{refman}

The \texttt{refman.sty} was defined at the EDV-Zentrum (computing center) of
the TU\footnote{Technical University} Wien. This layout is suitable for
reference manuals, technical descriptions and similar applications. It is
based on the ideas shown in previous sections: The layout has a wide left
margin for headings and margin notes and smaller margins on the right side,
the top and the bottom.

In 1994 this layout was re-implemented as a class for the new \LaTeXe. 
This made it possible to include some minor improvements, such as the 
support of different paper sizes. The \texttt{refman.sty} was split 
into two classes
\texttt{refrep}\index{refrep.cls}, similar to \texttt{report} and 
\texttt{refart}\index{refart.cls}, similar to \texttt{article}.
These classes differ in the layout of the header and footer. The 
\texttt{refart} does not support the \cs{chapter} command.

The current version of both classes is described in this document. It 
serves as an example for the layout.


\subsection{Invocation}
\index{refart, invocation}
\index{refrep, invocation}

The \LaTeX\ local guide (if available) shows if this class is available 
at your \TeX\ installation or where to install it.  To use the 
\texttt{refart} class, simply call it with the \cs{documentclass} 
command:

\begin{verbatim}
\documentclass[11pt,a4paper]{refart}
\usepackage{german} % other packages you may want 
\end{verbatim}

\subsection{Options}
\index{options}

The \texttt{refart} class replaces \texttt{article} and \texttt{refrep} 
replaces \texttt{report}. They support all options of these classes 
except for the \texttt{twocolumn} option.

It supports the additional option \texttt{square} which makes the
\cs{textheight} equal to the \cs{textwidth}. 

Neither \texttt{refart} nor \texttt{refrep} support two column layout, thus
the commands \cs{twocolumn} and \cs{onecolumn} must not be used.

The index will be set in two column format and you can't change it 
with the means of this class. 

\subsection{Layout changes}

\subsubsection{Page design}

\index{page design, horizontal}\marginlabel{Horizontal:}
In this design the usable area for text (\cs{fullwidth}) is 
calculated as the paper width minus 2~\cs{papermarginwidth}. The default
value for \cs{papermarginwidth}\index{papermarginwidth} is 1~Inch.

The option \texttt{smallborder} reduces \cs{papermarginwidth} to 0.25~Inch.
This is more suitable for documents viewed on screen, especially when
combined with the \texttt{a5paper} and \texttt{landscape} options.

Only a fraction of this width is used for the running text (\cs{textwidth}),
the remaining part forms a wide left margin (\cs{leftmarginwidth}) which is
used for headings and margin notes.  The \cs{textwidth} is 70~\% of the
\cs{fullwidth} by default, but this can be changed with the
\cs{settextfraction} command\index{settextfraction} which accepts arguments
between 0 and 1.

\index{page design, vertical}\marginlabel{Vertical:} The text height is
calculated as the paper height minus 2~\cs{papermarginwidth}. The
\texttt{topmargin} is modified by some pagestyles. (see \ref{pagestyle}).

The pages are always set with a ragged bottom.

\subsubsection{Section headings}

The headings for \cs{section}, \cs{subsection}, and 
\cs{subsubsection} extend into the left margin, thus using the full 
width of the page.  They are not justified and hyphenation is 
discouraged.  A small space is kept free above and below the heading.  
Headings for \cs{section} and \cs{subsection} are set in a bold 
font.

The \texttt{refrep} class defines a different layout for the  
\cs{chapter} command: It always starts a new page and prints the 
chapter headings in a large bold font with a thick line above and 
below. This heading uses the full width of the page.

A similar heading is created by the \cs{part} commands which is 
available in both classes. It uses a roman part number instead of the 
arabic section number.

The \cs{maketitle} commands sets the title of the document in the 
same layout when no special title page is requested.  (This is the 
default for \texttt{refart}.  To suppress the title page in a 
\texttt{refrep} document, you can use the \texttt{notitlepage} option.) 
The name of the author and the date is printed in italic flush right 
below the document title.

\subsubsection{Paragraphs}

Paragraphs are separated by a vertical space (\cs{parskip}) of 
half a line (\verb|0.5\baselineskip|) plus a stretchable length of 2~pt.
Paragraphs are not indented.

The vertical spacing inside, above and below a list environment is the 
same as in the running text.

\subsection{Footnotes}\index{footnote}

The footnote layout consists of a small margin (1em) which contains 
the footnote symbol. A small space is set between the symbol and the 
footnote text. The paragraphs of the footnote are not indented. There 
is currently no space between two footnotes, I'm not sure it this will 
stay this way. The footnote symbol is set as a superscript. This may 
change in later versions. I'm relying on user feedback to finally 
solve this.

\subsubsection{Description environment}
\index{description environment}

The \texttt{description} environment will use the whole left margin 
for the description label. 

\seealso{Section \ref{layout}}
You will find examples in the section~\ref{layout}.

\subsubsection{Positioning of margin notes}

Margin notes (\cs{marginpar}) are always put into the left margin. 
They use the whole width of the margin.

The minimum space between two margin notes is set to 0 to prevent 
them from being shifted around when many margin notes are used.

\subsubsection{Headers and Footers} \label{pagestyle}
\index{pagestyle}

The page style \texttt{plain} puts the page number into the footer in 
the right corner. When the option \texttt{twoside} is active, the page 
number of left pages is put into the left corner.

\index{headings} \index{myheadings} The pagestyles \texttt{headings} and
\texttt{myheadings} create a header which spans the whole width of the page.
The headings contain the running head (\cs{section} and \cs{subsection} in
\texttt{refart} and \cs{chapter} and \cs{section} in \texttt{refrep}) when
\texttt{headings} is used or a fixed text that can defined  with the
\cs{markboth} command when \texttt{myheadings} is used. The heading will be
set in a slanted font and separated from the body by a thin line.

\index{footings}
\index{myfootings}
In addition to the standard classes, \texttt{refman} supports a style 
for footers, which is used in this documentation. The information is 
exactly the same as in the headings but now printed in the footer with 
a thin line above.

To use a user-defined string you can say:
\begin{verbatim}
\pagestyle{myfootings} % or myheadings
\markboth{left title}{right title}
\end{verbatim}

The \texttt{heading} and \texttt{myheading} commands increase the top margin
by one line while the \texttt{footings} and \texttt{myfootings} commands
decrease the top margin by one line.  The page styles \texttt{empty} and
\texttt{plain} leave the top margin unchanged. You should not combine
headings and footings in one document.

User feedback has shown that it is not a good idea to combine \texttt{plain}
and \texttt{(my)heading} either. Therefore I changed the layout of the
\cs{chapter} page to \texttt{empty}. Maybe it is necessary to define a
\texttt{hplain} and \texttt{fplain} pagestyle or to define some magic to use
the correct definition of \texttt{plain}. Feedback is welcome.

\subsection{Additional commands}

\subsubsection{Marginlabel}
\index{marginlabel}

The command \verb|\marginlabel{xxx}| prints the text \texttt{xxx} right
justified into the left margin. Please note that a \cs{marginpar} will print
it left justified.

\marginlabel{Example:} The word ``Example'' in the left margin is 
printed with the command \verb|\marginlabel{Example:}|

\subsubsection{Attention}
\index{attention}\index{attentionsymbol}\index{manfnt}

The command \cs{attention} puts an exclamation mark with an arrow 
pointing to the text into the left margin.\attention{} This is an 
example for \cs{attention}.

\renewcommand{\attentionsymbol}{\texttt{:-)}}
\attention
Since version 2.0c you can change the symbol used for the 
\cs{attention} command using a 
\verb|\renewcommand{\attentionsymbol}{\texttt\{:-)\}}|
command. To get the default back use
\verb|\renewcommand{\attentionsymbol}| \verb|{\large \bfseries ! $\rightarrow$}|
\renewcommand{\attentionsymbol}{\large \bfseries ! $\rightarrow$}

Since version 2.0c \cs{attention} takes an optional argument to define the
symbol used in the margin. Thus you can change the symbol once, without
having to restore it later. Do not abuse this
feature\attention[\texttt{:-(}], it is primarily meant as an support for the
\texttt{manfnt} package which enables you to use the ``dangerous bend'' and
``double dangerous bend'' signs.

The \texttt{manfnt} package is no longer enclosed with Refman, it
has grown and is now a package of its own.

\subsubsection{Seealso}
\index{seealso}

The command \verb|\seealso{n}| prints an arrow and its argument into 
the left margin. You will find examples for this in the left margin 
and in \seealso{Chapter 1} chapter~1.

\subsubsection{Maxipage environment}
\index{maxipage}

The \texttt{maxipage} environment is a special kind of \texttt{minipage}
which extends over the full width of the page. It can be used for long
formulas or \texttt{tabular} environments. You may use \texttt{maxipage}
environments inside floats. You cannot use margin notes inside a
\texttt{maxipage} and no page break will occur while in a \texttt{maxipage}.
A \texttt{maxipage} is always a paragraph of its own with a thick line above
and below. You can disable these lines with the
\cs{maxipagerulefalse}\index{maxipagerule} command. They are on by default.

The following paragraph is an example for a \texttt{maxipage}:
\nopagebreak
\begin{maxipage}
This very long line is an example for a \texttt{maxipage}. It extends 
over the full width of the page, including the left margin.
\end{maxipage}\nopagebreak
This is normal text after the \texttt{maxipage}.

\subsubsection{Fullpage environment} \label{fullpage}
\index{fullpage}

The \texttt{fullpage} environment consists of one or more pages where 
the text extends over the full width of the page. You cannot use 
margin notes inside a \texttt{fullpage} environment. A \texttt{fullpage} 
will always start and end on a page of its own. It may be used for 
large tables, program listings or anything that does not fit into the 
normal layout.

\seealso{Page \pageref{bild}}
Page~\pageref{bild} is an example for a \texttt{fullpage}.

\subsubsection{Noparskip}

The \cs{noparskip} removes the vertical space between two 
paragraphs. It is similar to the \cs{noindent} command that removes 
the indent of the first line of a paragraph.

\subsubsection{Setleftmarginwidth}
\index{setleftmarginwidth}

The \cs{setleftmarginwidth} command is no longer supported. You can 
achieve similar results by using the \cs{settextfraction} command.

\subsubsection{Descriptioncolon}
\index{descriptioncolon}

By default a colon is printed after the description label.  The command
\cs{description\-colonfalse}  disables the colon, the
\cs{description\-colontrue} re-enables it.

\subsubsection{Descriptionleft}
\index{descriptionleft}

The \cs{descriptionlefttrue} command sets the description label 
left justified into the margin. The default is right justified which 
will be achieved with \cs{descriptionleftfalse}

\subsubsection{Maxipagerule}
\index{maxipagerule}

You can disable the rules before and after a \texttt{maxipage} with the
\cs{maxipage\-rulefalse} command and re-enable them with the
\cs{maxipageruletrue} command.  The default is on.  You should not mix
\texttt{maxipage}s with and without rules in one document.

\subsubsection{Condbreak}
\index{condbreak}

The command \verb|\condbreak{2cm}| ensures, that the next 2~cm are 
either completely on this page or completely on the next. No 
page break will appear in the next 2~cm.

This is really a hack to achieve what the \cs{samepage} command often fails
to do.

\subsubsection{Example}
\index{example}

The \texttt{example} environment acts like a \texttt{verse} 
environment but uses a \texttt{tt} font.  

\subsubsection{Pageperchapter}
\index{pageperchapter}

The command \cs{pageperchapter} creates page number that start with 
1 for every new chapter. This may be useful for larger manuals. Since 
it works with chapters it is only available in the 
\texttt{refrep} class.

\subsubsection{Smallborder}
\index{smallborder}

The normal border around the page is 1~Inch. That is fine for a printed
document, but wastes a lot of space when a document is meant for reading on
screen. The option \texttt{smallborder} reduces the margin to 0.25~Inch. 


You can redefine the border with \cs{setlength}\cs{papermarginwidth}
\verb|{0.25in}|.
Call \verb|\setpagefraction{0.7}| afterwards to recalculate the page layout.

\subsubsection{Dvips}
\index{dvips}

The option \texttt{dvips} tells DVIPS about the current page size.

\subsubsection{Pdftex}
\index{pdftex}

The option \texttt{pdftex} tells PDF\TeX about the current page size.

\subsubsection{Pagesize}
\index{pagesize}

\texttt{pagesize} chooses the correct \cs{special}-command to tell the
DVI-driver about the paper size. It works with DVIPS and DVIPDFMX for DVI
output and PDF\TeX\ for PDF output.

\subsubsection{Ifpdfoutput}
\index{ifpdfoutput}

You can use \verb|\ifpdfoutput{pdftext}{dvitext}| to write different text
depending on the output format. This command was necessary to implement the
\texttt{pagesize} option and is available for the user as well.

The last four commands have been taken from KOMA-Script, thanks Markus.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput