~ubuntu-manual/ubuntu-manual/lucid-2e

\documentclass{ubuntu-manual}

\hypersetup{colorlinks}

\usepackage{booktabs}
\usepackage{hyphenat}

\title{Ubuntu Manual Style Guide}
\author{Kevin Godby}


\newcommand{\email}[1]{\href{mailto:#1}{#1}}

% Macros for documenting and indexing LaTeX commands
\newcommand{\hangleft}[1]{\makebox[0pt][r]{#1}}
\newcommand{\bs}{\symbol{'134}}% a backslash in tt type in OT1/T1
\newcommand{\parg}[1]{$\langle$\textrm{\textit{#1}}$\rangle$}
\newcommand{\oarg}[1]{\texttt{[\parg{#1}]}}
\newcommand{\marg}[1]{\texttt{\{\parg{#1}\}}}
\newcommand{\cmd}[1]{\texttt{\textbackslash#1}}
\newcommand{\envnoindex}[2]{\texttt{\textbackslash begin\{#1\} #2 \textbackslash end\{#1\}}}
\newcommand{\env}[2]{\texttt{\textbackslash begin\{#1\} #2 \textbackslash end\{#1\}}\index{#1 environment@\texttt{#1} environment}\index{environments!#1@\texttt{#1}}}
\newcommand{\indexenv}[1]{\index{#1 environment@\texttt{#1} environment}\index{environments!#1@\texttt{#1}}}
\newcommand{\csnoindex}[1]{\texttt{\textup{\textbackslash#1}}}
\newcommand{\cs}[1]{\texttt{\textup{\textbackslash#1}}\index{#1 command@\protect\hangleft{\texttt{\bs}}\texttt{#1}}}
\newcommand{\indexcs}[1]{\index{#1 command@\protect\hangleft{\texttt{\bs}}\texttt{#1}}}

\newcommand{\highlight}[1]{\textcolor{important}{#1}}
\newcommand{\tr}[1]{\textcolor{important}{#1}}
\newcommand{\ntr}[1]{#1}
\newcommand{\tmarg}[1]{\marg{\tr{#1}}}
\newcommand{\toarg}[1]{\oarg{\tr{#1}}}
\newcommand{\tparg}[1]{\parg{\tr{#1}}}


\newenvironment{example}{%
  \begin{quote}%
    \setlength{\parindent}{0pt}%
    \setlength{\parskip}{\baselineskip}%
    \raggedright\sloppy\language\langwohyphens
}{%
  \end{quote}%
}

\begin{document}

\maketitle

\tableofcontents

\chapter{Introduction}

The \href{http://ubuntu-manual.org/}{Ubuntu Manual project} has set out to produce a beginner's guide for Ubuntu, covering everything from installation to commonly used applications.  The manual will be provided in \acronym{PDF} format in a variety of languages and will be freely available.  To generate the \acronym{PDF}s, we use \LaTeX.

\LaTeX{} is a typesetting system that has been around for over twenty years.  Since \LaTeX{} is a large (and sometimes complex) system this guide will only cover what you need to know to write, edit, and translate the contents of the Ubuntu Manual.

If you have questions or run into any problems that this guide doesn't cover, feel free to email the Ubuntu Manual mailing list at \email{ubuntu-manual@lists.launchpad.net}.

\chapter{The Basics}

\section{Getting Started}\label{sec:getting-started}

% Add pointers to getting the source code and using Rosetta.

As an author or editor, you will be modifying the Ubuntu Manual source files directly.  The source files for \LaTeX{} have a \texttt{.tex} extension.  You can edit the source files using your favorite text editor such as emacs, vim, or gedit.  \LaTeX{} code is similar to \acronym{HTML} in that most of the ``code'' is simply the text of the manual with a few formatting commands sprinkled in.

Translators should also familiarize themselves with the basics of \LaTeX{} formatting and read the special translator notes in \href{ch:notes-for-translators}{chapter~}\ref{ch:notes-for-translators}.

\section{Organization of Files}

Each of the chapters of the manual has its own subdirectory:

\begin{center}
  \begin{tabular}{ll}
    \toprule
    Chapter & Directory name \\
    \midrule
    Prologue & \texttt{prologue} \\
    1. Installation & \texttt{installation} \\
    2. The Ubuntu Desktop & \texttt{around-desktop} \\
    3. Working with Ubuntu & \texttt{default-apps} \\
    4. Hardware & \texttt{prefs-hardware} \\
    5. Software Management & \texttt{software-packaging} \\
    6. The Command Line & \texttt{command-line} \\
    7. Security & \texttt{security} \\
    8. Troubleshooting & \texttt{troubleshooting} \\
    9. Learning More & \texttt{learning-more} \\
    \bottomrule
  \end{tabular}
\end{center}

Once you've selected a chapter that you'd like to help write or edit, you will find a \texttt{.tex} file in that chapter's directory.  Some chapters will have all of their text in that one file, while other chapters have split each section into its own file.  If you see a bunch of \cs{input} or \cs{include} commands in the file, then you will have to look in the appropriate \texttt{.tex} file for the text of that section.




\chapter{Typesetting with \protect\LaTeX{}}\label{ch:typesetting-with-latex}

%\section{Writing Style}\label{sec:writing-style}% Not LaTeX-related


\section{Formatting Text}\label{sec:formatting-text}
\subsection{Punctuation}\label{sec:punctuation}

\paragraph{Quotation marks} Quotation marks in \LaTeX{} are entered as \verb|``| and \verb|''|, \emph{not} as \verb|"|.
Single quotation marks are entered as \verb|`| and \verb|'|.  Quotation marks for other languages are entered as their Unicode characters.% TODO This may change if we use csquotes.
\index{quotation marks}

\paragraph{Indicating sudden breaks} To indicate a sudden break in thought---like this---use an em dash.  To enter an em dash in the manual, use the \cs{dash} command.  This command will print an em dash without spaces---like this---for US English, but can be set to print an en dash with spaces\,--\,like this\,--\,for other languages such as UK English.
\index{em dash (---)}\index{en dash (--)}

\paragraph{Indicating a range}  If you wish to indicate a range (such as: pages 37--40 or 2005--2007), use an en dash.  An en dash is entered in \LaTeX{} as two hyphens: \verb|--|.  Do not put spaces before of after the en dash when used to indicate a range.
\index{en dash (--)}

\paragraph{Special characters}  There are a few characters that \LaTeX{} considers special (used for its own syntax).  To typeset these characters, precede the character with a backslash (\texttt{\textbackslash}).  The special characters are:
\index{dollar sign (\$)}\index{\$}
\index{percent sign (\%)}\index{\%}
\index{underscore (\_)}\index{underline (\_)}\index{\_}
\index{braces (\{ \textit{and} \})}\index{\{}\index{\}}
\index{ampersand (\&)}\index{\&}
\index{pound sign (\#)}\index{number sign}\index{\#}

\begin{example}
  \centering \$ \qquad \% \qquad \_ \qquad \{ \qquad \} \qquad \& \qquad \#
\end{example}
The above line was typed like this:
\begin{example}
  \centering \ttfamily \cs{\$} \qquad \cs{\%} \qquad \cs{\_} \qquad \cs{\{} \qquad \cs{\}} \qquad \cs{\&} \qquad \cs{\#}
\end{example}
Finally, to type a backslash character, use the \cs{textbackslash} command; to type a tilde (\texttt{\textasciitilde}), use the \cs{textasciitilde} command.
\index{backslash (\textbackslash)}\index{\textbackslash}
\index{tilde (\textasciitilde)}\index{\textasciitilde}

\section{GUI Elements}

\paragraph{Menu items}  To give a sequence of menu items that should be selected, use the \cs{menu} and \cs{then} commands.  For example:\index{menu items}
\begin{example}
  To open the Calculator application, click \menu{Applications\then Accessories\then Calculator}.
\end{example}
is typeset by:
\begin{example}
  \ttfamily To open the Calculator application, click \string\menu\string{Applications\string\then\space Accessories\string\then\space Calculator\string}.
\end{example}

Use the \cs{menu} command for single menu items as well:
\begin{example}
  Pull down the \menu{File} menu and then click \menu{Quit}.
\end{example}

\paragraph{Other \smallcaps{GUI} elements}  There are commands for other \smallcaps{GUI} elements as well:

\medskip
\begin{center}
  \begin{tabular}{lll}
    \toprule
    \smallcaps{GUI} element & Command & Appearance \\
    \midrule
    Button & \cs{button} & \button{Cancel} \\
    Tab & \cs{tab} & \tab{Advanced} \\
    Drop-down list & \cs{dropdown} & \dropdown{Country} \\
    Checkbox & \cs{checkbox} & \checkbox{Remember my password} \\
    Window title & \cs{window} & \checkbox{Preferences} \\
    Keyboard key(s) & \cs{keystroke} & \keystroke{Ctrl+Q} \\
    Radio button & \cs{radiobutton} & \radiobutton{Single click to open items} \\
    Text box & \cs{textfield} & \textfield{Full name} \\
    \bottomrule
  \end{tabular}
\end{center}

\paragraph{Application names}  The names of applications should be typeset with the \cs{application} command.  This will add the application to the index automatically.  For command-line--based applications, use the \cs{commandlineapp} command instead.\index{application names}

\paragraph{User input} When quoting what a user should type, use the \cs{userinput} command.  If you're just having the user press a key on the keyboard, use the \cs{keystroke} command instead.  For example:\index{user input}
\begin{quotation}
  \ttfamily Type \string\userinput\string{Hello, world!\string} and press \string\keystroke\string{Enter\string}.
\end{quotation}
is typeset as:
\begin{quotation}
  Type \userinput{Hello, world!} and press \keystroke{Enter}.
\end{quotation}

\paragraph{Cross-referencing}  In a manual of this size, it's often helpful to point the reader to another chapter or section for more information on a related topic.  There are few commands that can help you do that.  To cross-reference another chapter, use the \cs{chaplink} command.  Similarly, to cross-reference a section of a chapter, use the \cs{seclink} command.  The \cs{chaplink} command will insert the text ``Chapter \parg{X}: \parg{Chapter Title}'' and link it to the beginning of that chapter.  The \cs{seclink} command will insert the name of the section and link it to that section.\index{cross-referencing}% TODO provide examples

% TODO provide actual command references


\section{Graphics}\label{sec:graphics}

If a screenshot should be added at some point, make a note of it using the \cs{screenshotTODO} command.  Provide a description of what the screenshot should depict.  This will add a warning notice in the \smallcaps{PDF} and will add that screenshot to the to do list.\index{graphics}\index{screenshots}

\screenshotTODO{Firefox web browser window}

% TODO Write about how to insert a screenshot into the document.

\section{Other document elements}

\paragraph{Paragraphs} To start a new paragraph in \LaTeX{}, just add a blank line.  You don't need to indent the paragraphs as \LaTeX{} will take care of this for you.\index{paragraphs}

\paragraph{Margin notes} The manual uses margin notes to provide definitions, tips, and pointers to more information. To add a margin note, use the \cmd{marginnote} command:\index{margin notes}
\begin{example}
  \ttfamily \cs{marginnote}\marg{Margin note text}
\end{example}

\paragraph{Comments}  If you want to add a note to yourself (or others) in the \texttt{.tex} file, just type a percent sign (\%) followed by your note.  \LaTeX{}
ll ignore everything on the line after the percent sign.\index{comments}\index{percent sign (\%)}
\begin{example}
  \ttfamily This text will appear in the PDF. \% But this text won't!
\end{example}

Remember, if you want a percent sign to actually appear in the \smallcaps{PDF}, you'll need to precede it with a backslash:
\begin{example}
  \ttfamily Linux users are 50\cs{\%} smarter than non-Linux users.
\end{example}

\paragraph{Terminal commands} There are also special commands for typesetting text that appears or is entered into a terminal. An example will illustrate the commands:
\index{terminal input/output}\indexenv{terminal}
\begin{example}
  \parskip0pt\obeylines
  \ttfamily The \cs{commandlineapp}\{fortune\} program works like this:
  \csnoindex{begin}\{terminal\}
  \cs{prompt} \cs{userinput}\{fortune\}
  What we have to learn to do we learn by doing.
  \ \ \ -- Aristotle, Ethica Nicomachea II (c. 325 BC)
  \csnoindex{end}\{terminal\}
\end{example}
The above generates the following output:
\begin{example}
  The \commandlineapp{fortune} program works like this:
  \begin{terminal}
    \prompt \userinput{fortune}
    What we have to learn to do we learn by doing.
    \ \ \ -- Aristotle, Ethica Nicomachea II (c. 325 BC)
  \end{terminal}
\end{example}

The \cs{prompt} command will print a \smallcaps{BASH}-style user prompt (\prompt).  The \cs{rootprompt} command will print a \smallcaps{BASH}-style root prompt (\rootprompt).  The \cs{userinput} command should contain any text that the user types in. 

While the \texttt{terminal} environment\indexenv{terminal} is handy for multiple lines of terminal input/output, if you want to put terminal text inline with your paragraph text, you can use the \cs{userinput} and \cs{code} commands.

\paragraph{Warnings and notices for advanced instructions}  While the instructions in this manual should be as safe as possible, we sometimes mention commands or programs that can potentially do damage if not used correctly.  To draw attention to these rare circumstances, you can put a note in the \cs{warning} command.  This will set the text off so it's more eye-catching.

Similarly, there is a \cs{advanced} command for notes to advanced users.

\paragraph{Lists}  There are two types of lists that we use in the manual: numbered lists and bulleted lists.  Both lists work the same way, they just have different names.
\index{lists}\indexenv{enumerate}\index{itemize}

  \begin{minipage}{0.4\textwidth}
    \parskip0.5\baselineskip
    \parindent0pt
    \begin{flushleft}
      \ttfamily
      \string\begin\{itemize\}\\
      \ \ \string\item\ First list item\\
      \ \ \string\item\ Second list item\\
      \ \ \string\item\ Third list item\\
      \string\end\{itemize\}
    \end{flushleft}
    produces:\\
    \begin{flushleft}
      \rmfamily
      \begin{itemize}
        \item First list item
        \item Second list item
        \item Third list item
      \end{itemize}
    \end{flushleft}
  \end{minipage}
  \hfill
  \begin{minipage}{0.4\textwidth}
    \parskip0.5\baselineskip
    \parindent0pt
    \begin{flushleft}
      \ttfamily
      \string\begin\{enumerate\}\\
      \ \ \string\item\ First list item\\
      \ \ \string\item\ Second list item\\
      \ \ \string\item\ Third list item\\
      \string\end\{enumerate\}
    \end{flushleft}
    produces:
    \begin{flushleft}
      \rmfamily
      \begin{enumerate}
        \item First list item
        \item Second list item
        \item Third list item
      \end{enumerate}
    \end{flushleft}
  \end{minipage}


\chapter{Notes for Translators}\label{ch:notes-for-translators}

\LaTeX{} commands are preceded by a backslash character (\texttt{\textbackslash}). While the command names should not be translated, their arguments sometimes should be.

In the following list of commands, the \tr{red} text should be translated and the black text should not be translated.

\section{Document headings}
\begin{itemize}\ttfamily
  \item \cs{title}\tmarg{book title}
  \item \cs{author}\tmarg{book authors}
  \item \cs{part}\tmarg{part heading}
  \item \cs{chapter}\tmarg{chapter heading}
  \item \cs{section}\tmarg{section heading}
  \item \cs{subsection}\tmarg{subsection heading}
  \item \cs{subsubsection}\tmarg{subsubsection heading}
  \item \cs{paragraph}\tmarg{paragraph heading}
  \item \cs{subparagraph}\tmarg{subparagraph heading}
\end{itemize}

\section{Formatting commands}
\begin{itemize}\ttfamily
  \item \cs{marginnote}\tmarg{margin note text}
  \item \cs{textbf}\tmarg{bold text}
  \item \cs{textit}\tmarg{italic text}
  \item \cs{emph}\tmarg{italic text}
  \item \cs{smallcaps}\tmarg{acronym}
  \item \cs{application}\tmarg{application name}
  \item \cs{commandlineapp}\tmarg{command-line application name}
  \item \cs{menu}\{\tparg{menu name} \cs{then} \tparg{submenu name} \cs{then} \tparg{menu item}\}
  \item \cs{button}\tmarg{button name}
  \item \cs{checkbox}\tmarg{checkbox name}
  \item \cs{tab}\tmarg{tab name}
  \item \cs{dropdown}\tmarg{drop-down list name}
  \item \cs{window}\tmarg{window name}
  \item \cs{textfield}\tmarg{text box name}
  \item \cs{keystroke}\tmarg{Keyboard key names separated by \texttt{+}}
  \item \cs{userinput}\tmarg{stuff the user types}
  \item \cs{code}\tmarg{terminal output}
  \item \env{terminal}{\tparg{output from the terminal}}
  \item \cs{warning}\tmarg{warning text}
  \item \cs{advanced}\tmarg{advanced usage text}
  \item \cs{screenshot}\marg{filename}\marg{label}\tmarg{caption}
\end{itemize}

\noindent The following formatting commands should \emph{not} be translated:
\begin{itemize}\ttfamily
  \item \cs{dash}
  \item \cs{url}\marg{\acronym{URL}}
  \item \cs{prompt}
  \item \cs{rootprompt}
\end{itemize}

\section{Lists}
The only part of lists that need to be translated is the text of the list items themselves.

\begingroup\ttfamily\parindent=0pt\parskip=0pt\noindent
\csnoindex{begin}\{itemize\}\quad\textit{or}\quad\csnoindex{begin}\{enumerate\}\par
\space\space\cs{item} \tparg{list item text}\par
\space\space\cs{item} \tparg{another list item}\par
\csnoindex{end}\{itemize\}\quad\textit{or}\quad\csnoindex{end}\{enumerate\}\par
\endgroup

\section{Author and editor notes}
Do not translate any of the following commands:
\begin{itemize}\ttfamily
  \item \cs{todo}\marg{notes to appear in \acronym{PDF} margin}
  \item \cs{screenshotTODO}\marg{description of screenshot}
  \item \env{comment}{\parg{notes to authors/editors}}
\end{itemize}


\section{Glossary-related commands}

\begin{itemize}\ttfamily
  \item \cs{newglossaryentry}\marg{keyword}\{name=\tmarg{term}, description=\tmarg{definition}, plural=\tmarg{plural form}\}
  \item \cs{gls}\marg{keyword}
  \item \cs{glspl}\marg{keyword}
  \item \cs{Gls}\marg{keyword}
  \item \cs{Glspl}\marg{keyword}
\end{itemize}

\section{Cross-referencing commands}
Do not translate any of these commands:
\begin{itemize}\ttfamily
  \item \cs{label}\marg{label}
  \item \cs{ref}\marg{label}
  \item \cs{pageref}\marg{label}
  \item \cs{nameref}\marg{label}
  \item \cs{chaplink}\marg{label}
  \item \cs{seclink}\marg{label}
\end{itemize}

\section{Other document commands}
Do not translate any of the following:
\begin{itemize}\ttfamily
  \item \cs{frontcover}
  \item \cs{mainmatter}
  \item \cs{appendix}
  \item \cs{backmatter}
  \item \cs{providecommand}\marg{command name}\marg{command definition}
  \item \cs{documentclass}\oarg{options}\marg{document type}
  \item \cs{include}\marg{file}
  \item \csnoindex{begin}\marg{environment}
  \item \csnoindex{end}\marg{environment}
  \item \cs{printglossaries}
  \item \cs{printindex}
  \item \cs{LoadLicenseFile}
\end{itemize}


\chapter{Notes for Editors}

\section{Obsolete commands}

There are a few commands that were used in the beginning of the project that have since been replaced.  If you encounter any of these obsolete commands, please replace them with the updated command.

\begin{description}
  \item[\cs{menuitem}]  This command should be replaced by the \cs{menu} command.
  \item[\cs{nav}]  This command should be replaced by the \cs{menu} command.
  \item[\texttt{-{}-{}-}]  This em dash command should be replaced by the \cs{dash} command.
\end{description}


\chapter{Installing \protect\TeX{} Live 2009}
\index{\protect\TeX{} Live!installing}

We're using a number of features that require the latest version of \TeX{} Live (2009).  Unfortunately, the version of \TeX{} Live that comes with Ubuntu 9.10 is \TeX{} Live 2007.  To install \TeX{} Live 2009, follow these steps:

\begin{enumerate}
  \item Uninstall all the Ubuntu TeX Live packages:  \texttt{sudo apt-get remove texlive-*}
  \item Download the TeX Live 2009 install script:  \url{http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz}
  \item Unpack the tarball: \texttt{tar -zxvf install-tl-unx.tar.gz}
  \item Change to the newly-unpacked directory: \texttt{cd install-tl-*}
  \item Run the script: \texttt{sudo ./install-tl}
  \item Select where you'd like to install everything, and any other options you prefer.  I highly recommend enabling the ``create symlinks to standard directories'' option.
  \item To compile a translation, run: \texttt{make ubuntu-manual-\parg{lang}.pdf}   where \parg{lang} is the language code (see the \texttt{po/} directory for a list of supported languages).
\end{enumerate}

Note that not all languages are supported yet (especially those requiring non-Latin scripts).

If you have any questions or run into any problems, feel free to contact the Ubuntu Manual Team for assistance.


\chapter{Word List}\label{ch:word-list}

This chapter contains a list of words with their proper spelling and capitlization.

\begin{multicols}{3}
\obeylines%
Bluetooth
dial-up
Ethernet
gedit
\acronym{GNOME}
\acronym{GNU}/Linux
\acronym{KDE}
Red Hat
session menu
shut down
Wi-Fi
\end{multicols}


\printglossaries

\printindex

\end{document}