summaryrefslogtreecommitdiff
path: root/obsolete/macros/inrstex/inrsdoc/thauto.tex
diff options
context:
space:
mode:
Diffstat (limited to 'obsolete/macros/inrstex/inrsdoc/thauto.tex')
-rw-r--r--obsolete/macros/inrstex/inrsdoc/thauto.tex379
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