Document preparation for project reports

1. Document preparation for project reports Rob Pooley rjp@macs.hw.ac.uk http://www.macs.hw.ac.uk/~rjp/DocPrep/DocPrep_files/frame.html

2. 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

3. 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

4. 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

5. 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 \\ rjp@cee.hw.ac.uk} \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. Title page

6. 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 \\ rjp@macs.hw.ac.uk} \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 abstract

7. 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.

8. 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 \\ rjp@macs.hw.ac.uk} \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}

9. 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}

10. 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\\ rjp@macs.hw.ac.uk} \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} Sections and sub-sections

11. 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} Citations

12. 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\textwidth} \epsffile{usecase2pc.ps} \end{figure} Illustrations

13. 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 Cross references

14. 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.

15. 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. Drawings

16. 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. 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 Equations

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

18. 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