<> ||<>|| == Ubuntu Manual Technical Help == === Getting the code with Ground Control === '''At the moment Ground Control isn't working due to an update to Launchpad. You will have to use the command line bzr tool to get our branch. See below.''' We recommend that you use Ground Control to manage the branch. We've got it set up with special buttons to compile the PDF and clean the files so you don't even have to use the command line at all. It's very easy. View this video here that explains how to install and use Ground Control: http://www.youtube.com/watch?v=MeNXqfofbWk === How to use LaTeX === There are a few Ubuntu and LaTeX packages required to compile the Ubuntu Manual PDF. To install the prerequisites, first check out the ubuntu-manual repository. Follow instructions on [[ubuntu-manual/Prerequisites]] to install LaTeX. Next, `cd ubuntu-manual/pkgs` and then run `./install-pkgs.sh`. This script will run `apt-get` to install the appropriate Ubuntu packages and also install some LaTeX packages that aren't in Ubuntu's repository. The script may ask for your password so it can run `sudo apt-get install`. If you have problems running this script, email the `install-pkgs.log` file to the Ubuntu Manual mailing list. A LaTeX file is essentially a plain text file with a few commands added in. The way our latex files are set up, there is a master latex file in the root directory of the ubuntu-manual called `main.tex`. In that file a whole bunch of things are defined and just generally set up for you. Don't touch any of that stuff as it might break something. Later on in the document it includes 10 files, one for each chapter. These are located at `chapter1/chapter1.tex`, `chapter2/chapter2.tex`, etc. Those are the files that you should be editing. For example, if you want to work on the '''Display''' section of the '''Hardware''' chapter, you would edit the '''displays.tex''' file located in the '''prefs-hardware''' folder of the main directory e.g. ''~/ubuntu-manual/prefs-hardware/displays.tex'' To build the PDF, run {{{make}}} in the top level directory of the source. This will build a `main.pdf` file. To build the PDF and open it in a PDF viewer, run {{{make show}}} This will generate a lot of other files; these are included in the .bzrignore file and are best to leave in place to avoid having to build from scratch every time. They are analogous to the .o files produced when compiling C. If you do want to get rid of all generated files, run: {{{make clean}}} It's recommended to run "make clean" before syncing with the branch, either pushing or pulling. ==== Basics of Latex ==== Latex is pretty much a programming in itself and can be extended to do a lot of things, but to write basic documentation, you only need to know a few things. To edit Latex files you only need a text editor, but there are graphical editors such as {{{lyx}}}. ===== Latex Structure ===== Latex, for our purposes uses sections to define the structure. There are three main section types, sections, subsections, and subsubsections. All of them are created by typing a line such as {{{ \section{Title of Section} }}} That can be {{{ \section }}}, {{{ \subsection }}} or {{{ \subsubsection }}} You can go ahead and play around with that to see what they do. \chapter is used only for Chapters, and \section should only be used to start main parts of chapters, \subsection and \subsubsection can (and should) be used to separate up your writing. The best part of Latex is that it will create the Table of Contents with the various section and subsection headings for you! ===== Fonts and Text ===== If there is any text you don't want to show up in the actual document, but want for commenting purposes preface it with the {{{%}}} character. For example {{{%This is a comment}}} The font is automatically set to helvetica 10 pt font, but it is possible that you would want to change the font, add italics or bold. Below is a table of things you can do. The last column has the commands in monospace so it's easier to see what they are. || ''Italic'' || \textit{words in italics} || {{{\textit}}} || || '''Bold''' || \textbf{words in bold} || {{{\textbf}}} || || Slanted || \textsl{words in slanted} || {{{\textsl}}} || || Small Capitals || \textsc{words in small capitals} || {{{\textsc}}} || ===== Lists ===== There are two main forms of lists, numbered and bulleted. To create a bulleted list type: {{{ \begin{itemize} \item Text of item number 1 \item Text of item number 2 \item Text of item... etc \end{itemize} }}} For a numbered list type: {{{ \begin{enumerate} \item Text of item number 1 \item Text of item number 2 \item Text of item... etc \end{enumerate} }}} Of course you can have as many {{{\item}}}s as you would like as long as they are in between the {{{\begin}}} and {{{\end}}}. Last, you can have multiple layers of lists so if you wanted for example this: * Item 1 * Item 2 You would type (the indents are just to make it easier to read): {{{ \begin{itemize} \item Item 1 \begin{itemize} \item Item 2 \end{itemize} \end{itemize} }}} I will be adding ability to include screenshots soon to the latex template, if you have any questions find '''jmburgess''' on IRC or email me at joemburgess@gmail.com See [[https://help.ubuntu.com/community/LaTeX]] or [[http://www.andy-roberts.net/misc/latex/]] for more info. There's actually an awesome LaTeX documentation page here: http://en.wikibooks.org/wiki/LaTeX/ ~-Section on LaTeX written by [[https://launchpad.net/~joemburgess|Joe Burgess.]]-~ === Using bzr if you aren't using Ground Control === '''You don't need to do this if you're using Ground Control mentioned above.''' bzr, or Bazaar is the system we use to push and pull branches. It is pretty intelligent and can see what changes have been made. Here's how to use it. ==== Requirements ==== First, you'll need to make sure you have a [[https://launchpad.net|Launchpad]] account, are a member of the [[https://launchpad.net/ubuntu-manual|Project]] and the [[https://launchpad.net/~ubuntu-manual|Team]], and also have registered an [[https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair|SSH key]] for your computer. ==== First time you use bzr ==== Open up a new Terminal. Install bzr: {{{sudo apt-get install bzr}}} Tell bzr your name and email address: {{{bzr whoami "Joe Bloggs "}}} Get the bzr branch: {{{bzr branch lp:ubuntu-manual }}} Add the files to bzr: {{{bzr add}}} That should add all files in your working directory to bzr. Now you need to see the differences (there will be none if you have got the branch for the first time): {{{bzr diff}}} Then commit it: {{{bzr commit -m "What you've changed"}}} So for example: {{{bzr commit -m "Fixed some spelling mistakes in chapter 6"}}} After it has said "committed revision X" you should be able to push it through to main: {{{bzr push lp:ubuntu-manual}}} Now go to [[https://code.launchpad.net/~ubuntu-manual/ubuntu-manual/main|Launchpad]] and check that it has indeed been pushed up to the next revision. ==== Updating your local branch ==== Run the following command to "pull" the latest branch from Launchpad and merge it with yours: {{{bzr pull lp:ubuntu-manual}}} Remember all bzr commands must be in the root directory of ubuntu-manual, where your branch is registered. If you have created a new folder or new files (ie, not edited an existing one) then you will need to run {{{bzr add}}} again to add these new files/folders to the bzr branch, then you'll need to run bzr diff to check they've been added, and then the commit line shown above. Then finally push it through, once you've made sure no one else has pushed through something in the few minutes since you last checked! ==== How to make changes the RIGHT way ==== * Firstly, make sure you have the latest revision by going [[https://code.launchpad.net/~ubuntu-manual/ubuntu-manual/main|here]] * Run bzr diff when you've got the latest revision, to see what changes someone else has made * Make your own changes * Run make clean to get rid of all the unnecessary build packages * Run bzr diff again to confirm them * Commit them with a good description. Not word-for-word changes, but specific enough for someone to easily find again * Push them through to main, and then check the Launchpad page to see it's gone up to the next revision. === Style Guide === You can read the style guide for the Ubuntu Manual [[ubuntu-manual/StyleGuide|here.]] === Translations === '''Translation support is now integrated with our project!''' If you're interested in translating, head to the [[https://translations.launchpad.net/ubuntu-manual|Project translation page]] and start working!