From 04619e858364afd7d195d2d63c1ae2156e46b659 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 24 Oct 2010 23:49:44 +0000 Subject: selectp doc (24oct10) git-svn-id: svn://tug.org/texlive/trunk@20185 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/doc/latex/selectp/selectp-doc.pdf | Bin 0 -> 276547 bytes .../texmf-dist/doc/latex/selectp/selectp-doc.tex | 197 +++++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/selectp/selectp-doc.pdf create mode 100644 Master/texmf-dist/doc/latex/selectp/selectp-doc.tex diff --git a/Master/texmf-dist/doc/latex/selectp/selectp-doc.pdf b/Master/texmf-dist/doc/latex/selectp/selectp-doc.pdf new file mode 100644 index 00000000000..bafae6dc583 Binary files /dev/null and b/Master/texmf-dist/doc/latex/selectp/selectp-doc.pdf differ diff --git a/Master/texmf-dist/doc/latex/selectp/selectp-doc.tex b/Master/texmf-dist/doc/latex/selectp/selectp-doc.tex new file mode 100644 index 00000000000..c85c430ceb3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/selectp/selectp-doc.tex @@ -0,0 +1,197 @@ +\documentclass[pagesize=auto, fontsize=12pt]{scrartcl} + +\usepackage{fixltx2e} +\usepackage{etex} +\usepackage{lmodern} +\usepackage[T1]{fontenc} +\usepackage{textcomp} +\usepackage{hologo} +\usepackage{microtype} +\usepackage{hyperref} + +\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}} +\newcommand*{\pkg}[1]{\textsf{#1}} +\newcommand*{\cs}[1]{\texttt{\textbackslash#1}} +\makeatletter +\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}} +\makeatother +\newcommand*{\opt}[1]{\texttt{#1}} +\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle} +\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} +\newcommand*{\outputonly}[1]{\cmd{\outputonly}\texttt{\{#1\}}} + +\addtokomafont{title}{\rmfamily} + +\title{The \pkg{selectp} package\thanks{This manual corresponds to \pkg{selectp}~v1.0, dated~Sept 25, 1992.}} +\subtitle{Select pages for output} +\author{% + Donald Arseneau\thanks{\mail{asnd@triumf.ca}},% + \and based on macros in TUGBoat, 8:2 (1987), p.~217% + \and written by Don Knuth,% + \and and with suggestions from Hossein Saiedian.% +} +\date{Sept 25, 1992} + + +\begin{document} + +\maketitle + + +\section{Instructions} + +This style file defines the command \cmd{\outputonly} which selects specific +pages for output, much as \cmd{\includeonly} selects certain files for input. +To use \pkg{selectp.sty} in \LaTeX, specify \opt{selectp} as one of the document +style options and give the command \cmd{\outputonly}\marg{list of page numbers} +before \verb|\begin{document}|. Only pages given in the list will be output +to the DVI file. For example +% +\begin{verbatim} + \documentstyle[12pt,selectp,subeqn]{article} + \outputonly{1,3, 7-12 16 17} +\end{verbatim} +% +which will allow only pages 1, 3, 7, 8, 9, 10, 11, 12, 16, 17 to be output. +For \hologo{plainTeX}, use \verb|\input{selectp.sty}|. + +The number list should consist of numbers and number ranges (\verb|7-12|, e.\,g.)\ % +separated by commas or spaces. The order is not random but \emph{must be the +order that the pages are produced}; normally this means the numbers must +always increase. If an invalid page number appears on the list, no pages +will be output until the list is re-synchronized or the document ends. + +Any time the document's page number does not increment normally, +\pkg{selectp.sty} tries to re-synchronize the page number with the \cmd{\outputonly} +list of numbers. This is necessary when \cmd{\includeonly} is used. + +Pages that are labeled with roman numerals or letters should still be +listed with a normal arabic number; page~xi should be referred to as~6. + +In \LaTeX, unfortunately, pages~i and~1 are both number~1, so it is +tricky to skip over all the roman-numbered pages and then print +page~1. If there are 3 roman-numbered pages, +% +\begingroup +\addtokomafont{labelinglabel}{\ttfamily} +\begin{labeling}{1-3,8-12} +\item[1-3] + will print pages i, ii, iii; not pages 1, 2, 3 +\item[1-3,1-5] + will print pages i, ii, iii, 1, 2, 3, 4, 5 +\item[1-3,8-12] + will print pages i, ii, iii, 8, 9, 10, 11, 19 +\item[1,1-5] + will print i, 1, 2, 3, 4, 5 +\item[1-6] + prints pages i, ii, iii only, not pages 4, 5, 6 !!! +\item[0,2-6] + prints pages 2, 3, 4, 5, 6, since there is no page~0 and the + \verb|outputonly| page list is resynchronized when the actual page + number goes back to~1) +\end{labeling} +\endgroup +% +The last example is illuminating. \LaTeX\ looks for page~0, but can't find +it. It skips pages until the page number goes from~3~(iii) to~1, at which +point it resynchronizes by reading~\texttt{2} from the list, waiting for page~2 +to be produced, and then writing page~2. Selectp then reads~\texttt{-6}, and +\emph{Continues} outputting pages until it has done page~6. As long as the +numbers of the intervening pages are less than~6 (the end of the range), +those pages will be printed. + +If there are no roman numeral pages, the number list is simple, because +the numbers must increase monotonically. + +\LaTeX\ will not write auxilliary files while selecting output pages, so +the cross references and citations must be correct on the run \emph{before} +using \cmd{\outputonly}. Unfortunately, this means you must produce the +full-size DVI file at least once. + +If multuple \cmd{\outputonly} commands are given, the lists are concatenated. + +In \hologo{plainTeX}, specify roman numeral pages as negative numbers, but do not +use ranges until getting to the ordinary (arabic) page numbers (e.\,g.,\ % +\outputonly{-1,-2,-3,-4, 1-8}). In \hologo{plainTeX} specifying page~1 will \emph{not} +print page~i. + +If a page number in the list is not found, generally no more pages will be +printed. For example, suppose a document has 50~pages, the list \verb*|3 5 910 13| +(which perhaps should read \verb*|9 10|) causes \LaTeX\ to process silently +through the whole document looking for page~910. Only pages~3 and~5 will +be printed. + +\emph{Except} if the number terminating a \emph{range} is not found \verb*|{3 5-910 13}|, +\LaTeX\ continues outputting pages until the end. + +\emph{Except} if the actual page number changes discontinuously, then the number +list \emph{may} be scanned for the next number greater than the new page number. +(Jumps are usually due to the numbering being changed from roman to arabic +with the page reset to~1, or because an included file was skipped due to +an \cmd{\includeonly} command.) The list is scanned if the page number jumps +backward, or if it jumps forward \emph{past} the current target page. (``Target +page'' = the end of the current range or the next number to be printed out, +as appropriate.) + +Numbers must be integers: \texttt{4.3} is illegal, even if some other style file +is generating page numbers in that format. + +\pagebreak[1] + +Of course non-numbers are illegal. Some plausible mistakes: +% +\begin{quote} + \verb|page|, \verb|xvii|, \verb|IV|, \verb|12--16|, \verb|49ff|, \verb|49-|, \verb|5_7|. +\end{quote} +% +\verb|5_7| could be a typo for the range \verb|5-7|. +To specify page~49 and all following (\verb|49ff| or \verb|49-|), use a range +ending with a non-existent page: \verb|49-99999|. +The typo \verb|12--16| prints pages~12 and~16, not the range~12 through~16 as +intended. + + +\section{Examples of use} + +Suppose a document has pages i, ii, iii, iv, v, vi, 1, 2, 3,\dots, 33, but pages +22\dots28 are absent due to \cmd{\includeonly}; here are some examples of valid +uses of \cmd{\outputonly}. +% +\begin{labeling}[\enspace\textendash]{\outputonly{0,4,23-27,31-99}} +\item[\outputonly{15-20}] + prints only the 6 pages 15...20 +\item[\outputonly{1-3}] + prints pages i, ii, iii (in \LaTeX)\\ + \hologo{plainTeX} prints pages 1, 2, 3 +\item[\outputonly{1,1,2}] + prints pages i, 1, 2 +\item[\outputonly{0,1,2}] + prints pages 1, 2 +\item[\outputonly{1,3-6}] + prints pages i, iii, iv, v, vi +\item[\outputonly{4,3-6}] + prints pages iv, 3, 4, 5, 6 +\item[\outputonly{5,2}] + prints pages v, 2 +\item[\outputonly{5-2}] + prints only page v only! +\item[\outputonly{5-7}] + prints pages v, vi only! +\item[\outputonly{1-33}] + prints pages i, ii, iii, iv, v, vi only! +\item[\outputonly{29-99}] + prints pages 29, 30, 31, 32, 33 +\item[\outputonly{19-99}] + prints pages 19, 20, 21, 29, 30, 31, 32, 33 +\item[\outputonly{24-32}] + prints pages 29, 30, 31, 32 +\item[\outputonly{15-25,32}] + prints pages 15, 16, 17, 18, 19, 20, 21, 32 +\item[\outputonly{0,4,23-27,31-99}] + prints pages 4, 31, 32, 33 +\end{labeling} + +Version 0.9 (test), Sept 25, 1992: +Send problem reports to \mail{asnd@triumf.ca} + +\end{document} -- cgit v1.2.3