%-*-tex-*- \ifundefined{writestatus} \input status \relax \fi % \chcode{auto} \marginnotestrue \def\cqu{\cquote{Words are sensible signs necessary for understanding.}{Concerning Human Understanding, Book III, Chap. II, John~Locke (1632-1704)}} \chapterhead{auto}{AUTONUMBERING\cr REFERENCING\cr and TAGGING} \intex\ provides facilities for automatic numbering and referencing of chapters, sections, equations, figures, and tables. Both the number of a chapter, equation, \dots\ and its page may be referenced. In addition there are general features for defining your own special numbers and tags. For instance, it is possible to obtain a new number for, say problem exercises, by just calling |\newautonum{ex}|. This will create all the commands necessary for referencing, resetting, and autoincrementing these numbers. Chapters, sections, subsections, {\it etc}, are also autonumbered and can be referenced through tags. For instance this chapter has the tag |auto|. To insert the value of the tag in the text, it is only necessary to type |\ref{auto}|, which in this case gives \ref{auto} without any extra braces brackets or periods. Details of creating tags for chapters and sections are discussed in Chapter~\ref{shead} starting on page \pref{shead}. \intex\ also supplies facilities for automatically numbering and creating paper or journal citations (sometimes called confusingly, at least here, {\it references}). These are discussed in Chapter \ref{cite}, page \pref{cite}. The facilities for creating lists of tables or figures are found in Chapter \ref{toc} starting on page \pref{toc}\footnote{\dagger}{One must be careful not to overdo an easily used facility.}. \shead{autocomlist}{Command List} \begintwocolumn \ext|\aneq| \ext|\aneqtag| \ext|\autonumberingon| \ext|\autonumberingoff| \ext|\autoreferencingon| \ext|\autoreferencingoff| \ext\@|\autoeqnum| \ext\@|\autotblnum| \ext\@|\autofignum| \ext|\autonum| \ext|\inputtagfiles| \ext|\newautonum| \ext|\newtag| \ext|\numberbychapter| \ext|\numberbysection| \ext|\Prerefform| \ext|\Postrefform| \ext|\pageref \pref| \ext|\pagequietref \pqref| \ext|\pagetagsoff| \ext|\pagetagson| \ext|\quietref \qref| \ext|\ref| \ext|\silent| \ext|\specialnumberscontinuous| \ext\@|\tagrefformat| \ext\@|\num| \ext\@|\tagreplaceformat| \ext\@|\numform| \endthreecolumn \shead{tagcon}{Tagging Conventions} Such items as section heads, equations, figures, and tables may be given symbolic ``tags'' so that references to them will be correct even if there are deletions, insertions, or shufflings. ``Normal'' tags refer to the section, equation, or figure numbers while ``page'' tags refer to the page where the item occurred. Page tags are turned on with the \@|\pagetagson| command and turned off with \@|\pagetagsoff|. The default is |\pagetagsoff|. The tagging system within \intex\ is designed to work best when the autonumbering features are on. It is designed so that both forward and backward references are possible. This is done by saving the tags in a file while \tex\ is processing. The next time the document is processed, the use of the command |\autonumberingon| or |\autoreferencingon| will bring in the latest version of the tag file. As tags are generated, the new definitions and values replace the old ones. When there is a reference to a tag that has not yet been (newly) defined, the old value is used. To guarantee that the tag references are correct, the document should be processed twice. This, of course is only necessary on the ``final'' version. All tags, whether they are for chapters, sections, equations, citations, or specials {\bf must be unique within the entire document}. This allows for the value of a tag, which is usually a number, may be referred to by |\ref{}| or |\quietref{}| and the page number where it occurred by |\pref{}| or |\pqref{}|, no matter the type being tagged. The quiet forms of the refs do not create margin notes and do not check to see if a tag actually exists. Thus both |\qref{}| and |\pqref{}| will give an error if || does not exist. The quiet forms {\bf must} be used inside section heads and are recommended whenever the ref is passed as a parameter to som other command. The tag value does not have any additional brackets or braces around it. For instance, if an equation was given a tag of |theq|, and that was eventually given the value of 2.11 where the first number is the section or chapter and the second is the equation number, then |\ref{theq}| would insert 2.11 into the text. To obtain ``Eq. (2.11)'' in the text it is necessary to type |``Eq. (\ref{theq})''|, the (\dots) being put in explicitly. In almost all instances, the actual tag is generated automatically by the autonumbering forms. However, the |\newtag{}{}| command will create a tag with the name || and the value || for |\ref| and the current page number for |\pref|. Sometimes it is necessary to create the tag {\it silently, ie} without any trace in the text. Although |\newtag| does not insert into the text, |\auto...num| does. The commands \@|{\silenttrue \auto...num{}}| will cause the |\...num| to increment but nothing will be placed in the text. T his is preferred to |\silent{}|. Note that |{\silenttrue }| will normally put the || in the document. \shead{refformats}{Tag Insertion Formats} When a new tag and auto number is created, there are a number of reference forms for that tag that are also created. These are \begintt \tagrefformat \tagreplaceformat \numform \endtt The first governs the format of the initial replacement of the || when it created. The default in |\newautonum{}| is to make it the same as |\tagrefformat|. The second,|\tagrefformat| is the format for inserting the tag value when it is actually referred to in the text. The third |\numform| is set initially equal to |\the\num|, the value of the counter corresponding to ||. This may be modified if something other than simple arabic numerals are wanted. |\newautonum{}| defines |\tagrefformat| to be equivalent to ``|\Prerefform \numform \Postrefform|''. The commands |\Prerefform| and |\Postrefform| are defined by |\numberbysection|, |\numberbychapter| and modified when inside Appendices. \shead{validtag}{Valid Tag Forms} Any character except the following ``|\ $ % & _ ^ { } "| \vrt'' are valid as, and within tags. \shead{numcon}{Numbering Conventions} There are basically two types of autonumbers in \intex, those that deal with chapters, sections, subsections, subsubsections, and appendices, and the {\it special} ones defined for equations, tables, figures, or any created especially for that document. Associated with every autonumber is a {\it count} with the name |\num|. For instance the count associated with equations is |\eqnum| and that with subsections is |\sshnum|. However, when the number is actually inserted into the text, it is not the raw number that is inserted, but rather some formatted version. The formatting appends to the basic count, either nothing, or the numbers corresponding the chapter or section where the number was first created. The actual formatting depends upon what type of numbering format is in force. For instance, for a document with chapters, the ordinary convention is to number the specials as ``|.|''. If the document has sections but no chapters, and if |\numberbysection| has been called, the format is ``|
.|''. The default in \intex\ is neither of these but is continuous numbering. This means that the specials have the form ``||'' and are not reset, except in appendices, throughout the document. Continuous numbering of specials is forced by |\specialnumberscontinuous|. Appendices are treated specially. The specials are reset upon entering an appendix, and the reference formats always include the appendix number. The appendix number is usually an uppercase roman letter, although other formats are possible. \shead{autocomforms}{Command Forms} \beginblockmode \ext\@|\aneq \aneqtag{}| \nbr These commands are specials for use in display math mode to create equation numbers. They increment the equation counter |\eqnum|, and insert either a left or right hand equation number as appropriate, with the equation number {\bf surrounded} by brackets like (||). This is provided to reduce the amount of typing required. The |\aneqtag{}| also creates a || possible reference. \mbr \ext\@|\autonumberingon| \nbr This command turns automatic numbering on. It brings in the tag file with name |\jobname.tag|, if it exists, and opens a new version for writing the tags generated by that \tex\ processing run. The |\jobname| is the file name of the \tex\ file {\bf without} the normal |.tex| extension. No errors will result if this command is called several times. \mbr \ext\@|\autonumberingoff| \nbr This command turns automatic numbering off and closes the tag file. \intex\ defaults to |\autonumberingoff|. \mbr \ext\@|\autoreferencingon| \nbr This command turns automatic referencing on. It brings in the tag file with name |\jobname.tag|, if it exists. A |\ref{}| will result in the || being put in the text. A |\pref{}| will result in the page number where || was last defined being put in the text. No errors will result if this command is called several times. \intex\ defaults to referencing being active but does not automatically bring in a |.tag| file. \mbr \ext\@|\autoreferencingingoff| \nbr This command turns referencing off. Both |\ref{}| and |\pref{}| will result in the || being put in the text. \mbr \ext\@|\autonum{}| \nbr This is the basic command for incrementing the || number and creating a tag for that number with the tag name of || and the tag value of the number in the correct format given the numbering form in force. \intex\ defines three basic types, |eq| for equations, |fig|, for figures, and |tbl| for tables. The tag is written to the |.tag| file. \mbr \ext\@|\inputtagfiles [=] { ...}| \nbr In some cases it may be useful to bring in a file or list of files of tags other than those in |\jobname.tag|. |\inputtagfiles| is a || of commands of the type given. For instance the master file for this book was called |th.tex| while the file for this chapter was called |thauto.tex|. If |\autonumberingon| is called when \tex ing this chapter by itself, the tag file brought in will have the name |thauto.tag|. To use the |th.tag| file it is only necessary to put \begintt \inputtagfiles = {\inputwithcheck{th.tag} } in the chapter file. \endtt \mbr \ext\@|\newautonum{}| \nbr This command creates all the necessary commands for using and referring to the autonumber of ||. The ||s defined by \intex\ are |eq|, |fig|, and |tbl|, corresponding to equations, figures, and tables respectively. It is recommended, but not required that || be restricted to 3 or fewer characters. This allows for a consistent use of || as the extension of list file used for eventually creating a table of items for the table of contents part of a document. For instance, the equation numbering was created with |\newautonum{eq}|. This created the counter |\eqnum|, and the commands |\eqnumform|, |\eqtagreplaceformat|, and |\eqtagrefformat|. Any of these can be changes at will. However, care must be taken if consistent numbering formats is to be maintained. \mbr \ext\@|\newtag{}{}| \ext\@|\newttag{}{}| \ext\@|\newptag{}| \nbr This creates a (normal) tag with reference name || and value || and a page tag with the reference name|| and the current page value. These tags are written out to the |.tag| file if it is open. Page tags will get lost if they are produced inside a box that is never inserted in the text. This occurs for {\bf all} text inside a |\silent{}|. |\newttag{}{}| creates and writes a normal tag while |\newptag{}| creates and writes a page tag. \mbr \ext\@|\numberbychapter| \nbr This command will cause {\it specials} to be reset at the beginning of each new {\bf chapter}, and to append the {\bf chapter} number to any tag reference and to the original tag replacement. \mbr \ext\@|\numberbysection| \nbr This command will cause {\it specials} to be reset at the beginning of each new {\bf section}, and to append the {\bf section} number to any tag reference and to the original tag replacement. \mbr \ext\@|\pagequietref{} \pqref{}| \nbr This is a putting the page number in the text that corresponds to any || that has been previously defined. It does not attempt to create a margin note nor does it check to see if the || is valid. This allows the reference to be used in such places as section heads, titles, captionboxes. In fact it {\bf must} be used in {\bf any} place where the surrounding text is written to a special file or the terminal. Page references {\bf are always from the previous version.} \mbr \ext\@|\pageref{} \pref{}| \nbr This is the basic command for inserting the page number corresponding to any || that has been previously defined. Page references {\bf are always from the previous version.} \mbr \ext\@|\pagetagson \pagetagsoff| \nbr These commands turn page tags on and off respectively. The default is off. It is important to wait until the page containing the item is actually output before turning off page tags. The page tags are actually generated when the page is output \dots\ not before. \mbr \ext\@|\quietref{} \qref{}| \nbr This is a putting the || in the text that corresponds to any || that has been previously defined. It does not attempt to create a margin note nor does it check to see if the || is valid. This allows the reference to be used in such places as section heads, titles, captionboxes. In fact it {\bf must} be used in {\bf any} place where the surrounding text is written to a special file or the terminal. \mbr \ext\@|\ref{}| \nbr This is the basic command for inserting the || for any || that has been previously defined. \mbr \ext\@|\silent{}| \nbr This command expands the || inside a |vbox|, but without ever having it enter the document. This is a way to call out a |\figureinsert| in order to create the normal tags and list files without it actually appearing in the text. {\bf Page tags will not be created in this case.} Note that tags defined inside a |\silent| {\it may} not appear in the margin. The actual mechanism used is |\setbox0 = \vbox{}|. See Chapter~\ref{basbox} for more details on |box| commands. \mbr \ext\@|\specialnumberscontinuous| \nbr This command will prevent the {\it special} numbers from being reset at any point in the document, except appendices. A reference to a {\it special} number tag will result in the value of the appropriate counter with no section or chapter numbers added. {\bf All special numbers are treated the same way.} \endblockmode \ejectpage \marginnotesfalse \done