% Copyright 1995--1999 Stephan I. B"ottcher % % This program can be redistributed and/or modified under the terms % of the LaTeX Project Public License Distributed from CTAN % archives in directory macros/latex/base/lppl.txt; either % version 1 of the License, or any later version. % % $Id: ulineno.tex,v 3.1 2001/08/03 03:29:19 stephan Exp $ % % 1999-06-11 SiB: updated for lineno.sty v3.00 \ProvidesFile{ulineno.tex}[2001/08/03 lineno.sty users manual] %% <- UL 2011/02/13 for readprov.sty \documentclass[12pt,a4paper,titlepage]{article} \date{\def\$##1: ##2 ##3${##2}%$ Version \$Revision: 3.1 $, \$Date: 2001/08/03 03:29:19 $ } \def\lineno.sty{\texttt{\itshape lineno.sty}} \title{ \lineno.sty \\ Users Manual } \author{ Stephan I. B\"ottcher } \usepackage{lineno} \usepackage{url} \def~{\verb~} \catcode`\<\catcode`\~ \def<#1>{$\langle${\itshape#1}\/$\rangle$} \catcode`\|\catcode`\~ \def|#1{{\ttfamily\string#1}} \def\NL{]} \begin{document} \begin{runninglinenumbers} \renewcommand\linenumberfont{\normalfont\small\bfseries} \setlength\linenumbersep{1cm} \maketitle \thispagestyle{empty} \resetlinenumber \tableofcontents \clearpage \setcounter{page}{1} \pagewiselinenumbers \section{When to use \lineno.sty} The primary use of \lineno.sty is to get line numbers in your LaTeX document. \lineno.sty directly supports line numbers in various modes, and if you have any wishes that are not directly supported, chances are good that \lineno.sty can be adapted to do it. And if it turns out to be difficult with \lineno.sty, then it will be even more difficult without. There is one class of cases however, where \lineno.sty is not the most appropriate tool. When your text already comes in lines, like source listings, tables, poetry, then \lineno.sty will propably do the job, but other tools could do it much more efficiently. \lineno.sty can only number lines in the main text. Lines in any kind of boxes cannot be numbered. But see section \ref{sec:ilineno} below. \lineno.sty is especially useful when the text is broken into lines by \TeX\ itself. In this case, the task to attach line numbers is not easy, and a tool like \lineno.sty has good chances to break when used together with other packages. On the other hand, \lineno.sty proved to be quite stable, and I did not get any reports of complete failure yet. With \lineno.sty, you can refer to the line numbers via \LaTeX s ~\ref~ and ~\pageref~ macros. There are other applications, not directly related to line numbering. Whenever you want to attach something to your text, after a paragraph was broken into lines, across pagebreaks, lineno may do the job. \begin{bframe} Say, you need a frame around some text, but the text should be able to break across pages, \lineno.sty can be used to draw rules on both margins, which can be completed at the top and bottom by some special environment, see section\,\,\ref{sec:bframe}. \end{bframe} There may be cases, where other packages do a better job, e.g., \url{CTAN:macros/latex/contrib/supported/numline}. \section{Where to get \lineno.sty} \lineno.sty is available on the \emph{Comprehensive TeX Archive Network} (CTAN), e.g, \url{ftp:// ftp.tex.ac.uk/ tex-archive/ macros/ latex/ contrib/ supported/ lineno/ lineno.sty}. The home of \lineno.sty is \url{http:// www.nevis.columbia.edu/ ~stephan/ tex/ #lineno}. Here you can get the latest version. \end{runninglinenumbers} \section{How to use \lineno.sty} As any other \LaTeXe\ package, you need to load it with \begin{quote} ~\usepackage[~~]{lineno}~ \end{quote} \subsection{Package options} The available are: \begin{description} \item[\texttt{[left]}:] Put the line numbers into the left margin (default). \item[\texttt{[right]}:] Put the line numbers into the right margin. \item[\texttt{[switch]}:] Put the line numbers into the outer margin (left on even numbered pager, right on odd numbered pages). \item[\texttt{[switch*]}:] Put the line numbers into the inner margin. \item[\texttt{[pagewise]}:] Number the lines from 1 on each page. \item[\texttt{[running]}:] Continuously number the lines (default). \item[\texttt{[modulo]}:] Print line numbers only if they are multiples of five. \item[\texttt{[mathlines]}:] When using the ~{linenomath}~ environment for display math, put line numbers also on the lines of the display. \item[\texttt{[displaymath]}:] Automatically wrap the standard LaTeX display math environments in ~{linenomath}~. \begin{itshape} Change from v2 to v3: ~[mathlines]~ was called ~[displaymath]~ before, and ~[displaymath]~ was ~\usepacke{mlineno}~. \end{itshape} \end{description} All effects of these option can also be obtained by calling certain macros later in the document, except for ~[displaymath]~. \subsection{How to turn on line numbering} The line numbering is not activated by default. If you want line numbers, you have to turn it on. The simplest way is to say \begin{quote} ~\linenumbers~ \end{quote} This will turn on line numbers within the current group, according to the currently selected mode. If you do it right at the beginning, the whole document will be numbered. ~\linenumbers~ takes effect only when a paragraph is finished. This is important if you use ~\linenumbers~ for a single paragraph only. This will \emph{not} work: \begin{quote}\obeylines ~\begingroup~\\% ~\linenumbers~ Text of your paragraph. ~\endgroup~ \end{quote} because the ~\endgroup~ terminates the effect of ~\linenumbers~ before the paragraph is finished. The solution is to insert an empty line, or an explicit ~\par~ before the ~\endgroup~. The prefered solution is to use an enviroment: \begin{quote}\obeylines ~\begin{linenumbers}~ Text of your paragraph. ~\end{linenumbers}~ \end{quote} ~\end{linenumbers}~ terminates the paragraph for you. It will also make sure that the next paragraph is not indented, if there is no empty line in between. This form will not finish any preceeding paragraph. If you do not leave an empty line before ~\begin{linenumbers}~, the previous paragraph may also get line numbers (this is not true after a list environment). A quite esoteric form to number a single paragraph is: \begin{quote}\obeylines Text of your paragraph. ~{\linenumbers\par}~ \end{quote} Here, the ~\linenumbers~ is turned on in a group that just executes the ~\par~ to terminate the previous paragraph. Only this paragraph will have line numbers. (~\par~ is exactly equivalent to an empty line). \subsection{How to turn off line numbering} You do not usualy turn of line numbering explicitly, but rather restrict line numbering to a group or an environment. However, you can turn it off with the command \begin{quote} ~\nolinenumbers~ \end{quote} This macro can also be used as an environment. The same restrictions apply as for ~\linenumbers~. \section{Numbering modes} Attaching line numbers after \TeX\ has broken the paragraph into lines is already quite a difficult job for \TeX. Why? Because \TeX\ does not normally give you any control after line breaking. \lineno.sty does it by pretending that the current page ends after each and every line. This keeps \TeX\ quite busy, but works. Often, you want the line numbers to depend on the page they finally end up. E.g., you want the numbers to start with~ ~1 one each new page, or you want them to appear on the outer margins in twoside mode. This is an almost impossible demand, but \lineno.sty can do it, at some cost, in terms of computing time, memory, and disk space. \lineno.sty needs to write a note into the auxiliary file for each line in the numbered part of the text, and \TeX\ keeps some memory for each page, and all that takes some computation time to figure out on which page the line was in the last \LaTeX\ run. Thus, there are two basic numbering modes \begin{enumerate} \item \emph{Running} line numbers. The numbers run continuously along the document, without considering page breaks. The line numbers can be reset, or preset at any point in the document (except within a paragraph). Margin switching (or any other dependence on the page breaks) is not possible. \item \emph{Pagewise} line numbers. The lines on each page are numbered from one. Automatic margin switching is possible. \emph{Running} mode can be simulated in pagewise mode, to get automatic margin switching with continuous line numbers, but without the ability to reset/preset the line numbers anywhere in the document. Any feature that depends on the page breaks must use this mode. \end{enumerate} \begin{runninglinenumbers*} \subsection{\emph{Running} line numbers} This is the default mode of operation. The lines of your text are numbered continuously across page breaks. You cannot get automatic margin switching in this mode, because at the time when the line numbers are attached, it is not yet decided on which page the line will end up. However, you can simulate continuous line numbers in \emph{pagewise} mode (see below), where margin switching becomes possible. You get this mode by \begin{itemize}\raggedright \item \emph{not} specifying any of the package options ~[switch,pagewise]~, \item specifying the package option ~[running]~, \item give the command ~\setrunninglinenumbers~ in the document, or \item turn on line numbering with ~\runninglinenumbers~ or ~\begin{runninglinenumbers}~. \end{itemize} \subsubsection{Reseting or setting the line number} You can reset the line number with \begin{quote} ~\resetlinenumber[~~]~ \end{quote} where the default is to reset the line number to one. Alternatively, you can give the line number in an optional argument to any command that turns on the line numbering in this mode: \begin{quote}\obeylines ~\linenumbers[~~]~ ~\runninglinenumbers[~~]~ ~\begin{linenumbers}[~~]~ ~\begin{runninglinenumbers}[~~]~ \end{quote} or reset the line number to 1 with any of the following: \begin{quote}\obeylines ~\linenumbers*~ ~\runninglinenumbers*~ ~\begin{linenumbers*}~ ~\begin{linenumbers}*~ ~\begin{runninglinenumbers*}~ ~\begin{runninglinenumbers}*~ \end{quote} This section of the manual is enclosed in \begin{quote}\obeylines ~\begin{runninglinenumbers*}~ ~\end{runninglinenumbers*}~ \end{quote} \end{runninglinenumbers*} \begin{pagewiselinenumbers} \subsection{\emph{Pagewise} line numbers} Basically, this mode prints line numbers starting with 1 on top of each page, counting only lines where this mode is active. If you turn on this mode in the middle of a page, the numbers start with 1 at that point. The \emph{pagewise} mode of operation is quite a bit more work for \TeX. When the line numbers are printed, \TeX\ does not know on which page the current line will go. To get \emph{pagewise} mode working, \LaTeX\ has to remember on which page the line went in a previous run. This information is written into the ~.aux~ file, and like a table of contents, you will not see the numbers until you run \LaTeX\ at least twice on the document. Sometimes the information in the ~.aux~ file becomes invalid in a way that causes \lineno.sty to hang. In such a case you'll have to delete all ~.aux~ files of the document to get it going again. You get this mode by \begin{itemize}\raggedright \item specifying the package option ~[pagewise]~, but not ~[running]~, \item give the command ~\setpagewiselinenumbers~ in the document, or \item turn on line numbering with ~\pagewiselinenumbers~ or ~\begin{pagewiselinenumbers}~. \end{itemize} You cannot reset or preset the line numbers in \emph{pagewise} mode. This mode uses a different counter than \emph{running} mode. You can switch between the mode, and the \emph{running} numbers will continue where they left of, unless you reset the counter. \subsubsection{Margin switching} As a side effect of all the business to find out on which page the lines end up, margin switching becomes possible. It is now possible to print the line number differently on odd and even pages. The command \begin{quote} ~\switchlinenumbers~ \end{quote} will cause the line numbers to be printed on the outer margins, on the right side for odd pages, and on the left side for even numbered pages. If you add a star, the numbers go on the inner margins \begin{quote} ~\switchlinenumbers*~ \end{quote} You can achieve the same effect by specifying the package option ~[switch]~ or ~[switch*]~ together with ~[pagewise]~. Margin switching is independent of any ~[twoside]~ option of the document class. \subsubsection{\emph{Running} mode with margin switching} Margin switching is not possible in \emph{running} mode, but you can abuse the pagewise mode to produce continuous line numbers. This mode is activated with the command \begin{quote} ~\runningpagewiselinenumbers~ \end{quote} It is not possible to reset the line number counter for this mode, the lines will be numbered starting from one at the beginning of the document, and continue. You can switch back to real pagewise mode with \begin{quote} ~\realpagewiselinenumbers~ \end{quote} but when you resume \emph{running-pagewise}, the numbers will not continue where they left off, but jump by the number of lines that were numbered \emph{real-pagewise}. The package options ~[switch]~ and ~[switch*]~ will turn on \emph{running pagewise} mode with margin switching, unless you also specify ~[pagewise]~. Finally, if you give these options together with ~[running]~, like \begin{quote} ~\usepackage[switch,pagewise,running]{lineno}~ \end{quote} the mode is set to plain \emph{running} line numbers, but later in your document, if you say ~\pagewiselinenumbers~, the setings of the ~[switch]~ and ~[pagewise]~ options will take effect. \subsubsection{Page numbers} Any pages that contain \emph{pagewise} numbered lines must have a different page number. This may cause trouble with titlepages or simmilar fudging with the page number counter in the document. (I am talking about ~\c@page~ or ~\count 0~ here, not ~\thepage~). If you get strange errors, like \emph{``the use of} ~\nextLN~ \emph{does not match its definition''}, you should first delete all ~.aux~ files, and rerun \LaTeX\ several times. If the error does not reappear, fine, else check your page numbers, including those that are not printed. You may use \emph{running} line numbers on your titlepages, since the page boundaries are predefined, usually. \end{pagewiselinenumbers} \begin{linenumbers*} \subsection{Margin selection} In any mode you can select a fixed margin on which the numbers shall be printed. You can either give a package option ~[left]~ or ~[right]~, or change the margin within the document with \begin{quote}\obeylines ~\leftlinenumbers~ \rightlinenumbers ~\rightlinenumbers~ \end{quote} \rightlinenumbers Neither of these commands actually turns on line numbering. The margin setting is changed for the currently selected mode \emph{running} or \emph{pagewise}. If you want to set the margin for both modes, append a star \begin{quote}\obeylines ~\leftlinenumbers*~ ~\rightlinenumbers*~ \end{quote} The default is ~\leftlinenumbers*~. \end{linenumbers*} \subsection{Summary of mode selection commands} The following commands change the major line numbering mode. \begin{description}\itemsep=0pt\parskip=0pt \item [|\setrunninglinenumbers] \item [|\setpagewiselinenumbers] \leavevmode\\ set the current mode, without activating or deactivating line numbering. \item [|\runninglinenumbers\texttt{*[\NL}] \item [|\pagewiselinenumbers] \leavevmode\\ set the current mode and activate line numbering, optionally reset (~*~), or set the line number for \emph{running} mode. \end{description} The following commands do not change the major mode, but modify the the behaviour of \emph{pagewise} mode \begin{description}\itemsep=0pt\parskip=0pt \item [|\realpagewiselinenumbers] \item [|\runningpagewiselinenumbers] \leavevmode\\ select if \emph{pagewise} mode should number continuously, or really pagewise. \end{description} \subsection{Summary of margin selection commands} The following command select into which margin the numbers should be printed \begin{description}\itemsep=0pt\parskip=0pt \item [|\leftlinenumbers\texttt*] \item [|\rightlinenumbers\texttt*] \leavevmode\\ put the line numbers in the left/right margin in both modes. \item [|\leftlinenumbers] \item [|\rightlinenumbers] \leavevmode\\ put the line number into the left/right margin in the currently selected mode. \item [|\switchlinenumbers] \leavevmode\\ put the line numbers into the outer margin, when using \emph{pagewise} mode. \item [|\switchlinenumbers\texttt*] \leavevmode\\ put the line numbers into the inner margin, when using \emph{pagewise} mode. \end{description} \begin{linenumbers*} \modulolinenumbers[2] \subsection{Numbering only one in five lines} You can ask lineno to print the line numbers only if they devide by , by saying \begin{quote} ~\modulolinenumbers[~~]~ \end{quote} If you omit the optional argument, it will be every fifth line, or whatever you used last (the current value of the counter ~linenumbermodulo~). You get the same effect by giving the package option ~[modulo]~. If you set to 1, the modulo value is not changed, but modulo numbering is turned off. Changing the counter ~linenumbermodulo~ does not turn on modulo numbering, it just changes the modulo, if it is turned on without the optional argument. This section of the manual is enclosed in \begin{quote} ~\begin{linenumbers*}~ \\ ~\modulolinenumbers[2]~ ~\end{linenumbers*}~ \end{quote} \end{linenumbers*} \begin{pagewiselinenumbers} \switchlinenumbers \subsection{How the line numbers look like} This section of the manual is enclosed in \begin{quote} ~\begin{pagewiselinenumbers}~ \\ ~\switchlinenumbers~ ~\end{pagewiselinenumbers}~ \end{quote} By default, the line numbers are set in \begin{quote} ~\normalfont\tiny\sffamily~ \end{quote} right justified to 10\,pt left of the nominal left edge of the text. If the number is to appear on the right margin, it is right justified to 20\,pt right of the nominal right edge of the text. You can easily change that, of course. The font is defined by the macro \begin{quote} ~\linenumberfont~ \end{quote} You can redefine it to make the numbers appear in a differnt font (with ~\renewcommand~). I'll say right here in this manual \renewcommand\linenumberfont{\normalfont\bfseries\small} \begin{quote} ~\renewcommand\linenumberfont{\normalfont\bfseries\small}~ \end{quote} The distance on the left margin can be changed with \begin{quote} ~\setlength\linenumbersep{~~}~ \end{quote} The distance on the right margin is ~\linenumbersep~ plus ~\linenumberwidth~, both are set to 10\,pt by default. Let's do right here \setlength\linenumberwidth{1cm} \begin{quote} ~\setlength\linenumbersep{1cm}~ \end{quote} I put the command at the end of the paragraph, but it effects the whole paragraph, because that is where everything happens: at the end of the paragraphs. The line numbers are printed as arabic numerals, as defined in the macro \begin{quote} ~\thelinenumber~ \end{quote} for the \LaTeX\ counter ~{linenumber}~. You can redefine that, as for any other \LaTeX\ counter. E.g., \renewcommand\thelinenumber{\roman{linenumber}} \begin{quote} ~\renewcommand\thelinenumber{\roman{linenumber}}~ \end{quote} (For heavy duty line numbering, you should use \LaTeX s internal format, e.g., ~\@roman\c@linenumber~.) \subsubsection{Deeper customization} The line number is attached to the line by the macro \begin{quote} ~\makeLineNumber~ \end{quote} which is expanded inside a zero width ~\hbox~ alligned to the origin of the current line (left edge, baselines alligned). You can do anything in this macro. Let's assume you do not want line numbers at all, but just attach something else to each line of text: this is the macro to modify. You can refer to the line number by the macro ~\LineNumber~, which prints the current value of the counter ~{linenumber}~, or nothing if \emph{modulo} mode is active, and the number does not divide by ~{linenumbermodulo}~. You should not modify this macro when using any form of \emph{pagewise} mode. At the end of this paragraph I put the following \begin{runninglinenumbers} \renewcommand\makeLineNumber {\hss$\rightarrow$\ \rlap{\hskip\textwidth\ $\leftarrow$}} \end{runninglinenumbers} \begin{quote} ~\begin{runninglinenumbers}~\\ ~\renewcommand\makeLineNumber~\\ ~ {\hss$\rightarrow$\ \rlap{\hskip\textwidth\ $\leftarrow$}}~\\ ~\end{runninglinenumbers}~ \end{quote} Redefining ~\makeLineNumber~ cuts deep into the linenumber mode setting. If you still want to use the basic modes \emph{running} and \emph{pagewise} you should go one level up and modify one of the following macros, which are called by (or assigned to) ~\makeLineNumber~ depending on the current mode, and with the counter ~{linenumber}~ allready adjusted for the current page when using \emph{pagewise} mode. \begin{quote}\obeylines ~\makeLineNumberRunning~ ~\makeLineNumberOdd~ ~\makeLineNumberEven~ \end{quote} The first is used in \emph{running} mode, the other two in \emph{pagewise} mode. If you modify those, you cut into the margin selection mechanism as advertised above. You will have to call a mode selection command after changing these macros, to make them take effect (at least for ~\makeLineNumberRunning~). You can go up one more step. The margin selection commands redefine the above macros by making them equivalent (~\let~) to one of the following macros \begin{quote}\obeylines ~\makeLineNumberLeft~ ~\makeLineNumberRight~ \end{quote} You may redefine these, and afterwards issue a margin selection command followed by a mode selection command. The default definitions are \begin{quote} ~\def\makeLineNumberLeft~\\ ~ {\hss\linenumberfont\LineNumber\hskip\linenumbersep}~ \end{quote} and \begin{quote} ~\def\makeLineNumberRight~\\ ~ {\linenumberfont\hskip\linenumbersep\hskip\textwidth~\\ ~ \hbox to\linenumberwidth{\hss\LineNumber}\hss}~ \end{quote} Whatever you do, use ~\LineNumber~ to print the digits. This ensures that the modulo mode setting is acknowledged. If you want to customize that as well, this is the macro to change. ~\LineNumber~ eventually refers to ~\thelinenumber~, which is the place to customize the numerals themselves. At the end of this paragraph I said \renewcommand\LineNumber{\ifodd\value{linenumber} \thelinenumber)\fi} \begin{quote} ~\renewcommand\LineNumber~\\ ~ {\ifodd\value{linenumber} \thelinenumber)\fi}~ \end{quote} Line number references are not affected by ~\LineNumber~, but you should keep track of ~\thelinenumber~. Look at the following reference \begin{quote} The setion title of the next section is on page \pageref{ll1}, line \ref{ll1}. \end{quote} There is a mismatch in the definition of ~\thelinenumber~, from the point of the refered line to the reference here. \end{pagewiselinenumbers} \begin{pagewiselinenumbers} \section[Line number references] {Line number references\linelabel{ll1}} \lineno.sty allows to refer to a line number with ~\ref{~