UNIX 103: more progress on document
[kspaans/UnixTutorial] / documents-editing-etc.pod
1 =head1 So you want to write a document
2
3 You can do it on the shell, faster, better, and with less frustration than
4 with a gui word processor. This tutorial assumes some familiarity with the unix
5 shell, and will cover useful programs used for editing and processing documents
6 with the shell.
7
8 =head2 First you need a "real editor"
9
10 You might be familiar with C<pico> or C<nano>, however these editors lack 
11 I<power>. What do I mean by I<power> in a text editor? I mean the editor has
12 support for scripting, regular expressions, quick manipulations of text, an
13 easy way to interface with the shell, and support for various development
14 tools. You shouldn't have to quit to compile, run tests, and even attach to
15 a debugger (well, thats a touchy subject). The editor should also support
16 easy navigation of multi-file projects and syntax highlighting for whatever
17 languages you decide to use. A lot of these features will be covered in later
18 tutorials, for now just familiarize yourself with the basics.
19
20 There are two major players in the real editor market: GNU Emacs and vim
21 (short for vi improved). Both of these have grown out of the real editors of
22 the past and offer similar capabilities but different interfaces. I suggest
23 you try both tutorials and pick the one you like more. There is a long history
24 of bitter argument over which is superior, most of the debate is largely
25 irelevant rhetoric, and the rest is personal opinion, so pick what you prefer
26 and don't fear switching.
27
28 To run the vim tutor, at the prompt type C<vimtutor>.
29
30 To run the emacs tutorial, start C<emacs> and then press C<Control+h> C<t>.
31
32 From there, make your choice and we'll continue on with the tutorial.
33
34 =head2 Formatting Documents
35
36 Chances are that when you've needed to write up assignments previously, you've
37 used a tool such as I<Microsoft Word> or I<OpenOffice Writer> to do them.
38 However, should you decide to start doing assignments for your math courses in a
39 normal word processor, it likely won't take you long to realize that they aren't
40 very well-suited to representing mathematical equations. Many folks before you
41 have encountered this issue, and a good number of them discovered I<LaTeX> as the
42 solution to their problem. 
43
44 LaTeX is a popular typesetting language, many of your profs actually use it
45 when they write out assignments or exams. It makes it quite easy to typeset math
46 in a nice and pretty way. You can download a sample LaTeX template from the CSC at a later date
47 to use as a basis for assignments. For the most part you don't need to worry
48 about what the existing code in there does. The various C<\usepackage> commands
49 provide functionality that'll come in handy during your assignments, and you'll
50 need to update the C<\title>, C<\author> and C<\date> commands with the
51 appropriate information for your assignment.
52
53 To actually convert the LaTeX file to a PDF, you can use the C<pdflatex>
54 command. This exists on the undergraduate environment, and can be easily
55 installed in most Linux distributions.
56
57  $ pdflatex a1.tex
58  ...
59  $ xpdf a1.pdf
60
61 In LaTeX, formatting is grouped into I<environments>. These are normally
62 indicated by C<\begin{...}> and C<\end{...}>. An obvious example that can be
63 seen is the C<\begin{enumerate}[1.]> command. The I<enumerate> environment lets
64 you create a numbered list, which will be useful when you're working on
65 assignments. One thing that stands out about this command is the part in square
66 brackets after the closing brace. This is an optional parameter which lets you
67 specify the numbering format. If you wanted a lettered list, you could use
68 C<[a.]>, or if you wanted roman numerals, you could use C<[i.]>. Most
69 environments, including enumerate, can be nested within each other. 
70
71 In order to print out the actual number within the enumerate environment, you
72 can simply use the C<\item> command. 
73
74  \begin{enumerate}[1.]
75  \item foo
76  \item bar
77  \end{enumerate}
78  
79 Now then, before we get to the actual math typesetting, let's look at one other
80 environment which will be rather handy for your math courses. It's called
81 I<proof>. 
82
83  \begin{proof}
84  Let $x = 2$, and $y = x$. Thus, $y = 2$.
85  \end{proof}
86  
87 In that last example, you may have noticed the dollar signs around the
88 equations. In LaTeX, dollar signs allow you to put math in-line. If you use
89 double dollar signs, it will be placed into a new paragraph and centered:
90
91  Let $x = 4$, thus $$x = 2 * 2$$
92
93 If you want to write out a number of equations with the equal signs all
94 aligned, then you need to use another environment. This is called I<eqnarray*>.
95 It provides three columns, which you indicate using ampersands: C<&>. When you
96 want to start a new line, you can use a double backslash: C<\\>.
97
98  \begin{eqnarray*}
99  x & = & 2 * 2 \\
100  & = & 4
101  \end{eqnarray*}
102
103 All of the prior environments (C<$>, C<$$>, and C<eqnarray*>) put you into math
104 mode. This means that all letters are changed to look fancy and math-like.
105 There are lots of neat things you can do within this environment with respect
106 to formatting:
107
108 =over
109
110 =item * Symbols
111  \pi \alpha
112
113 =item * Fractions
114  \frac{1}{2}
115
116 =item * Exponents
117  e^xe^{2x}
118
119 =item * Roots
120  \sqrt{2}+\sqrt[3]{5}
121
122 =item * Trig
123  \tan{x}+\cos{x}
124
125 =item * Integrals
126  \int^5_2{3x}dx
127
128 =back
129
130 You should be able to combine these basic sequences to represent most equations
131 you'll encounter during your various math courses. One thing you may notice is
132 that if you put in paretheses, they will stay the same size even if the
133 contents grow. For example:
134
135 =begin latex
136
137 $$(\frac{1}{2}) = \left(\frac{1}{2}\right)$$
138
139 =end latex
140
141 In order to get paretheses which look like those on the right, you need to put
142 C<\left> before the opening parenthesis, and C<\right> before the closing one.
143 This works with other types of delimiters as well, such as square brackets and
144 braces. Since braces are special characters within LaTeX, you'll need to escape
145 them (C<\{>, C<\}>) to use them. Additionally, if you only want a left or right
146 bracket to exist on its own, but still need it to scale, you can use a period
147 C<.> instead of the normal bracket with the left or right. If you put all of
148 these things together, you can get formulae like:
149
150  \begin{enumerate}[a)]
151   \item 
152    $$\int^{35}_{-2}{\frac{\pi^x}{2\sqrt{x} + \frac{3}{\tan{x}}}}dx 
153      - \left.\frac{x}{3}\right|^5_3$$
154   \item
155    \begin{proof}[Proof by obviousness:]
156     Let $x = a^2$, and $a = 2$. Thus,
157     \begin{eqnarray*}
158      x &= &a^2 \\
159        &= &2^2 \\
160             &= &4
161     \end{eqnarray*}
162    \end{proof}
163  \end{enumerate}
164
165 =begin latex
166
167 \begin{enumerate}[a)]
168 \item 
169 $$\int^{35}_{-2}{\frac{\pi^x}{2\sqrt{x} + \frac{3}{\tan{x}}}}dx 
170 - \left.\frac{x}{3}\right|^5_3$$
171 \item
172 \begin{proof}[Proof by obviousness:]
173 Let $x = a^2$, and $a = 2$. Thus,
174 \begin{eqnarray*}
175 x &= &a^2 \\
176 &= &2^2 \\
177 &= &4
178 \end{eqnarray*}
179 \end{proof}
180 \end{enumerate}
181
182 =end latex
183
184 One last thing you may want to be able to do with LaTeX is matrices. These are
185 done using the I<array> environment. Like I<enumerate> earlier, this takes an
186 extra parameter, which indicates the number and alignment of columns: C<l> for
187 left, C<r> for right, and C<c> for centred. If you want to add a line between
188 columns, you simply add a pipe, C<|>, between the letters representing the
189 columns. To add a horizontal line, you can use the C<\hline> command. Similarly
190 to the I<eqnarray*> environment, you use ampersands and backslashes to break
191 columns and lines. For example:
192
193  \begin{array}{rcc|l}
194  1 & 2 & 3 & 4 \\ \hline
195  50 & 10 & 30 & 20 \\
196  3.14 & e & x & i
197  \end{array}
198
199
200 =begin latex
201
202 $$\begin{array}{rcc|l}
203 1 & 2 & 3 & 4 \\ \hline
204 50 & 10 & 30 & 20 \\
205 3.14 & e & x & i
206 \end{array}$$
207
208 =end latex
209
210 For further reference, you can find a list of LaTeX symbols at
211 L<http://www.agu.org/symbols.html>.
212
213 =head2 Searching documents 
214
215 There is a program called C<grep> which stands for a common sequence of
216 commands in one of C<vim>'s predecessors: B<g>lobal B<r>egular B<e>xpression
217 B<p>rint. This ammounted to displaying the lines in the open file that matched
218 a pattern. C<grep> was created to expedite this process, and grew to be a
219 general purpose search program for finding things in files. 
220
221 C<grep> searches for matches to a pattern specified in a format called a
222 regular expression. The most basic regular expressions are simply strings
223 that are searched for, but other patterns can be specified through 
224 I<metacharacters> which specify quantities of characters and classes of
225 characters to match. To tell grep you're using an B<e>xtended pattern,
226 either use C<egrep> or pass the patern after the B<-E> flag. 
227
228 In an extended pattern there are quantifier characters C<?> C<*> C<+> which 
229 stand for zero or one (is it thereB<?>), zero or more (like a wild card B<*>), 
230 and one or more (wild card B<+> 1) of the preceeding character, respectively.
231 You can be more specific in the number of characters you want to match, using
232 C<{}> with either a number (C<{3})> or a range of numbers (C<{3,5}>).
233
234 There are also metacharacters that specify I<classes> of character, i.e. C<\w> 
235 matches on word characters, or [:alphanum:] matches alphanumeric characters. 
236 You can specify your own classes with C<[]>, listing all the characters you 
237 wish to match or character ranges like C<[a-z]> to specify the lower case 
238 alphabet. If you want a hyphen, make sure its either in the range or the first 
239 or last character. To find a long list of predefined classes check the man page
240 for C<grep>. 
241
242 To specify multiple alternative patterns separate them with a C<|> character,
243 and to create subgroups in which there are options wrap them in C<()>, like
244 this: C<.*\.(jpg|jpeg|gif|png)> to match all images (C<.> matches any character 
245 unless you escape it).
246
247 C<grep> can also recurse down directories with C<-R>, to seach many files, and
248 accept input on a pipe to filter it, as mentioned in the previous tutorial.
249
250 =head2 Bulk editing
251
252 Often it becomes necessary to edit many, many, documents with the same minor
253 trivial correction (like chainging colour to color because you're going to the
254 states). Do you really, really want to do it by hand? Really? I didn't think 
255 think so. It would be much nicer if substitution could be done all at once by
256 a program, or in the editor. Here's the good news: a program exists, and a real
257 editor will have this feature.
258
259 To specify a find and replace most programs in unix use a I<substitution
260 expression> wich is part string and part regular expression. Looking like
261 C<s/regex/string/> these expressions instruct the program to replace every
262 match of C<regex> with C<string>. You can also capture items in the regular
263 expression and re use them as variables in the string. Placing part of a
264 pattern in C<()> will capture it, then following it with a triple backslash
265 C<\\\> and the group number (capture groups are numbered left to right starting
266 at one) to have whatever is matched inside the parens go there.
267
268 In the previous tutorial we mentioned C<sed>. C<sed> is the classic program to 
269 perform substitutions, it takes a substitution expression (you should put
270 the expression in single quotes so the shell doesn't do odd things with your
271 pattern) and operates on standard in, giving the result to standard out. This
272 allows for C<sed> to be used in a pipe as discussed previously. C<sed> also has
273 an B<i>nline edit mode using the C<-i> flag, which edits a single file in
274 place. Before doing this its probably a good idea to make a backup of your
275 file, incase your command doesn't do exactly what you meant. You can also limit
276 the scope of your substitution to regions between two patterns, by specifying
277 the start pattern and the end pattern like this: C<START,ENDs/regex/pattern>.
278 C<sed> is more powerful than just steram substitution, and has a large 
279 featureset and programming language to specify automated editing.
280
281 "real editors" like C<vim> and C<emacs>, which we've mentioned earlier also
282 have support for substitution commands. In vim these should have been mentioned
283 in vimtutor, but if not, in command mode press C<:> and then type your 
284 expression to apply it to a line. To specify a range of lines use numbers like
285 you used a start and end regexes in C<sed>, or use C<%> to specify the whole
286 document. In C<emacs> type C<M-x> and run the C<replace-regexp> macro. By
287 default this works on the whole document, to restrict the scope mark a region.
288
289 =head2 Spellchecking
290
291 To spell check documents, including those marked up with C<latex>, most systems
292 provide a program called C<ispell>, which is an interactive spell checker.
293 C<ispell> is normally just run on a file, to run it on C<latex> specify the
294 C<-t> option for C<TeX>. C<ispell> will edit the file in place, if you'd like
295 a backup you can make one manually or pass the C<-b> option to have ispell
296 create one for you. The interaction screen in ispell is rather straightforeward
297 and if you would like more details you can read the man page. You can
298 also create a personal word list if you like, and this too is beyond the scope
299 of this tutorial.
300
301 =head2 Printing
302
303 Printing in the student unix environments is done with the C<lpr> command. C<lpr>
304 expects a plain text file by default, but with the filter option C<-F> you can
305 give it a C<.dvi> file output by C<latex> with C<-Fd> to filter the C<.dvi> into
306 something the printer can understand. C<lpr> also supports a wide variety of
307 fancy options though they vary by printer. Your best bet is to use the man page
308 on the student environment. The default printer you should be using is I<ljp_3016>.
309 This is the bank of printers in MC3016, and will print your job when you swipe your
310 watcard at a printer. To add money you need to go to first floor MC and use the terminal
311 outside the CHIP. Neither of those sentences were unix related, but to use the student.cs
312 environment legwork is sometimes required. To check how much quota you have left (or how
313 much you've overspent) the C<lpquota> command will give you a list.
314
315 For further details on the printing environment check 
316 L<http://www.cs.uwaterloo.ca/cscf/printing/environments/student-computing>.
317
318 =head2 About the Authors (when they wrote this)
319
320 =head3 Edgar Bering (ebering@csclub.uwaterloo.ca)
321
322 A student heading into his second year Edgar served as club secretary W08 and
323 plans on running for executive most of the rest of the time he's around.
324