%% %% Template for documentation in LaTeX %% Tobias Wrigstad, tobias@dsv.su.se, 2002-11-19 %% %% Most commands used this sample document should be %% understandable from how they are used here. They are %% further explained in the document `The not so short %% guide to LaTeX' by Tobias Oetiker.For the benefit %% of foreign students, the comments in this file will %% be written in English. %% \documentclass[a4paper,11pt,twoside,titlepage,openany]{book} %% Declares that the current document shall use the book-template %% which meant that it will have headers, use chapters for partitioning %% the text etc. %% Target paper size is A4 paper, text is 11 pt if not explicitly %% altered, it will be printed on two-sided paper and it will use %% a special title page for printing title, author and date. %% `Openany' specifies that a chapter can begin on both right and left %% pages. \usepackage[latin1]{inputenc} %% The use of packages in LaTeX is quite analogous with packages in %% Java. The input encoding packages enables LaTeX to use non-English %% code pages (teckentabell). In this case latin1, to enable the use %% of Swedish characters such as å, ä, ö and accented characters such %% as é without special treatment. \usepackage[swedish]{babel} %% Remove when writing in english! %% Load Swedish hyphenation and tell LaTeX that we are writing in %% Swedish. This makes LaTeX print 'kapitel' instead of 'chapter' etc. \usepackage[dvips]{graphicx} %% Load support for special graphics, such as UML diagrammes etc. %% Importing graphics in LaTeX is a little tricky so please assign %% someone to learn to master it in the beginning of your project. %% Note that only .EPS-files (encapsulated post script) may be %% used! \usepackage{url} %% Defines the command \url{} that can be used to typeset url:s %% in text %% Now we will declare the title and author of this document. \title{\LaTeX{} at DSV2:PVT} % set the document's title \author{Tobias Wrigstad \\ % the \\ command is a line break \texttt{tobias@dsv.su.se}} % \texttt{...} gives typewriter text \date{\today} % set the document's date to today's date %% Here ends the declaration section, the so-called 'preamble'. Now, %% the document text begins. \begin{document} %% The beginning of the document %% \maketitle %% Print the title, the author and the date %% Since we specified titlepage above, this will be printed on %% a single page with no other text in the beginning of the document \chapter{Introduction} %% Declares the beginning of a new chapter. The book-template REQUIRES %% the use of chapters, otherwise section numbering will be erroneous. %% Since we specified that the document should be written in swedish, %% 'Kapitel 1' will be printed at the top of the page. \section{What is this LaTeX, anyway?} %% No text should be placed outside a section. This generates a section %% head in bold face with section number 1.1 (chapter 1, section 1). Now, I can begin to write some text. Note that the text automatically becomes size 11 pt because of the declaration in the preamble. Text is automatically justified (raka höger- och vänstermarginaler) and new paragraphs are automatically indented. Note (in the code) how linebreaks and double spaces are ignored by \LaTeX{}. A new paragraph is started by an empty line in the text. Note the indentation. This is clearly visible from the source code. \emph{N.B. You should read this document in parallel with the source code!} \subsection{Text formatting} %% Generates a subsection with number 1.1.1 %% Text can be \emph{emphasized} (which more or less means \textit{italicized} in the book template). Text can also be \textbf{bold faced} or in \textsc{Script Capitals} or without serifs i.e. \textsf{sans serif}. An easy way to show code snippets is to use the \texttt{verbatim} (note how I switched to typewriter text just for one word or phrase) environment: %% Begins preformatted text \begin{verbatim} This text is preformatted, meaning that linebreaks are not ignored as well as double spaces (%% comments are not ignored) \end{verbatim} %% Ends preformatted text In the preformatted text section, text is written exactly as it is typed in the source code. Line breaks are \emph{not} automatically inserted when the end of the line is reached. Instead text can flow into the right margin or even out of the page! Thus, lines must be broken by hand in the \texttt{verbatim} environment. \subsubsection{The next level of sectioning lacks a number} Thus, it will not appear in the table of contents. \section{The use of tables} First: note how this section's name is showed in the header. All pages (except the first page of every chapter and the title page) automatically becomes a header with a section name and number. You may wish to use tables in your project documentations. Tables are quite easily created. Below, a simple sample table is shown. For a more comprehensive documentation of how to create tables, see `The not so short guide to \LaTeX'. %% A good exercise: add a reference to that doc here! The table below is generated with this code: \begin{verbatim} \begin{tabular}{|l|r|c||p{1.5cm}|} \hline left justified & right justified & centered & width specified \\ \hline \hline \end{tabular} \end{verbatim} \begin{tabular}{|l|r|c||p{1.5cm}|} %% Note that a table is called a tabular! %% The character | declares that a vertical line should separate %% two columns. || means, two vertical lines etc. %% The character l creates a left justified column with a width just %% enough to contain the longest line of text in the column. %% The character r is analog with l but text is right justified. %% The character c is analog with l but text is centered. %% p{1.5cm} generates a column with width 1.5cm with left justified text. \hline %% Generated a horizontal line left justified & right justified & centered & width specified \\ %% The character & skips to next column %% \\ ends the current row, all rows must be ended with \\ \hline \hline \end{tabular} Text may be formatted with italics, bold face etc. inside a table. However, as we can clearly see from the appearance of this page, the placing of the table is not correct. It almost overlaps with the text of this paragraph. Tables should always be placed in a special environment called a \emph{float}. A float contains a table or a figure and ensures that it is placed correctly in the document. If there is not enough space on a page to place a float, the float \emph{floats} over to the next page, hence the name. Now, we place the table inside a float: \begin{table}[h] %% Creates a float that contains a table %% The character h read `here' and specifies that the float should appear %% at the same place in the text as where it was typed. %% Other options are 't' for top of page, 'b' for bottom of page and 'p' %% for a special floats page, i.e. an empty page with only the table on %% (and other floats that might fit onto the same page) %% \begin{center} %% Centers the table in the float %% \begin{tabular}{|l|r|c||p{1.5cm}|} \hline left justified & right justified & centered & width\newline specified \\ \hline \hline \end{tabular} \end{center} %% End the centering %% \caption{My table} %% Gives a explanatory text/a name to the table in the float \label{tab:my-table} %% See the cross referencing section for above command \end{table} %% End the table Much better, don't you think? Note that we have also given the float a caption. Since the float was a table float (examine the code), the caption automatically becomes the text `Tabell'. This would not be possible if we did not place the table in a float since then, \LaTeX{} cannot determine where the table and the explanatory text begins or ends. \begin{table}[t] \begin{center} \begin{tabular}{c|p{10cm}} \hline \textsf{c} & \textsf{p} \\ \hline 1 & lines inside a column with a specified width will be broken automatically if their length exceeds the width of the column. This is not the case for centered, left justified or right justified columns where lines must be broken by hand \\ 10 & Ten \\ 1000 & Thousand \\ \hline \end{tabular} \end{center} \caption{This table is autmatically placed at the top of the page where it appears in the code} \end{table} \section{Figures} \label{includegraphics} %% Labels are used to create references in a document, labels will %% be explained later %% Figures should also be placed in floats and be given captions. Figures should contain diagrammes etc. Figures are included with the use of this command: \begin{verbatim} \includegraphics[options]{name of .EPS file} \end{verbatim} Where the options are a list of keys with values separated with commas: \begin{description} %% This is a list, lists will be explained in a little while %% \item[scale=] A scale factor from in per cent. \item[angle=] An angle \item[bb=] Creates a \emph{bounding box}, i.e. a rectangle within the included image. Everything outside the bounding box is omitted. A bounding box is specified by four values, first the x and y values of the lower left corner and then the x and y values of the upper right corner. \item[clip=] True or false. Specifies if the the contents outside of the bounding box should be omitted or not. \end{description} The figures on the next page were imported with the following commands: \begin{verbatim} \includegraphics[scale=.25]{sample.eps} \includegraphics[scale=.50]{sample.eps} \includegraphics{sample.eps} \includegraphics[angle=45]{sample.eps} \includegraphics[bb=4mm 0mm 17mm 17mm, clip=true]{sample.eps} \end{verbatim} They all reside in the same float. The last image is clipped by the use of a bounding box. Normally, using a bounding box is not necessary. \begin{figure}[!t] %% This is a figure float, it works exactly as a table float but writes %% 'Figur' instead of 'Tabell' in the caption. \begin{center} \includegraphics[scale=.25]{sample.eps} \includegraphics[scale=.50]{sample.eps} \includegraphics{sample.eps} \includegraphics[angle=45]{sample.eps} \includegraphics[bb=4mm 0mm 17mm 17mm, clip=true]{sample.eps} \end{center} \caption{The same figure included five times} \end{figure} \section{Lists} \LaTeX{} supports the generation of lists in many ways; there are bullet lists, enumerated lists, descriptive lists etc. Below, the most common lists are shown. Look at the source code to see how they are generated. \subsubsection{Bullet list} \begin{itemize} \item In a bullet list, all list items are preceeded by a bullet, $\bullet$ \begin{itemize} \item Lists can be nested, i.e. a list item can contain a new list (even of a different kind). Note how the appearence of the nested list changes. \end{itemize} \item New items are automagically indented \end{itemize} \subsubsection{Enumerated list} \begin{enumerate} \item In a enumerated list all list items are preceeded with a number. \begin{enumerate} \item In nested enumerations, different enumeration styles are used. \begin{enumerate} \item A maximum of four levels of nesting is supported. \end{enumerate} \end{enumerate} \item New items are automagically indented \end{enumerate} \subsubsection{Descriptive list} \begin{description} \item[Descriptive list] A descriptive list is a list where each item has a name written in bold face. Note how a descriptive list was used to show the options of includegraphics in Section \ref{includegraphics}, page \pageref{includegraphics}. %% \ref and \pageref are used to refer to different places inside a document %% their usage will be explained in a little while \end{description} \section{Floats} Just a short note on floats. Always place tables and figures in floats. Use table floats for tables and figure floats for figures. Look at the source code on lines 162 and 265. Read the comments and experiment! \section{Structuring your documents} This purpose of this document is to be a guide to formatting documents in \LaTeX. To be readable codewise -- it is very badly structured (even technically). When you write your own documents in \LaTeX{} you must not be as sloppy as this. \subsection{File inclusion} A document can be divided into several different files to facilitate different people working at the same document at the same time. Files are included with the command: % \begin{verbatim} \input{file name} \end{verbatim} File name must be without spaces and file extension (extension \emph{must} be \textsc{tex}). If a file is placed in another directory, the entire path from the main file to the included file must be specified, \emph{e.g.}\ ``\texttt{../../../myfile}''. \subsection{Cross referencing} In large documents (such as those that you are about to write) it is often necessary to refer to a different place in the text. This is easy in \LaTeX{} with the commands: % \begin{verbatim} \label{name} \ref{name} \pageref{name} \end{verbatim} The \verb.\label. command associates a name with a place in the document text. This can be issued almost everywhere. By using \verb.\ref., the number of the section (or float or list item number etc.) where the label appeared is printed; \verb.\pageref. prints the number of page where the label appeared is printed. Depending on where the \verb.\label. was issued, different numbers appear. Experiment! Look at lines 220 and 329 in the source code for an example. \subsection{Citation with the bibliography} Hopefully, you will divide your project documentation into several different documents. Needless to say, you will sometimes (or quite often) need to refer between these documents, e.g. to say that X is explained in Y etc. To refer to external documents, you must first create a bibliography (litteraturförteckning) of documents that you wish to refer. A bibliography is included at the end of this document (look at the source code to see how it is constructed). To refer to an external document, the command \verb.\cite. is used. It works analogously with \verb.\ref. except that there is no corresponding label. Instead, the names that may be cited are specified by the bibliography at the end of the document. The bibliography at the end of this document contains three documents with the names `gof-patterns', `captain69' and `template'. Either of these names can be used by cite. For example, \verb.\cite{captain69}. produces \cite{captain69}. %% Here, \cite is used with a label from the bibliography at the end %% of the document In text, you usually write, `\ldots for a more detailed description of the proxy-pattern, see \cite{gof-patterns}\ldots' When referring to your own documents, you generally need to specify more exactly the location of the text to which you are referring, e.g. `\ldots for a more detailed description of the proxy-pattern, see \cite[pp. 257-263]{gof-patterns}\ldots' This is achieved by \verb,\cite[pp. 257-263]{gof-patterns},. The text in the brackets can be any text, not necessarily page numbers. \subsection{Table of contents} In \LaTeX{}, a table of contents is easily generated by issuing the command \begin{verbatim} \tableofcontents \end{verbatim} The table of contents in the course documentation is automatically generated using this command. (Exercise: insert it in this document and see the results -- note that the \LaTeX\ compiler will tell you to rerun the compilation at least one time!) \section{Line breaking} In \LaTeX{}, line breaking is a real issue. This is due to that \LaTeX{} must obey a number of typographic rules that is embedded in the system. In some cases, e.g. \LaTeX{} don't know how to break a very long word, it is necessary to manually hyphenate or break the line by hand. There are a couple of different approaches to this. The line below illustrates one problem: \\[3mm] %% Note that you can specify how tall a line break should be %% 1)~~Thislinedoesnotcontainanyspacesandwhen{\LaTeX}triestobreakititwillhaveproblems. %% The character ~ is a `hard space' that will not be compacted by LaTeX %% always use hard spaces (also in Microsoft Word!) when writing e.g. 1~000 kr %% to avoid line breaking between 1 and 000. %% \begin{description} \item[hyhenation] When \LaTeX{} doesn't know how to hyphenate a word, you can do it manually with a special (soft) hyphen, \verb.\-.. This will insert a hyphen \emph{if necessary}. If the text is altered later and suddenly, the long word fits into one line without hyphenation, the hyphenation will not be inserted. A long word could have many soft hyphens to enable hyphenation at several different places. \item[linebreak] The command \verb.\linebreak. or \verb.\linebreak[num]. breaks a line and justifies the margins. If you use \verb.\linebreak[num]., you must specify a number between 0 and 4 that is an indication of how much you want the line broken (higher number indicates higher need for line breaking). This enables the removal of deprecated line breaks that are no longer necessary due to subsequent changes in the text. \item[newline] The command \verb.\newline. breaks a line. There is a shorthand for \verb.\newline. in the command \verb.\\. or \verb.\\[length].. The latter breaks a line but also specifies how much whitespace should be inserted before next paragraph. Sometimes, \LaTeX\ is unable to justify the right margin of a section, simply because there is not enough words on the for \LaTeX\ to insert enough space between so to give the line the desired length. This is signalled by the \LaTeX-compiler as an ``underful hbox''. There is one such example in this document in the last column in the Table \pageref{tab:my-table}. Look in the code on the first table on the same page to see the use of \verb.\newline. (line 175 in the code). You may also want to look at the output of a compiler, fix the faulty table and recompile. Note that, depending on the situation, \verb.\linebreak. might actually be the solution (if you want the justified margins). This command does not, however, stretch the length of a word. \end{description} \section{Running \LaTeX} This is a brief explanation of how to transform a \textsc{tex} source file into a viewable/printable document. \LaTeX{} is invoked from the command line with the main file as single parameter: % \begin{verbatim} $ernst-hugo>latex my-file \end{verbatim} This will cause the file to be `compiled' (in some cases it must be compiled several times due to forward references etc., in this case \LaTeX{} will print a message indicating that the file should be recompiled) and produce a viewable file called a \textsc{dvi} file (DeVice Independent). If there are any compiler errors, these will be reported and the compilation aborted (without producing a \textsc{dvi} file). The \textsc{dvi} file is viewed with the command: \begin{verbatim} $ernst-hugo>xdvi my-file.dvi \end{verbatim} Some machines may have additional (and better) programs for viewing \textsc{dvi} files, like \texttt{kdvi} (available in the k desktop system, \url{www.kde.org}). After a \textsc{dvi} file is produced, another program called \texttt{dvips} is used to produce a postscript file or feed it to the printer. To create a postscript file from a \textsc{dvi} file (that can be emailed to your contractor): % \begin{verbatim} $ernst-hugo>dvips -ta4 -Ppdf -ooutfile.ps my-file.dvi \end{verbatim} This will cause the contents of my-file.dvi to be printed to the postscript file \texttt{outfile.ps}. \textbf{Please be careful when using \texttt{dvips}! If you forget the \texttt{-o} flag, your prints will be spooled to the printer instead of to a PostScript file!} To print the contents of a \textsc{dvi} file to a printer: % \begin{verbatim} $ernst-hugo>dvips -ta4 my-file.dvi \end{verbatim} To convert a \textsc{ps} file to a \textsc{pdf} file: % \begin{verbatim} $ernst-hugo>ps2pdf13 mypsfile.ps \end{verbatim} This creates a new \textsc{pdf} file names \texttt{mypsfile.pdf}. If \texttt{ps2pdf13} is not available, but \texttt{ps2pdf} is, then the same result can be achieved using \texttt{ps2pdf -dCompatibility=1.3 myfile.ps}. \section{How do I start?} Copy the first 61 lines of this file and add a \verb.\end{document}.. Strip the comments if you think that you don't need them. This should compile just fine. Alter the title, author and date. Now you have a one-page \LaTeX{} document with only the titlepage. Now, start writing between \verb.\begin{document}. and \verb.\end{document}.. The bibliography is easily copied from this document into your new document and the contents of the bibitems altered\footnote{Tip: you can use the same bibliography file for all documents and just include it with the input command. Or better still, learn Bib\TeX, which is a very potent powerful bibliography system for \LaTeX.}. Good luck! \paragraph{Comment} On the course DSV2:PVT, all documentation managers will be supplied with a copy of `The not so short guide to \LaTeX' and also be given an introduction on how to run \LaTeX{} and write a small \textsc{tex} file. It might be a good idea to assign a project member to work out the details of \LaTeX{} that you think you need. That way, you will produce a local expert that can be called in to solve \LaTeX{} problems as they arise. \begin{thebibliography}{99} %% Start of bibliography. It works almost exactly like a list, but with %% \bibitem instead of \item. %% \bibitem{gof-patterns} \textit{Design Patterns, Elements of Reusable Object-Oriented Software}. Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides. Addison-Wesley 1995. \bibitem{captain69} \textit{Safe as Milk}. Captain Beefheart, Zoot Horn Rollo, Winged Eel Fingerling, Alex Snouffler, John French. Budda Records 1969. \bibitem{template} %% Gives a name for citations to the following document, in this case `template' %% \textit{Title of document}. List of authors in the order they appear in the document Name of publisher, or other remark and year of publication. Document number or version number is good to include. \end{thebibliography} \end{document} \end{document} %% The end of the document %%