Document preparation for project reports

Rob Pooley [email protected]

http://www.macs.hw.ac.uk/~rjp/DocPrep/DocPrep_files/frame.html

Requirements

• We are looking to produce a document between 40 and 60 pages long • It will contain – Diagrams – Illustrations – Citations and references • It will be structured into – Chapters – Sections – Sub-sections

Options

• There are two main options available to you – LaTeX – a document mark up package – Microsoft Word – a WYSIWYG document editor • Other possibilities exist, but are not well supported – HTML can deliver some of the text formatting capabilities, but is not suited to document production – Open Office offers a Microsoft Word clone for Linux • We recommend that you stick to LaTeX or Word • Choose the one that suits you and your project best

Document structure

• Whatever you decide, your dissertation will have the same overall structure – A title page – An abstract – A disclaimer – A contents – Optionally a list of figures – Optionally a glossary – A series of chapters – A list of references – Optionally a series of appendices

Title page

• In LaTex you can select a style which will produce a separate title page.

\documentclass[a4paper]{report} \begin{document} \title{How little I managed to do} \author{Rob Pooley \\Computer Science \\Heriot-Watt University \\ [email protected]} \maketitle \end{document} • In Word you can format a page to hold the title for yourself.

• You need to set the option to turn of page numbering.

• You should make the title page a separate section to prevent page numbering problems.

The abstract

• LaTeX allows an abstract to be incorporated by using a simple environment markup.

\documentclass[a4paper]{report} \begin{document} \title{How little I managed to do} \author{Rob Pooley \\Computer Science \\Heriot-Watt University \\ [email protected]} \maketitle \begin{abstract} Here's the summary of how little I did during the year.

\end{abstract} \end{document} • Word allows you to format an abstract page for yourself.

• You should place it in the same section as your contents and disclaimer

The disclaimer

• You are on your own in both LaTeX and Word when you come to write the standard disclaimer.

• In both you need to place it on a separate page by forcing a page break.

• In both you want to make sure it is not a numbered page.

• In LaTeX you can use a quote environment to format it nicely.

Here's the LaTeX so far

\documentclass[a4paper]{report} \begin{document} \title{How little I managed to do} \author{Rob Pooley \\Computer Science \\Heriot-Watt University \\ [email protected]} \maketitle \begin{abstract} Here's the summary of how little I did during the year.

\end{abstract} \begin{quote} This work is all my own, except where I blatantly stole it from others. I hereby certify that you would be insane to believe anything I say in what follows.

\end{quote} \newpage \end{document}

Chapters and contents pages

\documentclass[a4paper]{report} \begin{document} \title{How little I managed to do} \author{Rob Pooley \\Computer Science} \maketitle \begin{abstract} Here's the summary of how little I did during the year.

\end{abstract} \begin{quote} This work is all my own, except where I blatantly stole it from others. I hereby certify that you would be insane to believe anything I say in what follows.

\end{quote} \tableofcontents \chapter{What I hoped I would be able to do} This chapter contains the incredibly optimistic claims I made in my first deliverable.

I was obviously never going to make this work.

\chapter{What I actually did} This chapter intentionally left blank.

\end{document}

Sections and sub-sections

• LaTeX allows you to start titled sections, sub-sections and paragraphs.

\documentclass[a4paper]{report} \begin{document} \title{How little I managed to do} \author{Rob Pooley\\Comp Sci\\ [email protected]} \maketitle \begin{abstract} Here's the summary of how little I did during the year.

\end{abstract} \begin{quote} This work is all my own, except where I blatantly stole it from others. I hereby certify that you would be insane to believe anything I say in what follows.

\end{quote} \tableofcontents \chapter{What I hoped I would be able to do} \section{The ridiculous claims} This chapter contains the incredibly optimistic claims I made in my first deliverable.

\subsection{The awful truth} I was obviously never going to make this work.

\chapter{What I actually did} \section{The void} \subsection{The emptiness} \paragraph{The facts} This chapter intentionally left blank.

\end{document}

Citations

• Anywhere in a LaTeX document (almost) you may insert a \cite command, with a label.

• At the end of your document, before the final end, you must create a

thebibliography

list.

• All the labels used in \cite commands have to be listed in the bibliography.

• LaTeX keeps the labels in the text in synch with those in the bibliography automatically.

Eddy was a coward\cite{gossip}.

Dave has no style\cite{obvious}.

\begin{thebibliography}{XXXXXXXX } \bibitem[gossip1]{gossip} Overheard in the Microbite.

\bibitem{obvious} Well known fact.

\end{thebibliography}

Illustrations

• LaTeX allows you to include figures • Figures can contain graphics, drawings or anything else you like • Figures have captions • Figures are numbered • Figures float unless you fix them in place \usepackage{epsf} \bibliographystyle{plain} ....

\begin{figure}[ht] \caption{\label{use-case}Use case diagram for two phase commit} \vspace{3mm} \setlength{\epsfxsize}{.7\tex twidth} \epsffile{usecase2pc.ps} \end{figure}

Cross references

• LaTeX allows you to put a label onto a caption, chapter or section heading • You can then reference that figure, chapter or section within the text \begin{figure}[ht] \caption{\label{use-case}Use case diagram for two phase commit} ….

Figure~\ref{use-case} shows use cases

Word and citations

• Word allows cross referencing • Word does not support citations directly • Word allows cross references to numbered lists, which supports numbered citations if you use it that way • Word allows cross references to paragraph texts, which is not quite the way to get textual labels • This can also be used to reference tables, headers etc.

Drawings

• Word allows you to draw directly using the Drawing toolbar • Word also allows you to add most kinds of graphics and image files, such as PostScript, PDF and JPEG.

• Word puts the images where you place them • LaTeX can import PostScript and PDF files • LaTeX has a textual language to describe drawings. This is very hard to use.

• LaTeX “floats” pictures to avoid blank space. This can result in pictures being out of step with the text.

• Word has a built in equation editor • This works very well for standard Maths symbols • There is also a markup language called field codes, which allow direct manipulation of symbols to create a customised formula language. You type ctl + F9 to open up a formula brace pair.

• If you double click on such an equation, you may lose the capacity to edit it.

Equations

• LaTeX was defined on top of TeX • TeX is a mathematical formula markup language • Mathematicians use LaTex extensively for its power in typesetting mathematical documents

Pros and cons

• Word – Is WYSIWYG – Allows easy drawing – Supports lots of imported graphic file formats – Is flexible • LaTeX – Gives a controlled default format – Handles citations and referencing well – Runs on Linux and Windows – Has no easy citation features – Requires you to do a lot of hand formatting – Is now on Windows and Linux as Open Office – Only works with Postscript and PDF – Has a horrid drawing capability – Is not very flexible

References

• The bast reference for LaTeX is • The Not So Short Introduction to LaTeX 2  http://www.ctan.org/tex-archive/info/lshort/english/lshort.pdf