Ceci est une ancienne révision du document !
Over the last couple of issues, I asked for input from the readers on commands that they find useful, and a short description of what they do. Now, I have nearly three A4 pages of commands in the Google Doc I created for this. To anyone who contributed – thank you! There were a surprising number of commands (or variations) that I hadn't ever come across before. If anyone would like recognition on the title page of the PDF, you can either email me at lswest34+cli-cookbook@gmail.com, or open an issue on the GitHub (or just fork the repository!). For the actual article this month, I will briefly explain how to set up and use LaTeX on Ubuntu, for anyone who wishes to contribute to the PDF (using LaTeX), but isn't yet comfortable with LaTeX.
First off, the Cookbook is now located on GitHub, here: https://github.com/lswest/cli-cookbook
It's a public repository, so anyone who wants to contribute needs only to fork the repository, make those changes, and then send me a pull request. I will reserve the right to veto the inclusion of any commands if they seem to me to be either unnecessary duplicates of existing commands, or else are purely malicious (by this I mean commands that will result in loss of data, without any feasible security usage). For those of you not comfortable with git (or LaTeX), and without the inclination to learn, you can suggest changes and updates using the issue tracker on the repository.
Installing LaTeX
The basic LaTeX installation is supplied through texlive, but a full installation is supplied through texlive-full. Either can be installed with apt-get, as seen below:
sudo apt-get install texlive
or
sudo apt-get install texlive-full
Installing the IDE
I recommend using an IDE when working with LaTeX for the first time, though you can, of course, compile .tex documents using the command-line. However, the IDE makes figuring out shortcuts and commands much easier.
My preferred IDE is Texmaker, which can be found in the official repository. You can install it with
sudo apt-get install texmaker
If your version of Ubuntu (or your preferred distribution) doesn't offer it officially, you can find it here: http://www.xm1math.net/texmaker/download.html#linux. As with all things in Linux, there are more choices than just Texmaker, but it will be what I base my explanations on.
Install extra packages I used a few extra packages to fancy up the Cookbook (with links and code formatting). The extra packages are: fancyvrb and hyperref. Everything else should be included in a typical LaTeX installation. These packages are contained in texlive-latex-recommended and texlive-latex-base. If you installed just texlive instead of the full installation, you will most likely need to install these separately.
Fork the GitHub repository
For this you need a github account, and have git installed. On my repository, you should see a button that reads “fork”. By clicking this you create a repository on your account that's a copy of mine. The second step is to clone the fork (the repository linked to your account). To do so, you can type the following into a terminal:
git clone https://github.com/username/cli-cookbook.git
Replace username with your username. Alternatively, you can simply copy the HTTPS clone URL off the GitHub page (of your forked repository).
This will create a folder called cli-cookbook and fill it with the files you need. Once that's done, open up the .tex file in Texmaker.
Editing the file
Usually when creating a file, you'll need to create the preamble (\usepackage, \documentclass, \begin{document}, etc.). However, since you're working off my file, that's all been taken care of.
If you want to add a new section (say, for example, you want to add a section for photo editing commands), you would type the following:
\section{Name}
The Name is then the header you'd like it to have (i.e. Photo Editing). If you want to split it up into sub sections, the command is: \subsection{}, and \subsubsection{} creates, surprisingly enough, a subsection to a subsection. If you plan to refer back to this section later, you'll need to assign it a label. At the end, it could look like this:
[…]
\section{Photo Editing}
\subsection{Using Photon to create albums}
\label{photon}
\subsection{Organizing Albums}
As seen in \hyperref[photon]{\ref*{photon}}
[…]
This will create a section called Photo Editing, and two subsections called Using Photon to create albums, and Organizing Albums. The \hyperref statement will replace that section of code with the section number of the Photon subsection (i.e. 13.1). Clicking on the link will take you to the page where that section appears.
à relire
Adding code I made this step slightly more complicated than it needs to be, in order to get the best result. You need to encompass your code like so: \begin{Verbatim}[commandchars=\\\{\}] Code goes here \end{Verbatim} The Verbatim environment won't wrap text, so you'll need to manually keep an eye on the length of the code once the PDF is compiled. If you have multiple commands after each other, I place a blank line between each step. If you stick to my formatting system, you'll also want to mark the unchanging parts of a command with a red color. Any user input I leave black. So it would look like this: \begin{Verbatim}[commandchars=\\\{\}] \codeHighlight{unchanging code} user input \codeHighlight{more unchanging code} \end{Verbatim} As you can imagine, this will result in unchanging code user input more unchanging code. Logically, you'll want to swap out the text for what you want to say. Ajout de code J'ai complexifié cette étape plus qu'elle ne doit être, afin d'obtenir le meilleur résultat. Vous devez inclure votre code comme suit : \begin{Verbatim}[commandchars=\\\{\}] Mettre ici le code \end{Verbatim} L'environnement Verbatim ne va pas faire de retour à la ligne automatique, ainsi vous devrez vérifier à la main la longueur du code, une fois que le fichier PDF est compilé. Lorsqu'on a plusieurs commandes après l'autre, je place une ligne vide entre chaque étape. Si vous suivez bien mon système de mise en forme, vous devrez marquer les éléments inchangés d'une commande avec une couleur rouge. Je laisse en noir toutes les entrée des utilisateurs. Donc, çà ressemblerait à ceci : \begin{Verbatim}[commandchars=\\\{\}] \codeHighlight{code inchangé} entrée utilisateur \codeHighlight{encore du code inchangé} \end{Verbatim} Comme vous pouvez l'imaginer, cela se traduira par code inchangé entrée utilisateur encore du code inchangé. Logiquement, vous aurez envie de remplacer ce texte par ce que vous voulez dire. Compiling the PDF Once you've made your changes and are ready to compile the PDF, press the blue arrow next to “Quick Build” in the top bar of Texmaker. If you want to do it by hand, you can run this command: pdflatex cli-cookbook.tex If any errors crop up, you'll need to read the error information to find the correct section of the file and see what could be wrong. I find the most common issue is a lack/overabundance of braces. Compilation du PDF Une fois que vous avez fait vos modifications et êtes prêt à compiler le fichier PDF, appuyez sur la flèche bleue à côté de “Quick Build” [Construction rapide] dans la barre supérieure de Texmaker. Si vous voulez le faire à la main, vous pouvez exécuter cette commande : pdflatex cli-cookbook.tex Si des erreurs surviennent, vous devrez lire les messages d'erreur pour trouver la section appropriée du fichier et voir ce qui pourrait être erroné. J'ai trouvé que le problème le plus courant est un manque/surabondance d'accolades Return the changes to original repository First, open a terminal and change directory to your local copy of the repository. cd ~/cli-cookbook/ Now, you need to add the newly added/changed files: git add -A Then you need to commit the changes git commit -m “Update message” -a Replace the “Update message” section with a brief summary of what you added. Keep quotes around the message! git push origin master This pushes the changes back to your copy of my repository. If you rename the branches, you'll need to know what you've changed the origin and master names to. By default, this command should work. Renvoyer les modifications dans le référentiel original Tout d'abord, ouvrez un terminal et allez dans le répertoire de votre copie locale du référentiel. cd ~/cli-cookbook/ Maintenant, vous devez ajouter les fichiers récemment ajoutés/modifiés : git add -A Puis vous devez valider les changements git commit -m “Update message” -a Remplacez la section “Update message” avec un bref résumé de ce que vous avez ajouté. Gardez le message entre guillemets ! git push origin master Cela remet les modifications dans votre copie de mon référentiel. Si vous renommez les branches, vous devez savoir en quoi vous avez changé l'origine et les noms de maîtres. Par défaut, cette commande devrait fonctionner. Now to actually send a pull request to the original repository: • Visit your repository on the github page. • Click “compare and review” (the green icon with two arrows forming a loop). • Choose the correct repository and branch (lswest:master and username:master, for example). • Review your changes. • Click on “Click to create a pull request for this comparison”. • Enter a title and description. • Click “Send pull request”. As of that point, the ball is now in my court and I need to review the proposed change and merge it or close it. If this article has whetted your appetite on LaTeX, let me know and I will return to this topic another time. Same with git and github – if you want more on that, let me know! Any other questions, comments or suggestions can be addressed to me at lswest34+fcm@gmail.com. Maintenant pour envoyer une demande de récupération au référentiel original: • visiter votre référentiel sur la page de github. • Cliquez sur « Compare and review » (l'icône verte avec deux flèches formant une boucle). • Choisir les bons référentiel et branche (lswest:master et username:master, par exemple). • Relire vos modifications. • Cliquez sur « Click to create a pull request for this comparison ». [Cliquez pour créer une demande de récupération pour cette comparaison] • Entrez un titre et une description. • Cliquez sur « Send pull request ». À partir de ce point, la balle est maintenant dans mon camp et j'ai besoin d'examiner le changement proposé et de le fusionner ou de le fermer. Si cet article a aiguisé votre appétit sur LaTeX, faites le moi savoir et je reviendrai sur ce sujet une autre fois. Même chose avec git et github : si vous en voulez plus, faites le moi savoir ! D'autres questions, commentaires ou suggestions peuvent m'être adressées à lswest34+fcm@gmail.com.