diff options
Diffstat (limited to 'macros/latex/contrib/refman/layout_e.tex')
-rw-r--r-- | macros/latex/contrib/refman/layout_e.tex | 674 |
1 files changed, 674 insertions, 0 deletions
diff --git a/macros/latex/contrib/refman/layout_e.tex b/macros/latex/contrib/refman/layout_e.tex new file mode 100644 index 0000000000..df4815b73c --- /dev/null +++ b/macros/latex/contrib/refman/layout_e.tex @@ -0,0 +1,674 @@ +% % +% 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} |