diff options
Diffstat (limited to 'info/laan/pwt/pwt.ind')
-rw-r--r-- | info/laan/pwt/pwt.ind | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/info/laan/pwt/pwt.ind b/info/laan/pwt/pwt.ind new file mode 100644 index 0000000000..85508d814d --- /dev/null +++ b/info/laan/pwt/pwt.ind @@ -0,0 +1,506 @@ +\input blue.tex \loadindexmacros \report + + \bluepictures\indmodelpic + +\bluechapter Creating an Index + +\beginsummary +The creation of a modest index within +a one-pass \TeX{} job has been treated. +In general a proof run and a final run are needed. +\endsummary + +Making an index is an art. The fundamental problem is +\bluedisplaycenterline What to include in an index? + +Computer-assisted indexing is not simple either. +Issues are +\bitem the markup of keywords or phrases +\bitem to associate page numbers +\bitem to sort and compress raw Index Reminders (^{IR}s), and +\bitem to typeset the result. +\smallbreak +My approach is to create proof indexes\Dash also called mini-indexes\Dash +for each chapter and +learn from those what should be included in the total index. +I perceived this as very pleasant in practice. +Even if you prefer \cs{makeindex} for the real index, this +processing on the fly of a chapter index can be of great help.\ftn{It is said + that the automatic generation of an index is a feature of the Literate Programming tools. + For LP with \TeX{} as such, as for example Gurari's Pro\TeX, this on-the-fly indexing + within \TeX{} can be used.} + +\bluehead Use + +I'll show how to mark up Knuth's four types of IRs, +how to mark up accents, +how to mark up font switching, and +how to mark up spaces as part of the IR. + +\blueexample Markup, commands and resulting index + +The right column has been obtained via +\bitem ^|\loadindexmacros|, at the beginning of the script +\bitem ^|\sortindex|, at the place of indexing, and +\bitem ^|\pasteupindex|, for the pasteup of + the index. +\smallbreak + \thisverbatim{\catcode`\|=12 + \catcode`!=12 \unmc + \catcode`\*=0 } +\begindemo +Types of IR + 0 ^{return} + 1 ^|verbatim| + 2 ^|\controlsequence| + 3 ^\<syntactic quantity> +Accents ^{\'el\`eve!}, +font changing ^{\bf bold} +and spaces ^{control\ symbol} +Control sequences + ^{\TeX, and \AmSTeX} + ^{Lamport and \LaTeX} +brackets ^{\tt< \rm and \tt>} +\newpage ^{return} +\newpage ^{return}%on purpose +\sortindex\pasteupindex\bye +*yields\obeylines +\quad {\tt {}< \rm {}and \tt {}>}{} {\oldstyle1} +\quad {\bf {}bold}{} {\oldstyle1} +\quad {control\ symbol}{} {\oldstyle1} +\quad {\tt \char 92\hbox {controlsequence}}{} {\oldstyle1} +\quad {\'el\`eve!}{} {\oldstyle1} +\quad {Lamport and \LaTeX{}} {\oldstyle1} +\quad {\TeX, and \AmSTeX{}} {\oldstyle1} +\quad {return}{} {\oldstyle1}--{\oldstyle3} +\quad $\langle \hbox {syntactic\ + quantity}\rangle ${} {\oldstyle1} +\quad {\tt verbatim}{} {\oldstyle1} +\enddemo +The representation of page numbers as a range comes out automatically. + +\exercise What makes a good index? Of course this is a million-dollar + question. Let us concentrate on the number of entries and on the + number of page numbers per entry. Which of the two extremes + sketched below is the better one in your opinion? + One with many entries pointing to issues spread throughout the book\Dash + like \TB{} ;-))), and pushing the limits just for the imagination, + an index with pointers to related work on the internet, accessible + by just clicking the mouse\Dash + or one with few page numbers per entry\ftn{Courtesy Erik Frambach.}? +\answer As usual it all depends on your application. End of answer. + But\Dash there is always a but\Dash the complaint I heard + most about \TB{} was that the information is spread all over, + and that it is hard to find what you are looking for. + Therefore I consider a few page numbers per entry beneficial. + (Let us forget about the intrinsic complexity of the + subject, certainly at the time.) + BLUe's format supports scrutinizing parts of an index, + because it is so easy to generate an index per chapter on the fly. + It is hardly not more difficult than generating a table of contents. + An index per chapter can be scrutinized more easily, and + redundancies removed. + That the index provides a mechanism + to link things over chapters is a good thing, however. + Don't misunderstand me. + But don't overuse it, IMHO, with all respect. Remember DeVinne's + adage `The last thing to learn is simplicity.' + +%end answer + +\bluehead Markup of Index Reminders + +IR-s are at the heart of the process. ^^{IR,\ markup} +Knuth distinguished {\oldstyle4} types to facilitate the outside processing. +I'll adopt his IRs syntax and types. + +\bluesubhead Syntax + +Knuth's IRs obey the following syntax. ^^{IR,\ syntax} +\begincenterverbatim +<word(s)>!]!!<digit>!]<page number>. +!endcenterverbatim +The digits {\oldstyle0}, {\oldstyle1}, {\oldstyle2}, or {\oldstyle3} +denote the types: +words, +verbatim words, +control sequences, and +syntactic quantities. +A user does not have to bother about the digits nor about the +page numbers. +Knuth has adopted the accompanying conventions for +the word(s) of IRs.\ftn{See \TB{} {\oldstyle424}, for the IR types, + and what is typeset in the result. + In \cs{vref} the markup is inserted as replacement + text of \cs{next}. What is set in the index is governed by the macros + which are included after \cs{begindoublecolumns} in the \TeX book script.} +$$\vbox{\offinterlineskip\def\tstrut{\vrule height2.5ex depth.5ex width0pt} +\halign{\tstrut#\hfill\quad\vrule\quad&#\hfill\quad\vrule\quad&#\hfill\cr +Mark up&Typeset in copy$^*$&IR \cr +\noalign{\hrule} +|^{...}| &\dots &|... !!0 |$\langle page\, no\rangle$.\cr +|^!vrt...!vrt| &|!vrt...!vrt|& + |... !!1 |$\langle page\, no\rangle$.\cr +|^!vrt\...!vrt| &|!vrt\...!vrt| & + |... !!2 |$\langle page\, no\rangle$.\cr +|^\<...>|&$\langle\dots\rangle^{**}$& + |... !!3 |$\langle page\, no\rangle$.\cr +\noalign{\vskip.5ex\hrule width1cm\relax\vskip1ex} +\multispan3{\quad$^*\,$\vrt\dots\vrt\ denotes manmac's, TUGboat's,\dots + verbatim \hfil}\cr +\multispan3{\quad$^{**}\,$in \cs{rm} \hfil}\cr +}}$$ +For the user the word(s) is (are) important. +The markup allowed for the IRs and the result in the copy are +given in the accompanying table. + +\bluesubhead Markup + +The markup for IRs is near to natural. +Precede the entry by a circumflex, or a double one in case of +a silent\ftn{Silent IRs mean that these will appear + only in the index, not on the page.} +index entry. + +\blueexample IR markup + +\thisverbatim{\catcode`\|=12 \catcode`\^=12 + \catcode`!=12 \catcode`*=0 \unmc} +\beginverbatim +^{\'el\`eve!}^|verbatim text|^|\controlsequence|^\<a metalinguistic variable> +^^\<a metalinguistic variable> %for silent ones, double the ^ +{\sl^{ligatures}} |'$|^|\,||$''|%from the TeX book script +^^{markup commands, see control sequences} +^{Lamport and \LaTeX} %text and control sequences with sort keys +*endverbatim + +\thissubsubhead{\runintrue} +\bluesubsubhead Spaces \par are difficult as always. ^^{IR\ and\ spaces} +In the IR they separate parts of the IR and are used +in the word part. + +\bitem Just typing a space has as an effect that + it will be neglected during sorting +\bitem The markup `\cs{\char32}', a control space, + will yield a space subject to sorting, according to + the ordering table +\bitem \cs{space} as markup will be neglected during sorting. + This token is default member of + the set of control sequences to be ignored. + It will be set in the index as \cs{\char32}. +\smallbreak + +\exercise What to do when part of a title should reappear in the index? +\answer The naive approach is to enclose that part by braces and precede + it by a circumflex. However, that goes wrong because a title + is stored and reused in many places. So copy the words and + mark them as a silent IR. + +\blueexample Spaces + +\thisverbatim{\catcode`\|=12 } +\begindemo +^{\space}%an ignored cs +^{a\ a} %control space +^{aa} +^{a\ b} +^{a \TeX} +^{a\ \bf a} +^{\TeX book} +^{xyz beta}%space neglected in + %sorting +^{xyza} +^|\space| +\sortindex\pasteupindex\bye +!yields +\noindent Sorted result in file index.srt +\thisverbatim{\catcode`\!=12 + \catcode`\;=0 } +\beginverbatim +\space {} !0 1. +a\ \bf a{} !0 1. +a\ a{} !0 1. +a\ b{} !0 1. +aa{} !0 1. +a \TeX {} !0 1. +space{} !2 1. +\TeX book{} !0 1. +xyza{} !0 1. +xyz beta{} !0 1. +;endverbatim +\enddemo +Explanation. \cs{space} belongs to the set of control sequences +to be ignored, ^^{ignored\ control\ sequences} +ICSs for short. +This means that it is skipped with respect to sorting, +except when it occurs as the last token of the word part. +In that case they are ordered as a space, +i.e., according to the lowest value. +This explains the position of `\cs{space}.' + +`\cs{TeX},' and `\cs{TeX} book,' are subject to the default sorting keys. + +`xyza' precedes `xyz beta,' because the space is silent. +When word ordering is preferred a \cs{\char32}, a control space, must +be included. + +\bluehead Special tokens + +Tokens are either neglected +or replaced by another sequence while sorting. +\bluetex{} provides two sets of tokens to be ignored while sorting: +^|\conseqs| and ^|\consyms|.\ftn{There are two sets because of + the handling of the space after the token in the result.} +Replacing a control sequence by another sequence +is called associating a sorting key to the +control sequence. + +Active symbols can't be part of the IR, for the moment. + +\bluesubhead Tokens to be ignored + +In practice I needed things like \cs{tt} +as part of the IR, which must be neglected while sorting.\ftn{The reason is + that {\tt <, and >} are used, and printed wrongly.} +I decided to ignore those tokens while sorting and to include +the tokens in the final index.elm as such. +Default \bluetex{} knows about the following sets of tokens to be ignored. +\begincenterverbatim +\conseqs{\c\space\bf\it\rm\tt\sub\relax} +\consyms{\`\'\"\^\~} +!endcenterverbatim + +\bluesubhead Sorting keys + +In order to extend a set, use the macro \cs{add}. + +\blueexample Use of sorting keys + +Default \bluetex{} provides the following +sorting keys. +\begincenterverbatim +\srtkeypairs{\AmSTeX{amstex} + \LAMSTeX{lamstex} + \LaTeX{latex} + \TeX{tex} + \PS{PostScript}} +!endcenterverbatim +Suppose that we have \cs{fourtex} and that we like this to be sorted +as `4tex.' +This can be done by extending the set of ^|\srtkeypairs|, ^^|\add| +as follows. +\thisverbatim{\unmc} +\begindemo +\add\fourtex{4tex}to\srtkeypairs +Copy with ^{IR \fourtex} +^{IR 1} +^{IR 5} +^{IR a} +% +\sortindex %with 4tex for \fourtex +\pasteupindex%Set `IR \fourtex{} + %<pagenumbers>' +\bye +!yields +then the file index.srt will contain the IRs +\thisverbatim{\catcode`\!=12 + \catcode`\;=0 } +\beginverbatim +IR 1 !0 <pageno>. +IR \fourtex{} !0 <pageno>. +IR 5 !0 <pageno>. +IR a !0 <pageno>. +;endverbatim +\enddemo +with \cs{fourtex} sorted on 4tex. + +\exercise What to do when `to' is part of the sorting key? +\answer Add an extra level of braces. + + +\bluehead Ordering + +A fundamental issue with indexes is the ordering. ^^{ordering} +The ^{ASCII} table is not suited because lowercase and uppercase +letters differ by 32. I decided to rank these as equal, more +precisely to assign the lowercase ASCII values to both. I prefer +from the accompanying table the {\oldstyle1}$^{st}$ column to the +{\oldstyle2}$^{nd}$ one. + +Moreover, accented letters are not part of ASCII. How should we +order for example e, \'e, \`e, \^e, \"e? +I decided to rank accented letters equal to those without an accent, +because I prefer from the accompanying table +the {\oldstyle3}$^{rd}$ column to the {\oldstyle4}$^{th}$ one. + +I know that non-letters precede letters, but what about their relative +ordering? I decided to stay as close as possible to the ASCII ordering. + +Then there is the problem of digits. In IRs they come as part of the +word(s) and as page numbers. For the latter I used the numerical ordering. +For the former I used the alphabetical ordering.\ftn{I could have applied + a look ahead mechanism and use numerical ordering throughout. + Maybe another time.} + +Furthermore, a user can select +the so-called ^{word\ ordering},\ftn{This means that a space precedes + all letters. A space as such is neglected in the ordering.} +by \cs{\char32}, \TeX nically a control space, as markup for a space. +Personally, I like from the accompanying table +the {\oldstyle5}$^{th}$ column better than the {\oldstyle6}$^{th}$. +\def\btablecaption{} +\def\footer{} +\nonframed +\def\rowstblst{} +$$\def\header{lower vs.\ upper case\cs + accents vs.\ unaccented\cs + word ordering} +\vruled\btable{\vtop{\halign{&\tstrut\quad#\hfil\cr +el & el \cr +El\`eve & em \cr +em & El\`eve \cr}}\cs +\vtop{\halign{&\tstrut\quad#\hfil\cr +el & el \cr +\hbox{\'el\`eve} & em \cr +em & \hbox{\'el\`eve} \cr}} +\cs\vtop{\halign{&\tstrut\quad#\hfil\cr +sea lion & seal \cr +seal & sea lion\cr}} +}%end \btable +$$ + +\bluehead Typesetting the index + +The specifications for typesetting a \bluetex{} index are +\bitem represent the four IR types the same as in the \TeX book +\bitem set in two-columns, balanced, possibly preceded + by one-column copy +\bitem set subsidiary entries analogous to the \TeX book +\bitem indent continuation lines by {\oldstyle2}em +\bitem indent subsidiary entries by {\oldstyle1}em +%\bitem underline page numbers which represent the definition or +% the main source of information +%\bitem represent a page number in italics when that page contains +% an instructive example of the concept in question. +\smallbreak +Users can edit index.elm\Dash read: add markup\Dash and +provide the necessary macros in for example \cs{preindex}. +In short follow Knuth. To please Frans Goddijn I introduced the tag +^|\numberstyle|, by default equal to \cs{oldstyle}. + +\exercise And what about subentries? +\answer My approach is to consider subentries as a typesetting problem in the sense + that the full entries are specified and only when sorted and typeset redundant first + parts can be suppressed, if one considers this better. This is similar to how + BLUe's format system typesets references, inspired by the \AMS. + For the moment I did not implement subentries handling, because as of {\oldstyle1995} + I consider it of low priority. + +\bluehead Customization + +A user might wish to interfere in places +\bitem to include other tokens to be ignored while sorting +\bitem to supply an ordering of his/her own +\bitem to enrich the sorted and compressed file index.elm. +\smallbreak + +\bluesubhead Adding tokens + +What are reasonable requirements to impose upon the handling of +markup control sequences (cs for short)? In my opinion +\bitem the cs must be defined +\bitem ^|\makexref| writes the cs unexpanded +\bitem ordering? unknown, and therefore must be supplied +\bitem ^|\setupnxtokens| guards that the cs-s are written %, unexpanded, + to ^{index.srt} and ^{index.elm}. +\smallbreak +As a consequence I decided to neglect the `in between' +control sequences while sorting. +For those who favour a one-pass job, I have provided the following, +though.\ftn{It is simpler to add those control sequences to + index.elm.} + +The extension of a set of tokens can be done via ^^|\add| +\beginverbatim +\add\hfil to\conseqs or \add\`to\consyms or \add\hfil{hfil}to\srtkeypairs +%with auxiliary \def\add#1to#2{...} +!endverbatim +Each element from \cs{conseqs} is redefined in such a way +that the control sequence token is written to the file +with a space appended.\ftn{\cs{noexpand} is used instead of \cs{string}.} + +\bluesubhead Modifying ordering + +A general way is to `copy' the ordering table +and to modify it.\ftn{My \cs{fifo} is just a shortcut, which also + prevents typos in assigning the ASCII values. For \cs{fifo}, see + my `FIFO and LIFO sing the BLUes.'} + +And what about a macro to add to the table? +This can be done easily, and superficially looks convenient +for an innocent user. +At the moment I don't trust the macros to be worthwhile +for an innocent user, unless a very modest index has to be made. +And this completes the circle: different ordering is not wanted, I guess. + +\bluesubhead The process and files involved + +Like in manmac, \bluetex{} stores the raw IRs in the file index. +^^{IR,\ processes\ and\ files} +The file index^^{index,\ file}\ftn{Default index is the value of + the toks variable ^|\irfile|, which is used in \cs{sortindex}.} +is read and stored in an array for internal sorting. +After sorting, the number of entries is +reduced,\ftn{Those which differ by page + number are collected in one entry.} +and the result is written to the file ^{index.srt}. +Then, index.srt is transformed into the file +index.elm.\ftn{Default ^{index.elm} is the value of the toks variable + ^|\indexfile|, which is used in |\pasteupindex|. + The transformation abandons the IR syntax. + The part which specifies the kind of IR + is deleted and the word part marked up + accordingly.} +The result is typeset via ^|\pasteupindex|. +Schematically it comes down to the following. +\bigskip +$$\vbox{\hsize.5\hsize% +\indmodelpic +}$$ +^|\loadindexmacros| loads the index and sorting macros, and performs +initializations. It is safeguarded against double loading.\ftn{I introduced + this because I start each chapter with \cs{loadindexmacros}, + independent from whether it is run on its own or as part of the total.} + + +\bluesubhead Enriching the index + +This use is necessary when for example ^^{index,\ enrich} +\bitem control sequences have to be typeset +\bitem special symbols are needed, or +\bitem cross-references within the index are required. +\smallbreak +The best way is to start from the ^{index.elm} file. + +\bluesubhead Typesetting the enriched file + +When the default name is used\Dash index.elm\Dash +just say \cs{pasteupindex}. +For another file name assign this name to the toks +variable \cs{indexfile}, +prior to the invocation of \cs{pasteupindex}. + +\bluehead Extras + +Ubdoubtedly people favour their own subset of \TeX, or more likely \LaTeX. +There is good news. You don't have to use BLUe's format system. I gathered the sorting +and indexing stuff as an independent self-contained set in the file plainindex.tpl. + +The bad news is that up till now I did not do much about preventing name clashes. + +\bluesubhead \TeX nical details + +The details with respect to indexing have been treated in `BLUe's Indexes,' and +the sorting aspects have been treated in `Sorting in BLUe,' both available from the CTAN. +\endinput +\bye
\ No newline at end of file |