diff options
Diffstat (limited to 'obsolete/macros/inrstex/inrsdoc/thauto.tex')
-rw-r--r-- | obsolete/macros/inrstex/inrsdoc/thauto.tex | 379 |
1 files changed, 379 insertions, 0 deletions
diff --git a/obsolete/macros/inrstex/inrsdoc/thauto.tex b/obsolete/macros/inrstex/inrsdoc/thauto.tex new file mode 100644 index 0000000000..f21b5973ce --- /dev/null +++ b/obsolete/macros/inrstex/inrsdoc/thauto.tex @@ -0,0 +1,379 @@ +%-*-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|\auto<type>num| +\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\@|\<type>tagrefformat| +\ext\@|\<type>num| +\ext\@|\<type>tagreplaceformat| +\ext\@|\<type>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{<tag>}| +or |\quietref{<tag>}| and the page number where it occurred by +|\pref{<tag>}| or |\pqref{<tag>}|, 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{<tag>}| and |\pqref{<tag>}| will give an error +if |<tag>| 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{<tag>}{<tagvalue>}| command will +create a tag with the name |<tag>| and the value |<tagvalue>| 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{<tag>}}| will cause the +|\...num| to increment but nothing will be placed in the text. T +his is preferred +to |\silent{<text>}|. +Note that |{\silenttrue <text>}| will normally put the |<text>| 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 +\<type>tagrefformat +\<type>tagreplaceformat +\<type>numform +\endtt +The first governs the format of the initial replacement of the |<tag>| when +it created. The default in |\newautonum{<type>}| is to make it the same as +|\<type>tagrefformat|. The second,|\<type>tagrefformat| is the format for inserting +the tag value when it is actually referred to in the text. +The third |\<type>numform| is set initially equal to +|\the\<type>num|, the value of the counter corresponding to |<type>|. This +may be modified if something other than simple arabic numerals are wanted. +|\newautonum{<type>}| defines +|\<type>tagrefformat| to be equivalent to +``|\Prerefform \<type>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 |\<type>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 +``|<chapter number>.<special number>|''. If +the document has sections but no chapters, and if |\numberbysection| has been +called, the format is ``|<section number>.<special number>|''. The default in +\intex\ is neither of these but is continuous numbering. +This means that the +specials have the form ``|<special number>|'' 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{<tag>}| +\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 (|<num>|). This is provided to reduce the +amount of typing required. The |\aneqtag{<tag>}| also creates a |<tag>| +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{<tag>}| will result in the +|<tagvalue>| being put in the text. A |\pref{<tag>}| will result in the page +number where |<tag>| 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{<tag>}| and |\pref{<tag>}| will result in the +|<tag>| being put in the text. + + +\mbr +\ext\@|\auto<type>num{<tag>}| +\nbr +This is the basic command for incrementing the |<type>| number and creating a +tag for that number with the tag name of |<tag>| 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 [=] {<input command><file name> ...}| +\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 |<token list>| 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{<type>}| +\nbr +This command creates all the necessary commands for using and referring to +the autonumber of |<type>|. The |<type>|s defined by \intex\ are |eq|, |fig|, +and |tbl|, corresponding to equations, figures, and tables respectively. It +is recommended, but not required that |<type>| be restricted to 3 or fewer +characters. This allows for a consistent use of |<type>| 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{<tag>}{<tag value>}| + +\ext\@|\newttag{<tag>}{<tag value>}| + +\ext\@|\newptag{<tag>}| +\nbr +This creates a (normal) tag with reference name |<tag>| and value +|<tag value>| and a page tag with the reference name|<tag>| 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{<text>}|. +|\newttag{<tag>}{<tag value>}| creates and writes a normal tag while +|\newptag{<tag>}| 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{<tag>} \pqref{<tag>}| +\nbr +This is a putting the page number in the text that corresponds to any +|<tag>| +that has been previously +defined. It does not attempt to create a margin note nor does it +check to see if the |<tag>| 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{<tag>} \pref{<tag>}| +\nbr +This is the basic command for inserting the +page number corresponding to any |<tag>| 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{<tag>} \qref{<tag>}| +\nbr +This is a putting the |<tagvalue>| in the text that corresponds to any +|<tag>| +that has been previously +defined. It does not attempt to create a margin note nor does it +check to see if the |<tag>| 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{<tag>}| +\nbr +This is the basic command for inserting the +|<tagvalue>| for any |<tag>| that has been previously +defined. + + +\mbr +\ext\@|\silent{<text>}| +\nbr +This command expands the |<text>| 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{<text>}|. 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 |