refman – Format technical reference manuals
Author
Axel Kielhorn
License
LaTeX Project Public License 1.3c
Abstract
Migrated from https://ctan.org/pkg/refman
Migrated from https://ctan.org/pkg/refman
% %
% LAYOUT_E.TEX - Short description of REFMAN.CLS
% 99-03-20
%
% Updated for REFMAN.CLS (LaTeX2e)
%
\documentclass[twoside,a4paper]{refart}
\usepackage{makeidx}
\usepackage{ifthen}
% ifthen wird vom Bild von N.Beebe gebraucht!
\def\bs{\char'134 } % backslash in \tt font.
\newcommand{\ie}{i.\,e.,}
\newcommand{\eg}{e.\,g..}
\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
\title{Changing the layout with \LaTeX}
\author{EDV-Zentrum der TU Wien, Abt.~Digitalrechenanlage \\
Hubert Partl \\
1988-10-04 \\
English translation by\\
Axel Kielhorn\thanks{a.kielhorn@web.de}\\
1999-03-20 \\
H27.0 --- Version 1}
\date{}
\emergencystretch1em %
\pagestyle{myfootings}
\markboth{Changing the layout with \textrm{\LaTeX}}%
{Changing the layout with \textrm{\LaTeX}}
\makeindex
\setcounter{tocdepth}{2}
\begin{document}
\maketitle
\begin{abstract}
This document describes the capabilities of the
\texttt{refart} and \texttt{refrep} classes for \LaTeXe.
These classes do not work with \LaTeX\ 2.09. They contain some
improvements over the original \texttt{refman} style which may result
in different output and minor incompatibilities, but make refman
work with paper sizes other than ISO A4, which I consider an
improvement.
\end{abstract}
This manual is an addition to chapter~5 (``Designing It Yourself'') of
the \LaTeX-manual by Leslie Lamport. It was originally written in
1988 by Hubert Partl and updated by me during the development of
\texttt{refman}~2.0. The translation into English was done in summer
1998, almost 10 years after the initial release in German.
\tableofcontents
\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
\subsection{Author, Layout Designer and Compositor}
Every piece of writing -- from a short handwritten note to a printed
book -- consists of two components: \textbf{contents} and
\textbf{design.} In most cases the design is only a means to allow
the reader to understand the contents more easily.
\index{author}\marginlabel{Author:}
The \textbf{contents} will be written by the author of the document.
She usually is supported by the publisher, who issues guidelines
about how the document should be written and conducts proofreading.
When using \LaTeX\ the contents appears in the main part of the
document -- between \verb|\begin{document}| and \verb|\end{document}|
-- with some additional \LaTeX-commands that describe the meaning of
the different parts.
\index{designer}\marginlabel{Designer:}
The \textbf{design} of a printed document is usually defined by the
publisher who employs designers for this purpose.
The layout is defined in so-called class files. When writing a
document you have to specify the class you want to use with the
\verb+\documentclass+ command.
The document classes distributed with \LaTeX\ have been designed by
American layout designers according to the conventions used in the
USA. The ``Koma-Script'' classes have been adapted to European taste
and contain many small improvements.
\index{compositor}\marginlabel{Compositor:}
The compositor takes the contents from the author and formats it
according to the layout the designer specified.
When using \LaTeX, this job is done by the \TeX\ program and the
printing is done by a device driver.
\subsection{Changing the Layout}
If you want to use a layout different from the ones distributed with
\LaTeX, you have to take the following steps:
\begin{enumerate}
\item
The layout has to be defined.
This is usually a job for a professional designer.
\seealso{Chapter \ref{design}}
You can find detailed information about how change the design in
chapter~\ref{design}.
\item
The layout has to be programmed in \LaTeX. This can either result in
a ``package'' that changes the behaviour of a standard class, or
in the definition of a new ``class''. \texttt{Refman} used to be a
package that changed the definition of the \texttt{article}
class but is now a class of its own. When writing a new class, you
will have more work, but as a result more freedom to change things.
\seealso{Chapter \ref{layout}}
Chapter~\ref{layout} contains more information about the new layout.
\end{enumerate}
\section{The Art of Layout-Design}
\label{design}
\label{Layout-Design}
\index{layout design}
\subsection{Common Rules}
\index{rules}
There are almost no common rules because every kind of document has
different requirements and needs a specific layout. This layout
should consider \emph{who} will read the document, and \emph{how}.
An important criteria is if the reader will read the document from
start to end like a detective novel (linear reading) or if he wants to
find certain information as in a telephone directory or a
reference manual. \index{manual}\index{telephone directory}
In addition to that, the layout has to consider certain conventions,
like the habits of the reader or ``Corporate Design'' \index{corporate
desing} rules that distinguish publications from different publishers.
\footnote{Compare the layout of different daily papers or magazines
like ``page'' or ``invers''.}
\attention
The main purpose of a layout is to make sure the reader finds the
information he wants and is able to read and understand it easily.
The structure, readability, and consistency of a document is more
important than it's ``beauty''.\footnote{This is not always true for
adverts that usually contain no information at all and, picture
magazines where the beauty of the picture \emph{is} the contents.}
The following ``rules of thumb''\index{rules of thumb} will be valid
for most applications:
\begin{description}
\item[Line spacing]\index{line spacing}
The spacing between two lines should be larger than the spacing
between two words to guide the eyes of the reader.
\item[Line length]\index{line length}
The length of a line -- or when using multicolumn layout of a
column -- should be about 60 characters. When lines get longer they
are more difficult to read and it is easier to go to the wrong line
after finishing the current one. Increasing the linespacing may help a
little.
When lines get to short it is difficult to set them justified, and you
will get lots of hyphenated words.
\item[Page layout]\index{page layout}
Normal text pages should look the same throughout the document.
Figures, tables and special pages like the index need not appear in
the same layout but should take as much space as needed.
\item[Margin notes]\index{margin notes}
Margin notes are often more suitable than footnotes because they
appear right next to the text they refer to. Special margin notes are
the ``attention sign'' or the ``dangerous bend'' that guide the user
to important parts of the text.
\item[Headings and Footings]\index{headings}\index{footings}
Headings and footings should make it easier for the reader to orient
himself in the document. If you expect readers to copy single pages
from the document they should contain information about the paper as
a whole, just in case you need more information or want to cite the
whole paper.
If you expect the document to change often (like software manuals),
each page should contain a version information or at least a date.
\end{description}
\subsection{Special note for technical descriptions}
Let us compare three different layouts and check if they are usable for
technical descriptions, user's guides and reference manuals.
\footnote{This hint came from Paul Stiff, who teaches layout design at
the University of Reading.}
\begin{description}
\item[Plain \TeX]
The standard format use by plain \TeX\ has the great disadvantage
that the lines are much to long, which reduces the readability.
\item[Standard-\LaTeX]
The format used by \LaTeX{}s standard classes isn't ideal. The
line length is correct, but that leaves us with a wide unused margin.
The font used for section headings is too large. The Koma-Script
classes improve this and offer many ways to configure the fonts.
This is a good design for a paper one usually reads from start to
end.
\item[Reference Manual Style]
A new design that appeared some years ago and is used in recent
reference manuals, is much more suited for our purpose.
\footnote{The ``PostScript Reference Manual'' is one document that
uses such a design.}
\begin{itemize}
\item
The text is printed in rather short lines in the right part of the
page. This part is used for continuous reading.
\item
The wide left margin is used for headings and margin notes. Since
you now have a wide margin it is easier to use long margin notes to
supply additional information and to lead the reader to important
parts of the documents. Please note that the margin is always on the
left side thus two-sided printing does not look symmetrical. This is
done on purpose, because the reader will always start reading at the
left side, and with this layout section headers really ``stand out''.
In a symmetrical layout, half the headers would be buried in the text.
\item
Figures and tables are either inside the text column, inside the
margin or, if necessary, fill the whole page.
\end{itemize}
\seealso{Section \ref{refmanex}}
Section~\ref{refmanex} describes how to implement such a layout in
\LaTeX.
\end{description}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{How to change a \LaTeX\ layout?}
\label{layout}
\subsection{Advantages and Disadvantages of the text processing system \LaTeX}
\marginlabel{Advantages:} The big advantage of \LaTeX\ is, that it
implements a ``generic'' or ``logical'' design.\index{design,
logical}\index{design, generic} This means that the author has to
specify the \emph{meaning} of special parts of the text like:
headings, citations, lists, literature references, and so on. These
logical definitions will be processed by the system and printed in
the ``correct'' way. The meaning of \emph{correct} is defined in the
document class and additional packages.
The opposite of this is the ``visual'' design\index{design, visual}
that most text processors use. Here the author has to know the correct
way to set certain parts of the text and take care of the correct
printing.
The logical design makes it easier for the author to write
consistent documents (\ie\ same font and fontsize for section headings
of the same level, same layout for lists and enumerations, \dots).
\marginlabel{Disadvantages:}
The main disadvantage of \LaTeX\ is that the author has only limited
means to change the layout and that she has only four classes to
choose from. This has changed a great deal with the appearance of the
Script classes for \LaTeX\ 2.09 in 1992, which in turn have been replaced by
the even more improved Koma-Script classes for \LaTeXe.
Another disadvantage is that \LaTeX\ seems to be tied to the
``Computer modern'' font family. This is simply not true, at least
not when you have a PostScript printer. Setting up different fonts
isn't an easy task, but once they are installed they are as easy
to use as the standard fonts.
But \LaTeX\ is much more powerful and flexible: you can define an
arbitrary design by changing the definitions in the class files or
overwrite them by packages. This is easier than you may think and
happens more often than you think. Many universities and publishers
have their own \LaTeX\ class but do not distribute it to the
world.\footnote{You can find a generic \texttt{elsevier.cls} on CTAN
which you can use to prepare article before submission. This will be
replaced by the magazine-specific class at the publisher.}
\subsection{Input files and class files}
According to the principle of separation of content and design,
there are two kind of files:
\begin{itemize}
\item
The content and the logical structure of a document are defined in
the \LaTeX\ input file.
\item
The design (layout) is defined in the class files and packages.
\end{itemize}
Which class and packages files a document will use is defined at the
beginning of the input file. The \verb|\documentclass| command
selects the class and the \verb+\usepackage+ command specifies
additional packages.
To generate a paper you need at least two files, the input file and a
class file.
These two files represent the work of the author and designer as
explained in the introduction. Even if the author and the designer are
the same person, this has some advantages:
\begin{itemize}
\item
Similar documents (that appear in a series) have the same layout
because the layout is defined in a file of its own and not part of
the document.
\item
You can print the same contents without much work in different
layouts, \eg\ as an article for a magazine and as a chapter for a
dissertation.
\end{itemize}
\subsection{Class files and Packages}
\LaTeX\ supports a hierarchy of layout definitions.
\begin{itemize}
\item
The first file processed is the class file that is specified inside
the curly braces of the \verb|\documentclass| command. This
defines the kind of document you want to write.
\item
The optional argument of the \verb|\documentclass| command inside
the square brackets defines class options which select variants of
the basic layout,such as different font sizes.
\item
The last step is reading the packages specified by the
\verb|\usepackage| command. This command again takes options to
select the layout.
\item
You can change layout parameters in the input file, but this is
discouraged because it violates the principle of separation of
content and design.
\end{itemize}
There are some important differences between class and package files
and ``normal'' input files:
\begin{itemize}
\item
Class and package files should only contain definitions. They must
not output text.
\item
The ``at''-sign \texttt{@} is treated as a letter and therefore may
appear in command names. Most internal commands of \LaTeX\ contain
an \texttt{@} to prevent the author from using them accidentally.
\item
The extension of the file is \texttt{.cls}, \texttt{.clo} or
\texttt{.sty} instead of \texttt{.tex}.
\end{itemize}
\subsection{Changing the layout, step by step}
\index{changing the layout, step by step}
It is usually easier to change existing class files instead of
writing a new one from scratch. In many cases it is even sufficient
so replace some definitions and put them into a package instead of
creating a new class.
Please note that you are \emph{not} allowed to change the standard
classes distributed with \LaTeX. You \emph{have} to change the name
when you want to make changes. That is another reason to put small
changes in packages.
\subsubsection{Defining the differences between the desired and
the available layout}
The first step is to define the difference between the layout you have
and the layout you want.
\subsubsection{Finding the original definition}
The next step is to find out where the original layout is defined. It
is best to search the files in the following order:\footnote{This hint
came from Sue Brooks, who held a workshop for ``\LaTeX-Hacker'' at the
1988 \TeX-conference in Exeter.}
\begin{enumerate}
\item the \LaTeX\ manual by Leslie Lamport,
\item the \LaTeX\ documentations files \texttt{*.dtx} for the classes
or packages
\item the \LaTeX\ documentations files \texttt{*.dtx} for the kernel,
\item the \TeX book by Donald E.~Knuth.
\end{enumerate}
The files are usually documented quite well so you should be able to
change things even if you don't understand everything.
\subsubsection{Writing a new package file}
The third step is to create a new package. You choose an appropriate
name for the package (like \texttt{mysty}) and create a filename by
adding the extension \texttt{.sty}.
This file will only contain the definitions you want to change or the
new commands you want to define.
If you want to change definitions or certain parameters, the best way
is to copy them from the original file and modify them according to
your liking.
Defining new commands is easier when you find similar commands in the
original files which you can change.
It is always a good idea to include the reason you wrote the package,
the changes it makes and the new commands it defines in the file. You
should include the date of the last change and the \LaTeX\ version it
works with, just in case some internal \LaTeX\ commands you use will change.
When writing larger packages, it is an even better idea to use the
\texttt{docstrip} program which is used to document the \LaTeXe\ files. Thus
you have your code and documentation in one file and it's easier to
keep them from going out of sync.
\subsubsection{Using the new package}
To use the new package, you call it with the \verb|\usepackage| command.
This command executes the code of your package and changes the layout
as desired.
Example:
\begin{verbatim}
\documentclass[11pt,twoside,a4paper]{article}
\usepackage{mysty} %<- This calls the package "mysty"
\end{verbatim}
You shouldn't need to change anything else in your input file, unless
you defined new commands or environments that are not available in
standard \LaTeX.
\attention
When you copy your input file to a different computer you have to
include your new packages as well. Otherwise the document can't be
processed.
%%%%%% %%%%%%%%%% %%%%%%%%%% %%%%%%%%%% %%%%%%%%%
\subsection{A simple example (Equation numbers)}
Let's assume that you want to write an article where the equations are
numbered separately in every section. In the \LaTeX\ manual you find a
notice that the report class does something similar for every chapter.
Looking into the file \texttt{report.cls} you will find the following
commands that deal with equation numbers:\nopagebreak
\begin{verbatim}
\@addtoreset{equation}{chapter}
\def\theequation{\thechapter .\arabic{equation}}
% or in LaTeX2e since 1995/06/01:
\renewcommand\theequation{
\thechapter.\@arabic\c@equation
}
\end{verbatim}
You don't necessarily need to understand these two commands in detail.
Now you create an new file with the name
\texttt{eqpersec.sty}\footnote{Depending on the computer you are using
the name may be different like \texttt{EQPERSEC\_STY} on a CYBER
running NOS/VE. But note that you must not use spaces in the
filename.} and copy the commands above into that file. After that
you replace every occurrence of \texttt{chapter} with \texttt{section}
and add some comments.\nopagebreak
\begin{verbatim}
% This is equation_per_section.sty
% Short name: eqpersec.sty
% Original file by Hubert Partl 1988
% Modified by Axel Kielhorn 1996/01/01
% to support LaTeX 1995/06/01 and later
%
% reset the equation counter at the start
% of a new section
%
\@addtoreset{equation}{section}
% Equationnumber = sectionnummer.equationnummer
% Use only one of the below
% depending on you LaTeX version
%
%\def\theequation{\thesection .\arabic{equation}}
% or in more recent versions of LaTeX
\renewcommand\theequation{
\thesection.\@arabic\c@equation
}
\end{verbatim}
Whenever you use a \verb|\usepacakge{eqpersec}| command as in
\nopagebreak
\begin{verbatim}
\documentclass[11pt]{article}
\usepackage{eqpersec}
\end{verbatim}
you will get equations numbered according to your conventions.
%%%%%%%%%% %%%%%%%%%%%%%% %%%%%%%%%%%% %%%%%%%%%%%% %%%%%%%% %%%%%%%%%%%%
\subsection{A more complex example (Reference Manual)}
\label{refmanex}
We want to create a layout similar to the one used in the \textit{PostScript
Reference Manual}, with a wide left margin for headings and margin
notes and a small margin at the right and bottom.
\subsubsection{Page layout}
To define the new layout we use the commands described in the \LaTeX\
manual. For full details see the file \texttt{refman.dtx}.
%\pagebreak[2]
\marginlabel{Horizontal:}
First we define two new names for length that we will use often:
\cs{fullwidth} is the width of the whole page minus a margin of 1~inch
on every side.
%
\begin{displaymath}
\texttt{fullwidth} = \texttt{paperwidth} - 2\ \textrm{inch}
\end{displaymath}
%
From this the width of the text is calculated.
%
\begin{displaymath}
\texttt{textwidth} = \texttt{fullwidth} \times \texttt{textfraction}
\end{displaymath}
%
\cs{leftmarginwidth} is the width of the left margin that will be
used for headings and margin notes.
\begin{displaymath}
\texttt{leftmarginwidth} = \texttt{fullwidth} - \texttt{textwidth}
\end{displaymath}
%
This is a little more difficult in reality because the lengths have to
be rounded to full points and a possible two column layout -- as used
in the index -- must be taken into consideration.
\marginlabel{Vertical:}
The vertical layout is a little more difficult because you have to
deal with the page header and footer.
%
\begin{displaymath}
\texttt{textheight} = \texttt{paperheight} - 2.5\ \textrm{inch}
\end{displaymath}
%
The result of this calculation is rounded to full lines. Depending on
the page style -- headings or footings -- it is shifted up or down by one
line.
\vspace{0pt plus 1cm}
\subsubsection{Section headings}
The headings have to be modified to make them extend into the left
margin.
In file \texttt{classes.dtx} we find the \verb|\@startsection| command
that defines the layout of the headings. Only parameters 4 to 6 are
relevant for us: parameter 4 is the space above and parameter 5 the
space below the section. The 6th parameter does the actual formatting.
This is the original definition:\nopagebreak
\begin{verbatim}
\newcommand\section{\@startsection
{section}{1}{\z@}%
{-3.5ex plus -1ex minus -.2ex}%
{2.3ex plus .2ex}%
{\normalfont\Large\bfseries}}
\end{verbatim}
The commands for sub- and subsubsections are similar. Note that the
measures are all in \texttt{ex}, thus depending on the font size used.
We define a new command \cs{secshape} to format the headings. This
command uses the whole width of the page for the heading. To discourage
hyphenation of the heading we give it a high penalty. This still
allows hyphenation when absolutely necessary.
\begin{verbatim}
\newcommand\secshape{%
\leftskip=-\leftmarginwidth%
\rightskip=\@flushglue%
\hyphenpenalty=2000}
\end{verbatim}
This command is inserted into the 6th parameter of \verb|\@startsection|.
Since the headings now extend into the left margin, we can use a
smaller font and reduce the space between the text and the heading. The
new definition looks like the following:\nopagebreak
\begin{verbatim}
\newcommand\section{\@startsection
{section}{1}{\z@}%
{-2ex plus -1ex minus -.2ex}%
{0.5ex plus .2ex}%
{\secshape\normalfont\large\bfseries}}
\end{verbatim}
\vspace{0pt plus 1cm}
\subsubsection{Setting the margin notes}
The margin notes should always appear on the left side of the text.
The normal layout puts them into the outer margin in twoside layout.
The file \texttt{latex.dtx} contains the definition of the
\verb|\@addmarginpar| command which is responsible for the margin
notes. We don't have to understand the whole definition; the important
part is the internal variable \verb|\@tempcnta| that is either
\verb|\@ne| (1) when the note should appear on the right side of the
text or \verb|\m@ne| ($-1$) when it should appear on the left side.
This is done by the following lines:
\begin{verbatim}
\@tempcnta\@ne
\if@twocolumn
\if@firstcolumn \@tempcnta\m@ne \fi
\else
\if@mparswitch
\ifodd\c@page \else\@tempcnta\m@ne \fi
\fi
\if@reversemargin \@tempcnta -\@tempcnta \fi
\fi
\end{verbatim}
which we simply replace by:
\begin{verbatim}
\@tempcnta\m@ne
\end{verbatim}
The remaining lines that handle the setting of the margin note
depending on the parameter \verb|\@tempcnta| are left unchanged.
\subsubsection{Extensions}
The definitions described above are sufficient for simple applications
but in practical use one may want some additional commands.
\seealso{Appendix \ref{refman}} You will find the description for the whole new
class in the appendix~\ref{refman}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input lay_e2
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\printindex
\end{document}