KEVIN GODBY UBUNTU MANUAL: L A TEX FOR AUTHORS AND TRANSLATORS

Transcription

1 KEVIN GODBY UBUNTU MANUAL: L A TEX FOR AUTHORS AND TRANSLATORS

2

3 Contents Introduction e Basics Ge ing Started Organization of Files Style Guide Forma ing Text GUI Elements Graphics Other document elements Notes for Translators Document headings Forma ing commands Lists Author and editor notes Glossary-related commands Cross-referencing commands Other document commands Notes for Editors Obsolete commands Installing TEX Live

4

5 Introduction e Ubuntu Manual project has set out to produce a beginner s guide for Ubuntu, covering everything from installation to commonly used applications. e manual will be provided in pdf format in a variety of languages and will be freely available. To generate the pdfs, we use L A TEX. L A TEX is a typese ing system that has been around for over twenty years. Since L A TEX 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 the Ubuntu Manual mailing list at ubuntu-manual@lists.laun pad.net.

6

7 The Basics Ge ing Started As an author or editor, you will be modifying the Ubuntu Manual source files directly. e source files for L A TEX have a.tex extension. You can edit the source files using your favorite text editor su as emacs, vim, or GEdit. L A TEX code is similar to html in that most of the code is simply the text of the manual with a few forma ing commands sprinkled in. Translators should also familiarize themselves with the basics of L A TEX forma ing and read the special translator notes starting on page. Organization of Files Ea of the apters of the manual has its own subdirectory: Chapter Prologue Directory name prologue. Installation installation. Around Your Desktop around-desktop. Default Applications default-apps. Preferences and Hardware prefs-hardware. So ware and Pa aging software-packaging. System Maintenance maintenance. e Command Line command-line. Security security. Troubleshooting troubleshooting. Learning More About Linux learning-more Once you ve selected a apter that you d like to help write or edit, you will find a.tex file in that apter s directory. Some apters will have all of their text in that one file, while other apters have split ea section into its own file. If you see a bun of \input commands in the file, then you will have to look in the appropriate.tex file for the text of that section.

8

9 Style Guide Forma ing Text Punctuation otation marks otation marks in L A TEX are entered as `` and '', not as ". Single quotation marks are entered as ` and '. otation marks for other languages are entered as their Unicode aracters. 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 \dash command. is 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 su as UK English. Indicating a range If you wish to indicate a range (su as: pages or ), use an en dash. An en dash is entered in L A TEX as two hyphens: --. Do not put spaces before of a er the en dash when used to indicate a range. Special aracters ere are a few aracters that L A TEX considers special (used for its own syntax). To typeset these aracters, precede the aracter with a ba slash (\). e special aracters are: e above line was typed like this: $ % _ { } & # \$ \% \_ \{ \} \& \# Finally, to type a ba slash aracter, use the \textbackslash command. GUI Elements Menu items To give a sequence of menu items that should be selected, use the \menu and \then commands. For example: To open the Calculator application, cli Applications Accessories Calculator. is typeset by:

10 kevin godby To open the Calculator application, click \menu{applications\then Accessories\then Calculator}. Use the \menu command for single menu items as well: Pull down the File menu and then cli it. Other gui elements ere are commands for other gui elements as well: gui element Command Appearance Bu on button Cancel Tab \tab Advanced Drop-down list \dropdown Country Che box \checkbox Remember my password Window title \window Preferences Keyboard key(s) \keystroke Ctrl+Q Radio bu on \radiobutton Single cli to open items Text box \textfield Full name Application names e names of applications should be typeset with the \application command. is will add the application to the index automatically. For command-line based applications, use the \commandlineapp command instead. User input When quoting what a user should type, use the \userinput command. If you re just having the user press a key on the keyboard, use the \keystroke command instead. For example: Type \userinput{hello, world!} and press \keystroke{enter}. is typeset as: Type Hello, world! and press Enter. Cross-referencing In a manual of this size, it s o en helpful to point the reader to another apter or section for more information on a related topic. ere are few commands that can help you do that. To cross-reference another apter, use the \chaplink command. Similarly, to cross-reference a section of a apter, use the \seclink command. e \chaplink command will insert the text Chapter X : Chapter Title and link it to the beginning of that apter. e \seclink command will insert the name of the section and link it to that section. Graphics If a screenshot should be added at some point, make a note of it using the \screenshottodo command. Provide a description of what the screenshot

11 ubuntu manual: L A TEX for authors and translators should depict. is will add a warning notice in the pdf and will add that screenshot to the to do list. Figure. : Firefox web browser window M I S S I N G S C R E E N S H O T Firefox web browser window Other document elements Paragraphs To start a new paragraph in L A TEX, just add a blank line. You don t need to indent the paragraphs as L A TEX will take care of this for you. Margin notes e manual uses margin notes to provide definitions, tips, and pointers to more information. To add a margin note, use the \marginnote command: \marginnote{ Margin note text } Comments If you want to add a note to yourself (or others) in the.tex file, just type a percent sign (%) followed by your note. L A TEX ll ignore everything on the line a er the percent sign. This text will appear in the PDF. % But this text won't! Remember, if you want a percent sign to actually appear in the pdf, you ll need to precede it with a ba slash: Linux users are 50\% smarter than non-linux users.

12 kevin godby Terminal commands ere are also special commands for typese ing text that appears or is entered into a terminal. An example will illustrate the commands: 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} e above generates the following output: e fortune program works like this: $ fortune What we have to learn to do we learn by doing. -- Aristotle, Ethica Nicomachea II (c. 325 BC) e \prompt command will print a bash-style user prompt ($ ). e \rootprompt command will print a bash-style root prompt (# ). e \userinput command should contain any text that the user types in. While the terminal environment 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 \userinput and \code commands. 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 a ention to these rare circumstances, you can put a note in the \warning command. is will set the text off so it s more eye-cat ing. Similarly, there is a \advanced command for notes to advanced users. Lists ere 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.

13 ubuntu manual: L A TEX for authors and translators \begin{itemize} \item First list item \item Second list item \item Third list item \end{itemize} \begin{enumerate} \item First list item \item Second list item \item Third list item \end{enumerate} produces: First list item Second list item ird list item produces:. First list item. Second list item. ird list item

14

15 Notes for Translators L A TEX commands are preceded by a ba slash aracter (\). While the command names should not be translated, their arguments sometimes should be. In the following list of commands, the red text should be translated and the bla text should not be translated. Document headings \title{ book title } \author{ book authors } \part{ part heading } \chapter{ apter heading } \section{ section heading } \subsection{ subsection heading } \subsubsection{ subsubsection heading } \paragraph{ paragraph heading } \subparagraph{ subparagraph heading } Forma ing commands \marginnote{ margin note text } \textbf{ bold text } \textit{ italic text } \emph{ italic text } \smallcaps{ acronym } \application{ application name } \commandlineapp{ command-line application name } \menu{ menu name \then submenu name \then menu item } \button{ bu on name } \checkbox{ e box name } \tab{ tab name } \dropdown{ drop-down list name } \window{ window name } \textfield{ text box name } \keystroke{ Keyboard key names separated by + } \userinput{ stuff the user types } \code{ terminal output } \begin{ terminal } output from the terminal \end{ terminal } \warning{ warning text }

16 kevin godby \advanced{ advanced usage text } \screenshot{ filename }{ label }{ caption } e following forma ing commands should not be translated: \dash \url{ URL } \prompt \rootprompt Lists e only part of lists that need to be translated is the text of the list items themselves. \begin{ itemize } or \begin{ enumerate } \item list item text \item another list item \end{ itemize } or \begin{ enumerate } Author and editor notes Do not translate any of the following commands: \todo{ notes to appear in PDF margin } \screenshottodo{ description of screenshot } \begin{ comment } notes to authors/editors \end{ command } Glossary-related commands \newglossaryentry{ keyword }{name={ term },description={ definition }} \gls{ keyword } \glspl{ keyword } \Gls{ keyword } \Glspl{ keyword } Cross-referencing commands Do not translate any of these commands: \label{ label } \ref{ label } \pageref{ label } \nameref{ label } \chaplink{ label } \seclink{ label }

17 ubuntu manual: L A TEX for authors and translators Other document commands Do not translate any of the following: \frontcover \mainmatter \appendix \backmatter \providecommand{ command name }{ command definition } \documentclass[ options ]{ document type } \include{ file } \begin{ environment } \end{ environment } \printglossaries \printindex \LoadLicenseFile

18

19 Notes for Editors Obsolete commands ere 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. \menuitem is command should be replaced by the \menu command. \nav is command should be replaced by the \menu command. --- is em dash command should be replaced by the \dash command.

20

21 Installing TEX Live We re using a number of features that require the latest version of TEX Live ( ). Unfortunately, the version of TEX Live that comes with Ubuntu. is TEX Live. To install TEX Live, follow these steps:. Uninstall all the Ubuntu TeX Live pa ages: sudo apt-get remove texlive-*. Download the TeX Live install script: texlive/tlnet/install-tl-unx.tar.gz. Unpa the tarball: tar -zxvf install-tl-unx.tar.gz. Change to the newly-unpa ed directory: cd install-tl-*. Run the script: sudo./install-tl. 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.. To compile a translation, run: make ubuntu-manual- lang.pdf where lang is the language code (see the po/ directory for a list of supported languages). 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 me. I m usually in irc as godbyk and can, of course, be contacted via .