Debian Codegraph @

texmf-dist/doc/latex/lineno/ulineno.tex

raw
1 % Copyright 1995--1999 Stephan I. Böttcher
2 %
3 % This program can be redistributed and/or modified under the terms
4 % of the LaTeX Project Public License Distributed from CTAN
5 % archives in directory macros/latex/base/lppl.txt; either
6 % version 1 of the License, or any later version.
7 %
8 % $Id: ulineno.tex,v 3.1 2001/08/03 03:29:19 stephan Exp $
9 %
10 % 1999-06-11 SiB: updated for lineno.sty v3.00
11 \ProvidesFile{ulineno.tex}[2001/08/03 lineno.sty users manual]
12 %% <- UL 2011/02/13 for readprov.sty
13
14 \documentclass[12pt,a4paper,titlepage]{article}
15
16 \date{\def\$##1: ##2 ##3${##2}%$
17 Version
18 \$Revision: 3.1 $,
19 \$Date: 2001/08/03 03:29:19 $
20 }
21 \def\lineno.sty{\texttt{\itshape lineno.sty}}
22
23
24 \title{ \lineno.sty
25 \\ Users Manual
26 }
27 \author{ Stephan I. Böttcher
28 }
29
30 \usepackage{lineno}
31 \usepackage{url}
32
33 \def~{\verb~}
34 \def\angle#1{$\langle${\itshape#1}\/$\rangle$}
35 \catcode`\|\catcode`\~
36 \def|#1{{\ttfamily\string#1}}
37 \def\NL{\angle{number}]}
38
39 \begin{document}
40 \begin{runninglinenumbers}
41 \renewcommand\linenumberfont{\normalfont\small\bfseries}
42 \setlength\linenumbersep{1cm}
43 \maketitle
44 \thispagestyle{empty}
45 \resetlinenumber
46 \tableofcontents
47 \clearpage
48 \setcounter{page}{1}
49 \pagewiselinenumbers
50
51 \section{When to use \lineno.sty}
52
53 The primary use of \lineno.sty is to get line numbers in your LaTeX
54 document. \lineno.sty directly supports line numbers in various
55 modes, and if you have any wishes that are not directly supported,
56 chances are good that \lineno.sty can be adapted to do it. And if it
57 turns out to be difficult with \lineno.sty, then it will be even more
58 difficult without.
59
60 There is one class of cases however, where \lineno.sty is not the most
61 appropriate tool. When your text already comes in lines, like source
62 listings, tables, poetry, then \lineno.sty will propably do the job,
63 but other tools could do it much more efficiently.
64
65 \lineno.sty can only number lines in the main text. Lines in any kind
66 of boxes cannot be numbered. But see section \ref{sec:ilineno} below.
67
68 \lineno.sty is especially useful when the text is broken into lines by
69 \TeX\ itself. In this case, the task to attach line numbers is not
70 easy, and a tool like \lineno.sty has good chances to break when used
71 together with other packages.
72
73 On the other hand, \lineno.sty proved to be quite stable, and I did
74 not get any reports of complete failure yet.
75
76 With \lineno.sty, you can refer to the line numbers via \LaTeX s
77 ~\ref~ and ~\pageref~ macros.
78
79 There are other applications, not directly related to line numbering.
80 Whenever you want to attach something to your text, after a paragraph
81 was broken into lines, across pagebreaks, lineno may do the job.
82
83 \begin{bframe}
84 Say, you need a frame around some text, but the text should be able
85 to break across pages, \lineno.sty can be used to draw rules on both
86 margins, which can be completed at the top and bottom by some
87 special environment, see section\,\,\ref{sec:bframe}.
88 \end{bframe}
89
90 There may be cases, where other packages do a better job, e.g.,
91 \url{CTAN:macros/latex/contrib/supported/numline}.
92
93
94 \section{Where to get \lineno.sty}
95
96 \lineno.sty is available on the \emph{Comprehensive TeX Archive
97 Network} (CTAN), e.g, \url{https://mirrors.ctan.org/macros/latex/contrib/lineno/lineno.sty}.
98
99 The home of \lineno.sty is \url{https://github.com/latex-lineno/lineno}. Here you can get the latest version.
100
101 \end{runninglinenumbers}
102
103 \section{How to use \lineno.sty}
104
105 As any other \LaTeXe\ package, you need to load it with
106 \begin{quote}
107 ~\usepackage[~\angle{options}~]{lineno}~
108 \end{quote}
109
110 \subsection{Package options}
111
112 The available \angle{options} are:
113 \begin{description}
114
115 \item[\texttt{[left]}:] Put the line numbers into the left margin
116 (default).
117
118 \item[\texttt{[right]}:] Put the line numbers into the right margin.
119
120 \item[\texttt{[switch]}:] Put the line numbers into the outer margin
121 (left on even numbered pager, right on odd numbered pages).
122
123 \item[\texttt{[switch*]}:] Put the line numbers into the inner
124 margin.
125
126 \item[\texttt{[pagewise]}:] Number the lines from 1 on each page.
127
128 \item[\texttt{[running]}:] Continuously number the lines (default).
129
130 \item[\texttt{[modulo]}:] Print line numbers only if they are
131 multiples of five.
132
133 \item[\texttt{[mathlines]}:] When using the ~{linenomath}~
134 environment for display math, put line numbers also on the lines of
135 the display.
136
137 \item[\texttt{[displaymath]}:] Automatically wrap the standard LaTeX
138 display math environments in ~{linenomath}~.
139
140 \begin{itshape}
141 Change from v2 to v3: ~[mathlines]~ was called ~[displaymath]~
142 before, and ~[displaymath]~ was ~\usepacke{mlineno}~.
143 \end{itshape}
144
145 \end{description}
146 All effects of these option can also be obtained by calling certain
147 macros later in the document, except for ~[displaymath]~.
148
149 \subsection{How to turn on line numbering}
150
151 The line numbering is not activated by default. If you want line
152 numbers, you have to turn it on. The simplest way is to say
153 \begin{quote}
154 ~\linenumbers~
155 \end{quote}
156 This will turn on line numbers within the current group, according to
157 the currently selected mode. If you do it right at the beginning, the
158 whole document will be numbered.
159
160 ~\linenumbers~ takes effect only when a paragraph is finished. This
161 is important if you use ~\linenumbers~ for a single paragraph only.
162 This will \emph{not} work:
163 \begin{quote}\obeylines
164 ~\begingroup~\\%
165 ~\linenumbers~
166 Text of your paragraph.
167 ~\endgroup~
168 \end{quote}
169 because the ~\endgroup~ terminates the effect of ~\linenumbers~ before
170 the paragraph is finished. The solution is to insert an empty line,
171 or an explicit ~\par~ before the ~\endgroup~.
172
173 The prefered solution is to use an enviroment:
174 \begin{quote}\obeylines
175 ~\begin{linenumbers}~
176 Text of your paragraph.
177 ~\end{linenumbers}~
178 \end{quote}
179 ~\end{linenumbers}~ terminates the paragraph for you. It will also
180 make sure that the next paragraph is not indented, if there is no
181 empty line in between.
182
183 This form will not finish any preceeding paragraph. If you do not
184 leave an empty line before ~\begin{linenumbers}~, the previous
185 paragraph may also get line numbers (this is not true after a list
186 environment).
187
188 A quite esoteric form to number a single paragraph is:
189 \begin{quote}\obeylines
190 Text of your paragraph.
191 ~{\linenumbers\par}~
192 \end{quote}
193 Here, the ~\linenumbers~ is turned on in a group that just executes
194 the ~\par~ to terminate the previous paragraph. Only this paragraph
195 will have line numbers. (~\par~ is exactly equivalent to an empty
196 line).
197
198
199 \subsection{How to turn off line numbering}
200
201 You do not usualy turn of line numbering explicitly, but rather
202 restrict line numbering to a group or an environment. However, you
203 can turn it off with the command
204 \begin{quote}
205 ~\nolinenumbers~
206 \end{quote}
207 This macro can also be used as an environment. The same restrictions
208 apply as for ~\linenumbers~.
209
210
211 \section{Numbering modes}
212
213 Attaching line numbers after \TeX\ has broken the paragraph into lines
214 is already quite a difficult job for \TeX. Why? Because \TeX\ does
215 not normally give you any control after line breaking. \lineno.sty
216 does it by pretending that the current page ends after each and every
217 line. This keeps \TeX\ quite busy, but works.
218
219 Often, you want the line numbers to depend on the page they finally end
220 up. E.g., you want the numbers to start with~ ~1 one each new page,
221 or you want them to appear on the outer margins in twoside mode. This
222 is an almost impossible demand, but \lineno.sty can do it, at some
223 cost, in terms of computing time, memory, and disk space. \lineno.sty
224 needs to write a note into the auxiliary file for each line in the
225 numbered part of the text, and \TeX\ keeps some memory for each page,
226 and all that takes some computation time to figure out on which page
227 the line was in the last \LaTeX\ run.
228
229 Thus, there are two basic numbering modes
230 \begin{enumerate}
231
232 \item \emph{Running} line numbers. The numbers run continuously along
233 the document, without considering page breaks.
234
235 The line numbers can be reset, or preset at any point in the
236 document (except within a paragraph). Margin switching (or any
237 other dependence on the page breaks) is not possible.
238
239 \item \emph{Pagewise} line numbers. The lines on each page are
240 numbered from one. Automatic margin switching is possible.
241
242 \emph{Running} mode can be simulated in pagewise mode, to get
243 automatic margin switching with continuous line numbers, but without
244 the ability to reset/preset the line numbers anywhere in the
245 document.
246
247 Any feature that depends on the page breaks must use this mode.
248
249 \end{enumerate}
250
251 \begin{runninglinenumbers*}
252
253 \subsection{\emph{Running} line numbers}
254
255 This is the default mode of operation. The lines of your text are
256 numbered continuously across page breaks.
257
258 You cannot get automatic margin switching in this mode, because at the
259 time when the line numbers are attached, it is not yet decided on
260 which page the line will end up. However, you can simulate continuous
261 line numbers in \emph{pagewise} mode (see below), where margin
262 switching becomes possible.
263
264 You get this mode by
265 \begin{itemize}\raggedright
266 \item \emph{not} specifying any of the package options
267 ~[switch,pagewise]~,
268 \item specifying the package option ~[running]~,
269 \item give the command ~\setrunninglinenumbers~ in the document, or
270 \item turn on line numbering with ~\runninglinenumbers~ or
271 ~\begin{runninglinenumbers}~.
272 \end{itemize}
273
274 \subsubsection{Reseting or setting the line number}
275
276 You can reset the line number with
277 \begin{quote}
278 ~\resetlinenumber[~\angle{number}~]~
279 \end{quote}
280 where the default is to reset the line number to one.
281
282 Alternatively, you can give the line number in an optional argument to
283 any command that turns on the line numbering in this mode:
284 \begin{quote}\obeylines
285 ~\linenumbers[~\angle{number}~]~
286 ~\runninglinenumbers[~\angle{number}~]~
287 ~\begin{linenumbers}[~\angle{number}~]~
288 ~\begin{runninglinenumbers}[~\angle{number}~]~
289 \end{quote}
290 or reset the line number to 1 with any of the following:
291 \begin{quote}\obeylines
292 ~\linenumbers*~
293 ~\runninglinenumbers*~
294 ~\begin{linenumbers*}~
295 ~\begin{linenumbers}*~
296 ~\begin{runninglinenumbers*}~
297 ~\begin{runninglinenumbers}*~
298 \end{quote}
299 This section of the manual is enclosed in
300 \begin{quote}\obeylines
301 ~\begin{runninglinenumbers*}~
302 ~\end{runninglinenumbers*}~
303 \end{quote}
304 \end{runninglinenumbers*}
305
306
307 \begin{pagewiselinenumbers}
308
309 \subsection{\emph{Pagewise} line numbers}
310
311 Basically, this mode prints line numbers starting with 1 on top of
312 each page, counting only lines where this mode is active. If you
313 turn on this mode in the middle of a page, the numbers start with 1
314 at that point.
315
316 The \emph{pagewise} mode of operation is quite a bit more work for
317 \TeX. When the line numbers are printed, \TeX\ does not know on which
318 page the current line will go. To get \emph{pagewise} mode working,
319 \LaTeX\ has to remember on which page the line went in a previous run.
320 This information is written into the ~.aux~ file, and like a table of
321 contents, you will not see the numbers until you run \LaTeX\ at least
322 twice on the document. Sometimes the information in the ~.aux~ file
323 becomes invalid in a way that causes \lineno.sty to hang. In such a
324 case you'll have to delete all ~.aux~ files of the document to get it
325 going again.
326
327 You get this mode by
328 \begin{itemize}\raggedright
329 \item specifying the package option
330 ~[pagewise]~, but not ~[running]~,
331 \item give the command ~\setpagewiselinenumbers~ in the document, or
332 \item turn on line numbering with ~\pagewiselinenumbers~ or
333 ~\begin{pagewiselinenumbers}~.
334 \end{itemize}
335
336 You cannot reset or preset the line numbers in \emph{pagewise} mode.
337 This mode uses a different counter than \emph{running} mode. You can
338 switch between the mode, and the \emph{running} numbers will continue
339 where they left of, unless you reset the counter.
340
341 \subsubsection{Margin switching}
342
343 As a side effect of all the business to find out on which page the lines
344 end up, margin switching becomes possible. It is now possible to
345 print the line number differently on odd and even pages. The command
346 \begin{quote}
347 ~\switchlinenumbers~
348 \end{quote}
349 will cause the line numbers to be printed on the outer margins, on the
350 right side for odd pages, and on the left side for even numbered
351 pages. If you add a star, the numbers go on the inner margins
352 \begin{quote}
353 ~\switchlinenumbers*~
354 \end{quote}
355 You can achieve the same effect by specifying the package
356 option ~[switch]~ or ~[switch*]~ together with ~[pagewise]~.
357
358 Margin switching is independent of any ~[twoside]~ option of the
359 document class.
360
361 \subsubsection{\emph{Running} mode with margin switching}
362
363 Margin switching is not possible in \emph{running} mode, but you can
364 abuse the pagewise mode to produce continuous line numbers. This mode
365 is activated with the command
366 \begin{quote}
367 ~\runningpagewiselinenumbers~
368 \end{quote}
369 It is not possible to reset the line number counter for this mode, the
370 lines will be numbered starting from one at the beginning of the
371 document, and continue. You can switch back to real pagewise mode with
372 \begin{quote}
373 ~\realpagewiselinenumbers~
374 \end{quote}
375 but when you resume \emph{running-pagewise}, the numbers will not
376 continue where they left off, but jump by the number of lines that
377 were numbered \emph{real-pagewise}.
378
379 The package options ~[switch]~ and ~[switch*]~ will turn on
380 \emph{running pagewise} mode with margin switching, unless you also
381 specify ~[pagewise]~.
382
383 Finally, if you give these options together with ~[running]~, like
384 \begin{quote}
385 ~\usepackage[switch,pagewise,running]{lineno}~
386 \end{quote}
387 the mode is set to plain \emph{running} line numbers, but later in
388 your document, if you say ~\pagewiselinenumbers~, the setings of the
389 ~[switch]~ and ~[pagewise]~ options will take effect.
390
391 \subsubsection{Page numbers}
392
393 Any pages that contain \emph{pagewise} numbered lines must have a
394 different page number. This may cause trouble with titlepages or
395 simmilar fudging with the page number counter in the document. (I am
396 talking about ~\c@page~ or ~\count 0~ here, not ~\thepage~).
397
398 If you get strange errors, like \emph{``the use of} ~\nextLN~
399 \emph{does not match its definition''}, you should first delete all
400 ~.aux~ files, and rerun \LaTeX\ several times. If the error does not
401 reappear, fine, else check your page numbers, including those that are
402 not printed. You may use \emph{running} line numbers on your
403 titlepages, since the page boundaries are predefined, usually.
404
405 \end{pagewiselinenumbers}
406
407 \begin{linenumbers*}
408
409 \subsection{Margin selection}
410
411 In any mode you can select a fixed margin on which the numbers shall
412 be printed. You can either give a package option ~[left]~ or
413 ~[right]~, or change the margin within the document with
414 \begin{quote}\obeylines
415 ~\leftlinenumbers~
416 \rightlinenumbers
417 ~\rightlinenumbers~
418 \end{quote}
419 \rightlinenumbers
420 Neither of these commands actually turns on line numbering. The
421 margin setting is changed for the currently selected mode
422 \emph{running} or \emph{pagewise}. If you want to set the margin for
423 both modes, append a star
424 \begin{quote}\obeylines
425 ~\leftlinenumbers*~
426 ~\rightlinenumbers*~
427 \end{quote}
428 The default is ~\leftlinenumbers*~.
429
430 \end{linenumbers*}
431
432
433 \subsection{Summary of mode selection commands}
434
435 The following commands change the major line numbering mode.
436 \begin{description}\itemsep=0pt\parskip=0pt
437 \item [|\setrunninglinenumbers]
438 \item [|\setpagewiselinenumbers] \leavevmode\\
439 set the current mode, without activating or deactivating line
440 numbering.
441 \item [|\runninglinenumbers\texttt{*[\NL}]
442 \item [|\pagewiselinenumbers] \leavevmode\\
443 set the current mode and activate line numbering, optionally reset
444 (~*~), or set the line number for \emph{running} mode.
445 \end{description}
446 The following commands do not change the major mode, but modify the
447 the behaviour of \emph{pagewise} mode
448 \begin{description}\itemsep=0pt\parskip=0pt
449 \item [|\realpagewiselinenumbers]
450 \item [|\runningpagewiselinenumbers] \leavevmode\\
451 select if \emph{pagewise} mode should number continuously, or really
452 pagewise.
453 \end{description}
454
455
456 \subsection{Summary of margin selection commands}
457
458 The following command select into which margin the numbers should be
459 printed
460 \begin{description}\itemsep=0pt\parskip=0pt
461 \item [|\leftlinenumbers\texttt*]
462 \item [|\rightlinenumbers\texttt*] \leavevmode\\
463 put the line numbers in the left/right margin in both modes.
464 \item [|\leftlinenumbers]
465 \item [|\rightlinenumbers] \leavevmode\\
466 put the line number into the left/right margin in the currently
467 selected mode.
468 \item [|\switchlinenumbers] \leavevmode\\
469 put the line numbers into the outer margin, when using
470 \emph{pagewise} mode.
471 \item [|\switchlinenumbers\texttt*] \leavevmode\\
472 put the line numbers into the inner margin, when using
473 \emph{pagewise} mode.
474 \end{description}
475
476 \begin{linenumbers*}
477 \modulolinenumbers[2]
478
479 \subsection{Numbering only one in five lines}
480
481 You can ask lineno to print the line numbers only if they devide by
482 \angle{n}, by saying
483 \begin{quote}
484 ~\modulolinenumbers[~\angle{n}~]~
485 \end{quote}
486 If you omit the optional argument, it will be every fifth line, or
487 whatever you used last (the current value of the counter
488 ~linenumbermodulo~). You get the same effect by giving the package
489 option ~[modulo]~.
490
491 If you set \angle{n} to 1, the modulo value is not changed, but modulo
492 numbering is turned off.
493
494 Changing the counter ~linenumbermodulo~ does not turn on modulo
495 numbering, it just changes the modulo, if it is turned on without the
496 optional argument.
497
498 This section of the manual is enclosed in
499 \begin{quote}
500 ~\begin{linenumbers*}~ \\
501 ~\modulolinenumbers[2]~
502
503 ~\end{linenumbers*}~
504 \end{quote}
505
506 \end{linenumbers*}
507
508 \begin{pagewiselinenumbers}
509 \switchlinenumbers
510
511 \subsection{How the line numbers look like}
512
513 This section of the manual is enclosed in
514 \begin{quote}
515 ~\begin{pagewiselinenumbers}~ \\
516 ~\switchlinenumbers~
517
518 ~\end{pagewiselinenumbers}~
519 \end{quote}
520 By default, the line numbers are set in
521 \begin{quote}
522 ~\normalfont\tiny\sffamily~
523 \end{quote}
524 right justified to 10\,pt left of the nominal left edge of the text.
525 If the number is to appear on the right margin, it is right justified
526 to 20\,pt right of the nominal right edge of the text.
527
528 You can easily change that, of course. The font is defined by the
529 macro
530 \begin{quote}
531 ~\linenumberfont~
532 \end{quote}
533 You can redefine it to make the numbers appear in a differnt font
534 (with ~\renewcommand~). I'll say right here in this manual
535 \renewcommand\linenumberfont{\normalfont\bfseries\small}
536 \begin{quote}
537 ~\renewcommand\linenumberfont{\normalfont\bfseries\small}~
538 \end{quote}
539 The distance on the left margin can be changed with
540 \begin{quote}
541 ~\setlength\linenumbersep{~\angle{distance}~}~
542 \end{quote}
543 The distance on the right margin is ~\linenumbersep~ plus
544 ~\linenumberwidth~, both are set to 10\,pt by default.
545 Let's do right here
546 \setlength\linenumberwidth{1cm}
547 \begin{quote}
548 ~\setlength\linenumbersep{1cm}~
549 \end{quote}
550 I put the command at the end of the paragraph, but it effects the
551 whole paragraph, because that is where everything happens: at the end
552 of the paragraphs.
553
554 The line numbers are printed as arabic numerals, as defined in the
555 macro
556 \begin{quote}
557 ~\thelinenumber~
558 \end{quote}
559 for the \LaTeX\ counter ~{linenumber}~. You can redefine that, as
560 for any other \LaTeX\ counter. E.g.,
561 \renewcommand\thelinenumber{\roman{linenumber}}
562 \begin{quote}
563 ~\renewcommand\thelinenumber{\roman{linenumber}}~
564 \end{quote}
565 (For heavy duty line numbering, you should use \LaTeX s internal
566 format, e.g., ~\@roman\c@linenumber~.)
567
568 \subsubsection{Deeper customization}
569
570 The line number is attached to the line by the macro
571 \begin{quote}
572 ~\makeLineNumber~
573 \end{quote}
574 which is expanded inside a zero width ~\hbox~ alligned to the
575 origin of the current line (left edge, baselines alligned). You can
576 do anything in this macro. Let's assume you do not want line numbers
577 at all, but just attach something else to each line of text: this is
578 the macro to modify. You can refer to the line number by the macro
579 ~\LineNumber~, which prints the current value of the counter
580 ~{linenumber}~, or nothing if \emph{modulo} mode is active, and the
581 number does not divide by ~{linenumbermodulo}~. You should not modify
582 this macro when using any form of \emph{pagewise} mode. At the end of
583 this paragraph I put the following
584 \begin{runninglinenumbers}
585 \renewcommand\makeLineNumber
586 {\hss$\rightarrow$\ \rlap{\hskip\textwidth\ $\leftarrow$}}
587 \end{runninglinenumbers}
588 \begin{quote}
589 ~\begin{runninglinenumbers}~\\
590 ~\renewcommand\makeLineNumber~\\
591 ~ {\hss$\rightarrow$\ \rlap{\hskip\textwidth\ $\leftarrow$}}~\\
592 ~\end{runninglinenumbers}~
593 \end{quote}
594
595 Redefining ~\makeLineNumber~ cuts deep into the linenumber mode
596 setting. If you still want to use the basic modes \emph{running} and
597 \emph{pagewise} you should go one level up and modify one of the
598 following macros, which are called by (or assigned to)
599 ~\makeLineNumber~ depending on the current mode, and with the counter
600 ~{linenumber}~ allready adjusted for the current page when using
601 \emph{pagewise} mode.
602 \begin{quote}\obeylines
603 ~\makeLineNumberRunning~
604 ~\makeLineNumberOdd~
605 ~\makeLineNumberEven~
606 \end{quote}
607 The first is used in \emph{running} mode, the other two in
608 \emph{pagewise} mode. If you modify those, you cut into the
609 margin selection mechanism as advertised above. You will have to call
610 a mode selection command after changing these macros, to make them take
611 effect (at least for ~\makeLineNumberRunning~).
612
613 You can go up one more step. The margin selection commands redefine
614 the above macros by making them equivalent (~\let~) to one of the
615 following macros
616 \begin{quote}\obeylines
617 ~\makeLineNumberLeft~
618 ~\makeLineNumberRight~
619 \end{quote}
620 You may redefine these, and afterwards issue a margin selection
621 command followed by a mode selection command. The default definitions
622 are
623 \begin{quote}
624 ~\def\makeLineNumberLeft~\\
625 ~ {\hss\linenumberfont\LineNumber\hskip\linenumbersep}~
626 \end{quote}
627 and
628 \begin{quote}
629 ~\def\makeLineNumberRight~\\
630 ~ {\linenumberfont\hskip\linenumbersep\hskip\textwidth~\\
631 ~ \hbox to\linenumberwidth{\hss\LineNumber}\hss}~
632 \end{quote}
633 Whatever you do, use ~\LineNumber~ to print the digits. This ensures
634 that the modulo mode setting is acknowledged. If you want to
635 customize that as well, this is the macro to change. ~\LineNumber~
636 eventually refers to ~\thelinenumber~, which is the place to customize
637 the numerals themselves. At the end of this paragraph I said
638 \renewcommand\LineNumber{\ifodd\value{linenumber} \thelinenumber)\fi}
639 \begin{quote}
640 ~\renewcommand\LineNumber~\\
641 ~ {\ifodd\value{linenumber} \thelinenumber)\fi}~
642 \end{quote}
643 Line number references are not affected by ~\LineNumber~, but you
644 should keep track of ~\thelinenumber~. Look at the following
645 reference
646 \begin{quote}
647 The setion title of the next section is on page \pageref{ll1}, line
648 \ref{ll1}.
649 \end{quote}
650 There is a mismatch in the definition of ~\thelinenumber~, from the
651 point of the refered line to the reference here.
652 \end{pagewiselinenumbers}
653
654 \begin{pagewiselinenumbers}
655
656 \section[Line number references]
657 {Line number references\linelabel{ll1}}
658
659 \lineno.sty allows to refer to a line number with ~\ref{~\angle{label}~}~.
660 The label is set by ~\linelabel{~\angle{label}~}~, anywhere in a paragraph
661 that gets line numbers. If you put a ~\linelabel~ somewhere else, the
662 line number it refers to is pretty meaningless, but no error message
663 is issued. (This section begins on line \ref{ll1}, page
664 \pageref{ll1} and ends on line \ref{ll2}, page \pageref{ll2}.)
665
666 References work both in \emph{running} and \emph{pagewise} modes.
667 However, you have to be very careful when using both \emph{real
668 pagewise} mode and \emph{running pagewise} mode: The mode setting
669 must be the same during reference as during labeling.
670
671 The restrictions on placing a ~\linelabel~ are the same as for a
672 ~\marginpar~. (In fact, they are implemented as fake ~\marginpar~s.)
673 E.g., the linelabel on the section header of this chapter could not be
674 placed in the straight forward way, because it would cause an error in
675 the table of contents. (It should be disabled during \emph{toc}
676 processing.) Instead, I typed
677 \begin{quote}
678 ~\section[Line number references]~\\
679 ~ {Line number references\linelabel{ll1}}~
680 \end{quote}
681 This works fine, with the standard \LaTeX\ ~{article}~ document
682 style. If more generic markup is required, you should avoid things
683 like this (you should avoid \lineno.sty altogether, in that case).
684
685 ~\linelabel~ does not work in display math. (Why, you do not use
686 equation numbers?)
687
688 The ~\linelabel~ command starts a new paragraph if it is issued after
689 an empty line. It will properly ignore further whitespace before the
690 first word of text. Thus you can easily get a label to the first line
691 of a paragraph.
692
693 Furthermore, ~\linelabel~ uses \LaTeX s standart tricks to avoid
694 unnecessary spaces if you place is between two words with spaces
695 around, but you should not do that anyway, if you want to make sure
696 that the label applies to a certain word in the text. You should
697 attach the line label to the word in question without intervening
698 spaces, either before of after the word. If you leave spaces both
699 before and after the ~\linelabel~ command, the current implemenation
700 attaches the line label to the following word (by ignoring the
701 trailing space).
702
703 Special care should be taken at the end of a paragraph. You better
704 put the line label without intervening spaces behind the period, like
705 this
706 \begin{quote}
707 ~This is the end of this section.%~\\
708 ~\linelabel{ll2}~
709 \end{quote}
710 This is the end of this section.%
711 \linelabel{ll2}
712
713 \end{pagewiselinenumbers}
714
715 \begin{linenumbers*}
716
717
718 \section{Known incompatibilities}
719
720 This section will expand whenever somebody discovers problems when
721 using \lineno.sty together with other \LaTeX\ packages.
722
723 \subsection{\texttt{wrapfig.sty}}
724
725 \lineno.sty used to have problems with \texttt{wrapfig.sty}, but this
726 is solved but \lineno.sty, version 2.05.
727
728
729 \section{Extension packages}
730
731 The extension packages were abolished with version v3.00 of
732 \lineno.sty. One package, ~itemrule.sty~, was dropped, the others
733 were put directly into the the main \lineno.sty package file.
734
735 \subsection{Display math, \texttt{\itshape mlineno}}
736
737 \lineno.sty does not work well with display math. The parts of a
738 paragraph preceeding a display math will not get line numbers. The
739 reason is that the paragraph is not finished, but the part above the
740 display is broken into lines anyway.
741
742 Let me demonstrate the effect. This paragraph contains a
743 ~{displaymath}~ environment. The part before the Formula does not get
744 line numbers. Here comes the Formula
745 \begin{displaymath}
746 \mathrm{6\,H_2O + 6\,CO_2 \ \rightarrow\ C_6H_{12}O_6 + 6\,O_2}
747 \end{displaymath}
748 which makes the line numbers disappear. The trailing part of the
749 paragraph does get line numbers.
750
751 There are several means to solve the problem, but none of them is
752 fully satisfactory. \lineno.sty defines a ~{linenomath}~ environment,
753 which can be wrapped around a display math to make the line numbering
754 work. This will work with any kind of display math, even if you use
755 explicit ~$$~ pairs. There is a ~*~-form ~{linenomath*}~ which also
756 numbers the lines of the display itself, as good as it can. Here
757 comes an example use of ~{linenomath*}~
758 \begin{linenomath*}
759 \begin{eqnarray*}
760 b_1 &=& a_{11}x_1 + a_{12}x_2 \\
761 b_2 &=& a_{21}x_1 + a_{22}x_2
762 \end{eqnarray*}
763 \end{linenomath*}
764 wrapping an ~{egnarray*}~ like this
765 \begin{quote}
766 ~\begin{linenomath*}~\\
767 ~ \begin{eqnarray*}~\\
768 ~ b_1 &=& a_{11}x_1 + a_{12}x_2 \\~\\
769 ~ b_2 &=& a_{21}x_1 + a_{22}x_2~\\
770 ~ \end{eqnarray*}~\\
771 ~\end{linenomath*}~
772 \end{quote}
773 Specifying the package option ~[mathlines]~, causes the
774 ~{linenomath}~ environment to switch its function with its *-form.
775 This allows you to later decide if you want the numbers on the formulas
776 or not, without putting in stars everywhere (as long as you have been
777 consistent).
778
779 The ~{linenomath}~ wrapper does nothing if line numbering is not
780 activated. You do not need to remove them if you decide to omit the
781 line numbering later (although you still have to load \lineno.sty).
782
783 The \texttt{\itshape mlineno} extension redefines the standard \LaTeX\
784 display math environments to wrap themselves automatically into
785 ~{linenomath}~:
786 \begin{quote}\obeylines
787 ~\[~ ~\]~
788 ~{displaymath}~
789 ~{equation}~
790 ~{eqnarray}~
791 ~{eqnarray*}~
792 \end{quote}
793 As of version 3.00 you can activate this by the package option
794 ~[displaymath]~. You can keep existing explicit ~{linenomath}~
795 wrappers without harm.
796
797 This will probably not work with AMSmath.
798
799 Other solutions to make \lineno.sty work with display math are either
800 ugly or less stable. The ugly possibility is to precede every display
801 math with an empty line, or better with
802 \begin{quote}
803 ~{\par\nobreak\noindent}~
804 \end{quote}
805 but this gains you nothing compared to using the ~{linenomath}~
806 environment, since you still have to modify your document.
807
808 \end{linenumbers*}
809
810
811 \subsection{\texttt{\itshape rlineno}}
812
813 \begin{runninglinenumbers}
814 It is currently not possible to put a ~\linelabel~ into math mode.
815 This should not impose problems with inline math, since you can attach
816 the label just outside the math shift, like\linelabel{rll1}
817 \begin{quote}
818 ~... \linelabel{~\angle{label}~}$x=f(y)$ ...~
819 \end{quote}
820 but to refer to a line in display math, you cannot label it directly.
821 \end{runninglinenumbers}
822
823 \begin{pagewiselinenumbers}
824 The extension \texttt{\itshape rlineno} offers a solution,
825 allowing to refer to a line number with an offset.
826
827 This extension is now available with plain \lineno.sty v3.00.
828
829 You put the ~\linelabel~ at the end of the preceeding line, and refer
830 to that number, plus 1 or, in case of multiline displays, by any other
831 offset.\linelabel{rll2}
832 \begin{quote}
833 ~...\linelabel{~\angle{label}~}~ \\
834 ~\begin{equation}~ \\
835 ~ y=f'(x)~ \\
836 ~\end{equation}~ \\
837 ~... the formula in line \lineref[+1]{~\angle{label}~}~
838 \end{quote}
839 The offset calculation is different for pagewise or running line
840 numbers, and you will have to make sure the right method is used.
841 \end{pagewiselinenumbers}
842
843 The macro ~\lineref[~\angle{offset}~]{~\angle{label}~}~ uses the method of the
844 currently selected mode (line numbering need not be activated). To
845 specify the mode explicitly, use ~\linerefr~ or ~\linerefp~ for
846 running or pagewise mode respectively.
847
848 For example, the manual sets a ~\linelabel{rll1}~ at the end of the
849 line preceeding the single line quote environment at
850 line\,\linerefr[+1]{rll1} in the first paragraph of this chapter, and
851 refered to it via
852 \begin{quote}
853 ~\linerefr[+1]{rll1}~
854 \end{quote}
855 and another one preceeding the quote environment in the second
856 paragraph of this chapter, with the central line
857 numbered\,\linerefp[+3]{rll2}, which I just refered to via
858 \begin{quote}
859 ~\linerefp[+3]{rll2}~
860 \end{quote}
861 \begin{runninglinenumbers}
862 If the correct mode is selected (e.g., ~\setrunninglinenumbers~),
863 you can use ~\lineref[+1]{rll1}~ to refer to
864 line\,\lineref[+1]{rll1}.
865 \end{runninglinenumbers}
866
867
868 \subsection{\texttt{\itshape numquote}}
869
870 This extension defines two environments, each of them with a *-form or
871 alternatively an optional argument.
872 \begin{quote}\obeylines
873 ~\begin{numquote}~
874 ~\end{numquote}~
875 \end{quote}
876 is like ~{quote}~,
877 \begin{quote}\obeylines
878 ~\begin{numquotation}~
879 ~\end{numquotation}~
880 \end{quote}
881 is like ~{quotation}~, but with the lines numbered. Numbering
882 restarts with 1 each time it is used, except you use the *-form, or
883 specify the line number to start with in an optional argument.
884 \begin{numquote}
885 The line numbers set to the left of the text, indented by the same
886 amount as the quote or quotation. This works as expected even if the
887 quote appears in a nested list.
888 \end{numquote}
889 To customize the distance from the text or the shape of the
890 numbers, you can modify the macros ~\quotelinenumbersep~ and
891 ~\quotelinenumberfont~ respectively.
892
893 As of version 3.00, this is available directly with \lineno.sty.
894
895 \clearpage
896
897 \subsection{\texttt{\itshape ilineno}}
898 \label{sec:ilineno}
899
900 \begin{center}
901 \noindent\fbox{\parbox{0.8\textwidth}{
902 \internallinenumbers \resetlinenumber[13]
903 Sometimes you need line numbers within a |\parbox\ or figure. This
904 extension can do that, if the text is simple enough. It works by
905 drawing a ladder of numbers next to the paragraph, each number
906 vertically separated by |\baselineskip\ from the other. This
907 obviously dose not work nicely with anything but straight text.
908 Extra high lines (like this: $\displaystyle x=\frac AB$) will
909 disturb the alignment. The power of \lineno.sty is not necessary to
910 achieve this, but you may need both in one document with a somewhat
911 coherent interface, and some of the necessary infrastructure from
912 \lineno.sty is actually useful.
913 }}\end{center}
914 % Why is the v-spacing wrong here?
915
916 The preceding paragraph was set like this:
917 \begin{quote}
918 ~\begin{center}\fbox{\parbox{0.8\textwidth}{~ \\
919 ~\internallinenumbers~ \\
920 ~\resetlinenumber[13]~ \\
921 ~ ~ Sometimes you need \dots \\
922 ~}}\end{center}~
923 \end{quote}
924
925 \subsection{\texttt{\itshape itemrule.sty}}
926
927 Somebody asked me if he can get a rule next to an itemized item, from
928 the bullet downwards. This style did that. It was unstable and of
929 little interest, so it is gone from the \lineno.sty distribution.
930
931 \subsection{\texttt{\itshape bframe}}
932 \label{sec:bframe}
933
934 \setlength\bframesep{10pt}
935 \begin{bframe}
936 \lineno.sty can be used for unexpected purposes. The environment
937 \begin{quote}\obeylines
938 ~\begin{bframe}~
939 ~\end{bframe}~
940 \end{quote}
941 draws boxes around some text, even across page breaks. At a page
942 break, the box is open (it is difficult to fix that). There are two
943 parameters:
944 \begin{description}\itemsep=0pt\parskip=0pt
945 \item [|\bframesep] \leavevmode\\
946 defines the separation of the box from the text.
947 \item [|\bframerule] \leavevmode\\
948 defines the thickness of the lines around the text.
949 \end{description}
950
951 It works by asking \lineno.sty to draw small rules left and right to
952 the lines. The total height of the rules is ~\baselineskip~ plus
953 ~\bframesep~. This leaves some extra space for extra high lines.
954
955 The current version is very preliminary. In a future version there
956 may be a possibility to move the vertical lines inwards for indented
957 text. The box may optionally be closed at page breaks. It will not
958 likely be possible to have a colored background in the box, at least
959 not with a graphics driver that cannot put a background behind
960 existing foreground (Postscript cannot, I've been told). Tell me how
961 to make a gray background, like block dots on transparent, and I can
962 do shaded boxes.
963
964 \end{bframe}
965
966 \section{How to print the documented source}
967
968 \begin{bframe}
969 \lineno.sty is written in three programming languages: \TeX, sh,
970 and awk.
971
972 The file can be loaded as a \LaTeXe\ package as it is. However, if
973 you feed it into a Unix shell, like
974 \begin{quote}
975 ~csh> source ./lineno.sty~
976 \end{quote}
977 it will produce the files ~lineno.tex~ and ~lineno.dvi~, which is the
978 documented source of \lineno.sty. If you want to learn how it works,
979 or you need to adapt \lineno.sty for some special requirements, you
980 should read that document.
981 \end{bframe}
982
983 \end{document}