devels/uc_sw_bk_auth_collab/auth_info.htm

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Information For Authors And Collaborators</title>
<base target="main">
<bgsound src="../../gensounds/as_good_as_it_gets/bettrman.wav" loop="0">
</head>

<body background="../../bkgnds/bk10.gif">

<p align="center"><b><font size="4">Information For Authors And Collaborators</font></b></p>
<hr>
<p>This document contains information for authors and other individuals
collaborating on the book, a work in progress, tentatively entitled &quot;<i>A
Practitioner's Guide To The Design And Development Of Small Microcontroller
Software</i>&quot;.</p>
<hr>
<p><b><u>Bookmarks (To This Page)</u></b></p>
<ul>
  <li><a href="#lic_copyright_info" target="_self">License And Copyright
    Information</a></li>
  <li><a href="#typo_latex_conventions" target="_self">Typographic, LaTeX, Etc.
    Conventions</a>
    <ul>
      <li><a href="#choice_wp_sw" target="_self">Choice Of Word-Processing
        Software</a></li>
      <li><a href="#nom_scopes" target="_self">Nomenclature Of Scopes</a></li>
      <li><a href="#num_vol_org" target="_self">Number Of Volumes And
        Organization</a></li>
      <li><a href="#mech_xref" target="_self">Mechanisms For Cross-Referencing
        Across Documents</a></li>
      <li><a href="#nam_use_conv" target="_self">Naming And Usage Conventions</a></li>
      <li><a href="#sub_tree_struct" target="_self">Subdirectory Tree Structure</a></li>
    </ul>
  </li>
</ul>
<hr>
<p><b><u><a name="lic_copyright_info"></a>License And Copyright Information</u></b></p>
<p>The license for the book is still under construction.&nbsp; The goal is to
phrase the license so that anyone may print or distribute the book, including
for profit, so long as the work is correctly attributed and the copyright is not
transferred.</p>
<hr>
<p align="center"><b><u><a name="typo_latex_conventions"></a><font size="4">Typographic,
LaTeX, Etc. Conventions</font></u></b></p>
<p><b><u><a name="choice_wp_sw"></a>Choice Of Word-Processing Software</u></b></p>
<p>LaTeX was chosen as the word-processing software for this work, for the
following reasons:</p>
<ul>
  <li> Its proven ability to handle very large documents (before beginning
this work,&nbsp; LaTeX was tested to 10,000 pages).</li>
  <li> The heavy mathematical content of much of the subject matter and LaTeX's proven ability to handle complex mathematical equations and typesetting.</li>
  <li>LaTeX's proven ability to handle high-resolution grayscale drawings.</li>
  <li> The ease of translation to .PDF
format for distribution on the Web.</li>
  <li> The scientific bent of most of our potential authors and
contributors---meaning that they would mostly already be LaTeX users.</li>
  <li> The cross-platform nature of LaTeX (it exists on Unix and Linux as
well as Windows platforms).</li>
</ul>
<p><b><u><a name="nom_scopes"></a>Nomenclature Of Scopes</u></b></p>
<p>There are four scopes discussed in this document:</p>
<ul>
  <li> By <i>work</i>, we mean the entire collection of volumes
and supporting materials that comprise this effort.</li>
  <li> By <i>volume</i>, we mean a single bindable unit, compiled as a unit by
    LaTeX, consisting of a collection of
chapters plus title page, introductory information, table of contents, index,
etc.&nbsp; (By <i>bindable</i> we mean that the unit can stand alone as something bound by a printer.&nbsp;
    To stand
alone, it must have a title page, a table of contents, a bibliography, and an
    index.)</li>
  <li> By <i>chapter</i>, we mean a single chapter or appendix
of a volume.&nbsp; As this work is laid out, the chapter is the atomic unit which
receives its own subdirectory and is designed so that it can be easily shifted
between volumes if necessary.</li>
  <li> By <i>subsection</i>, we mean sub-units of a chapter.&nbsp; The
way that a chapter is broken into smaller units is at the chapter author's
    discretion (although we do provide recommendations).&nbsp; To simplify collaboration, each chapter is laid out in its own
subdirectory.&nbsp; Authors are free to arrange a chapter's subdirectory
    hierarchy in any
convenient way.&nbsp; Some authors will prefer a monolithic layout, with all necessary
files in the chapter's subdirectory.&nbsp; Others will prefer to further organize
chapters using child subdirectories in the chapter's subdirectory.&nbsp; Any
organization is acceptable, so long as all chapter contents are contained in the
chapter's subdirectory and its children.</li>
</ul>
<p><b><u><a name="num_vol_org"></a>Number Of Volumes And Organization</u></b></p>
<p>All volumes of this work are generated using <i>Wish</i> or an
equivalent.&nbsp; (<i>Wish</i> is the Tk shell of the Tcl/Tk scripting
language).&nbsp; Wish is used because of the
complexity of the LaTeX compilations--some files must be generated on the
fly, and there are other build complexities that require scripting
automation.&nbsp; The maximum number of pages that can be bound in a book is on the order of
several hundred, and this work could easily exceed that length.&nbsp; For this reason,
the work is designed so that it can be split into volumes.&nbsp; It is logistically
easier to plan for the possibility of multiple volumes from the beginning,
rather than needing to split an existing single-volume work into multiple
volumes without an advance plan.</p>
<p>At the present time, the Wish script compiles a single-volume work, as well
as all volumes of a multi-volume work, re-using the same chapters as input to
both the single-volume work and the multi-volume work.&nbsp; The number of volumes and
the way that chapters are assigned to volumes is controlled by arrays of strings
in the Wish script.&nbsp; The process is nearly fully automatic.</p>
<p>However, the preface, which gives an overview of volumes and chapters, has to
be manually maintained to match the Wish script.&nbsp; This is a minor inconvenience,
and would be very difficult to automate.</p>
<p>At the present time, in the multi-volume work, each volume has a separate
index.&nbsp; A future improvement planned is to enhance the Wish script to combine the
indices of all volumes.&nbsp; The plan is to combine index entries so that the volume
tag is included with each page number cited in the index.&nbsp; This will give a full
index of all volumes.&nbsp; For the single-volume work, this limitation does not
exist, as the index is all-inclusive.</p>
<p>Only the single-volume work will be published on the Web.&nbsp; Readers can print
page ranges, so the length will not be an inconvenience.</p>
<p>The number and titles of volumes and the assignment of chapters to volumes is
not known precisely at this time.&nbsp; This information will settle later as the work
is presented to a publisher.&nbsp; However, the most important attribute of the work
is that it is designed in advance to be split into multiple volumes.</p>
<p>If the conventions outlined in this appendix are followed, the possible split
into multiple volumes should be straightforward and nearly fully automatic
(except for the preface).</p>
<p><b><u><a name="mech_xref"></a>Mechanisms For Cross-Referencing Across
Documents</u></b></p>
<p>David Carlisle's <i>xr</i> package is used to cross-reference across documents.&nbsp;
In practice, this creates a
global <font face="Courier">\label</font> and <font face="Courier">\ref</font> namespace
which spans <i>all</i> volumes, so care must be given to naming conventions to
keep order and prevent naming collisions.</p>
<p>The use of the <i>xr</i> package is straightforward:</p>
<ul>
  <li><font face="Courier">\usepackage{xr}</font> must be specified in the preamble
of each compiled LaTeX volume.</li>
  <li><font face="Courier">\externaldocument{&lt;name&gt;}</font> must appear in
the preamble once for each foreign volume whose symbols are to be imported.</li>
</ul>
<p>The use of <i>xr</i> does require that the entire set of cross-referenced
volumes be compiled at least twice in a round-robin fashion to resolve all
foreign dependencies.</p>
<p>The Wish script automatically generates the &quot;main&quot; LaTeX file for the
single-volume work and for each volume of the multi-volume work.&nbsp; The insertion
of the <font face="Courier">\usepackage{xr}</font> and <font face="Courier">\externaldocument{&lt;name&gt;}</font>
commands is automatic, and is done on the basis of arrays of strings embedded in
the Wish script.</p>
<p><b><u><a name="nam_use_conv"></a>Naming And Usage Conventions</u></b></p>
<p>Naming and usage conventions apply at the <i>work</i> level, at the <i>volume</i>
level, at the <i>chapter</i> level, and optionally at the <i>section</i> level.</p>
<p>Naming conventions at the work level are enumerated below.</p>
<ul>
  <li> Commands, environments, etc. which exist at the <i>work</i> level (are
intended for use everywhere in the work) begin with the string <font face="Courier">\vwork</font>.&nbsp;
    An example of such a string would be <font face="Courier">\vworkrealsetnonneg</font>, which is the notation used throughout the work for
the set of non-negative real numbers.</li>
  <li> Files which contain definitions common to the work and shared sections
common to the work (such as the title page, for example) have a file name
beginning with &quot;<font face="Courier">work</font>&quot;.</li>
  <li> All file names and paths in the work which might be accessed by LaTeX
(including path components) must meet the following conventions.&nbsp; (The reason for these restrictions is that
    LaTeX and some programs which
accompany LaTeX are very old and won't operate if the conventions above are
not followed.)
    <ul>
      <li> No file name or path component may contain a space character or
characters other than underscores, letters, digits, and a single &quot;.&quot;.</li>
      <li> No directory name may contain an extension, or have a name beyond 8
characters.</li>
      <li> All file names must meet the DOS &quot;8.3&quot; restriction.</li>
      <li> All file names must be &quot;typed&quot; (they must have an
        extension, such as .txt, .tex, etc.).</li>
    </ul>
  </li>
  <li> At present, there are no cross-references associated with the <i>work</i>
    scope
(all cross-references are associated with smaller units).&nbsp; However, if such
cross-references are eventually needed, labels should begin with &quot;<font face="Courier">vwork</font>&quot;.</li>
  <li> The entire work is stored in a single subdirectory and its children
(this is necessary to easily burn a CD or to easily compress or copy the entire
work).&nbsp; On PC platforms, this subdirectory is assumed to be <font face="Courier">\esrgubka</font>.</li>
</ul>
<p>Naming and usage conventions at the <i>volume</i> level are
enumerated below.</p>
<ul>
  <li> Each volume is assigned a 4-character tag, which normally [at the
present time] always ends in a digit. (For example, the volume entitled <i>Concepts</i> has the 4-character tag
    <i>CON0</i>.&nbsp; The 4-character tag is the
basis for all of the volume-based naming conventions.</li>
  <li> The Wish script creates a <font face="Courier">.TEX</font> file for each volume, as
dictated by the arrays of strings embedded in the script.&nbsp; This is the main
    <font face="Courier">.TEX</font>
file which is compiled by LaTeX.&nbsp; The Wish script populates each main <font face="Courier">.TEX</font>
file with the necessary <font face="Courier">\input</font> statements to include the
chapters and appendices.&nbsp; Each main <font face="Courier">.TEX</font> file is named in accordance
with the 4-character volume tag.&nbsp; For example, the <i>Concepts</i> volume main
    <font face="Courier">.TEX</font>
file is named <font face="Courier">CON0.TEX</font>.</li>
  <li>No volumes should be directly <i>cited</i> or alluded to except
in the preface.&nbsp; (They should be cited or alluded to using the commands
    described below.)&nbsp; This restriction is necessary to ensure that all chapters
compile both as part of a single-volume work and as part of a multiple-volume
    work and that chapters can be freely moved between volumes.</li>
  <li> To eliminate redundant information, the association between chapters
and volumes (i.e. which chapters are in which volumes) and the numbers and titles of
volumes are specified only in the Wish script.&nbsp; The Wish script, in turn,
populates the main <font face="Courier">.TEX</font> files with this information in the form of
    LaTeX
commands.<br>
    <br>
    For each volume, an information block like the one below is created.<br>
    <br>
    <font face="Courier"> %%%% MFR0: Volume 2: Mathematical Frameworks
And Results %%%%<br>
    \newcommand\vmfrzeroarabic{2} \newcommand\vmfrzeroroman{II}<br>
    \newcommand\vmfrzerotitle{Mathematical
Frameworks And Results}<br>
    \newcommand\vmfrzerocitecomma{MFR0, }<br>
    \newcommand\vmfrzerocitehyphen{MFR0-}</font><br>
    <br>
    In the preface, the automatically-generated LaTeX commands of the form
shown above should be used rather than embedding actual volume numbers or titles
in the preface.&nbsp; This way, changes in the Wish script definitions automatically
propagate to all references.</li>
</ul>
<p>Naming and usage conventions at the <i> chapter</i> level are enumerated below.</p>
<ul>
  <li> Chapters, like volumes, have 4-letter tags which are used as the basis
for naming subdirectories, files, and LaTeX commands generated automatically
by the Wish script.&nbsp; For example, the 4-letter tag of the chapter on
    continued fractions is <i>CFR0</i>.</li>
  <li> Each chapter occupies its own subdirectory, which has a name formed by
prepending the 4-letter chapter tag with &quot;<i>c_</i>&quot;.&nbsp; For example, the
subdirectory containing the chapter on continued fractions is
    &quot;C_CFR0&quot;.&nbsp; It is
at the chapter author's discretion whether to create child subdirectories.
However, all materials for each chapter must be fully contained in a single
subdirectory and its children.</li>
  <li> Within each chapter's subdirectory, the chapter's main <font face="Courier">.TEX</font>
file is named in the same way as the subdirectory, with the <font face="Courier">.TEX</font>
suffix.&nbsp; For example, the main <font face="Courier">.TEX</font> file of the
    continued fractions chapter is
named &quot;C_CFR0.TEX&quot;.</li>
  <li> Like volumes, chapters have corresponding LaTeX commands which are
generated automatically by the Wish script.&nbsp; An example is supplied below.<br>
    <br>
    <font face="Courier" size="2"> %%%% Chapter CPRI0: Integers, Prime Numbers,
And Related Topics %%%%<br>
    \newcommand\cprizerovolarabic{2}<br>
    \newcommand\cprizerovolroman{II}<br>
    \newcommand\cprizerovoltitle{Mathematical Frameworks And Results} \newcommand\cprizeroshorttitle{Integers,
Primes, And Related Topics}<br>
    \newcommand\cprizerotitle{Integers, Prime Numbers,
And Related Topics}<br>
    \newcommand\cprizerolongtitle{Integers, Prime Numbers, And
Related Topics}<br>
    \newcommand\cprizeroxrefhyphen{MFR0-}<br>
    \newcommand\cprizeroxrefcomma{MFR0,
}<br>
    \newcommand\cprizeromcclass{Chapter}<br>
    \newcommand\cprizeroucclass{CHAPTER}<br>
    \newcommand\cprizerolcclass{chapter}<br>
    <br>
    </font>These automatically-generated \LaTeX{} commands should be used to refer to
chapters, rather than embedding chapter names or other information.</li>
  <li> When a chapter refers to something in the same chapter, it can simply
use the <font face="Courier">\ref{}</font> command to directly refer to its own
equations, figures, etc.&nbsp; Any internal reference of this sort will necessarily be in the same
volume.</li>
  <li><p> When a chapter refers to something in another chapter, more caution
must be used, because the chapter may be in another volume.&nbsp; For this reason, the
automatically-generated commands include a &quot;xrefhyphen&quot; and &quot;xrefcomma&quot;
    form which should be used to cite other chapters.&nbsp; For example, if another
chapter cites an equation in the &quot;PRI0&quot; chapter, it should use the
    form:</p>
    <p><font face="Courier">\cprizeroxrefhyphen\ref{eq: ...}</font></p>
<p>The Wish script automatically generates an empty string for
chapters in the same volume as the citing chapter, or else a string such as
&quot;MFR0, &quot; for foreign chapters.&nbsp; This results in the correct cross-reference
styles.&nbsp; Authors are encouraged to consult existing chapters for recommended
cross-referencing styles.</p>
  </li>
</ul>
<p><b><u><a name="sub_tree_struct"></a>Subdirectory Tree Structure</u></b></p>
<p>Need to add a figure here to illustrate the subdirectory structure.</p>
<hr>
<p align="center" style="margin-top: -2; margin-bottom: -1"><font size="1">This
web page is maintained by <a href="mailto:dtashley@users.sourceforge.net">David
T. Ashley</a>.<br>Sound credit:&nbsp; <i>As Good As It Gets</i>.<br>
$Header: /cvsroot/esrg/sfesrg/esrgweba/htdocs/devels/uc_sw_bk_auth_collab/auth_info.htm,v 1.4 2003/05/15 08:12:53 dtashley Exp $</font></p>
<hr noshade size="5">

</body>

</html>
1	dashley	23	<html>
2
3			<head>
4			<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
5			<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
6			<meta name="ProgId" content="FrontPage.Editor.Document">
7			<title>Information For Authors And Collaborators</title>
8			<base target="main">
9			<bgsound src="../../gensounds/as_good_as_it_gets/bettrman.wav" loop="0">
10			</head>
11
12			<body background="../../bkgnds/bk10.gif">
13
14			<p align="center"><b><font size="4">Information For Authors And Collaborators</font></b></p>
15			<hr>
16			<p>This document contains information for authors and other individuals
17			collaborating on the book, a work in progress, tentatively entitled "<i>A
18			Practitioner's Guide To The Design And Development Of Small Microcontroller
19			Software</i>".</p>
20			<hr>
21			<p><b><u>Bookmarks (To This Page)</u></b></p>
22			<ul>
23			<li><a href="#lic_copyright_info" target="_self">License And Copyright
24			Information</a></li>
25			<li><a href="#typo_latex_conventions" target="_self">Typographic, LaTeX, Etc.
26			Conventions</a>
27			<ul>
28			<li><a href="#choice_wp_sw" target="_self">Choice Of Word-Processing
29			Software</a></li>
30			<li><a href="#nom_scopes" target="_self">Nomenclature Of Scopes</a></li>
31			<li><a href="#num_vol_org" target="_self">Number Of Volumes And
32			Organization</a></li>
33			<li><a href="#mech_xref" target="_self">Mechanisms For Cross-Referencing
34			Across Documents</a></li>
35			<li><a href="#nam_use_conv" target="_self">Naming And Usage Conventions</a></li>
36			<li><a href="#sub_tree_struct" target="_self">Subdirectory Tree Structure</a></li>
37			</ul>
38			</li>
39			</ul>
40			<hr>
41			<p><b><u><a name="lic_copyright_info"></a>License And Copyright Information</u></b></p>
42			<p>The license for the book is still under construction.  The goal is to
43			phrase the license so that anyone may print or distribute the book, including
44			for profit, so long as the work is correctly attributed and the copyright is not
45			transferred.</p>
46			<hr>
47			<p align="center"><b><u><a name="typo_latex_conventions"></a><font size="4">Typographic,
48			LaTeX, Etc. Conventions</font></u></b></p>
49			<p><b><u><a name="choice_wp_sw"></a>Choice Of Word-Processing Software</u></b></p>
50			<p>LaTeX was chosen as the word-processing software for this work, for the
51			following reasons:</p>
52			<ul>
53			<li> Its proven ability to handle very large documents (before beginning
54			this work,  LaTeX was tested to 10,000 pages).</li>
55			<li> The heavy mathematical content of much of the subject matter and LaTeX's proven ability to handle complex mathematical equations and typesetting.</li>
56			<li>LaTeX's proven ability to handle high-resolution grayscale drawings.</li>
57			<li> The ease of translation to .PDF
58			format for distribution on the Web.</li>
59			<li> The scientific bent of most of our potential authors and
60			contributors---meaning that they would mostly already be LaTeX users.</li>
61			<li> The cross-platform nature of LaTeX (it exists on Unix and Linux as
62			well as Windows platforms).</li>
63			</ul>
64			<p><b><u><a name="nom_scopes"></a>Nomenclature Of Scopes</u></b></p>
65			<p>There are four scopes discussed in this document:</p>
66			<ul>
67			<li> By <i>work</i>, we mean the entire collection of volumes
68			and supporting materials that comprise this effort.</li>
69			<li> By <i>volume</i>, we mean a single bindable unit, compiled as a unit by
70			LaTeX, consisting of a collection of
71			chapters plus title page, introductory information, table of contents, index,
72			etc.  (By <i>bindable</i> we mean that the unit can stand alone as something bound by a printer.
73			To stand
74			alone, it must have a title page, a table of contents, a bibliography, and an
75			index.)</li>
76			<li> By <i>chapter</i>, we mean a single chapter or appendix
77			of a volume.  As this work is laid out, the chapter is the atomic unit which
78			receives its own subdirectory and is designed so that it can be easily shifted
79			between volumes if necessary.</li>
80			<li> By <i>subsection</i>, we mean sub-units of a chapter.  The
81			way that a chapter is broken into smaller units is at the chapter author's
82			discretion (although we do provide recommendations).  To simplify collaboration, each chapter is laid out in its own
83			subdirectory.  Authors are free to arrange a chapter's subdirectory
84			hierarchy in any
85			convenient way.  Some authors will prefer a monolithic layout, with all necessary
86			files in the chapter's subdirectory.  Others will prefer to further organize
87			chapters using child subdirectories in the chapter's subdirectory.  Any
88			organization is acceptable, so long as all chapter contents are contained in the
89			chapter's subdirectory and its children.</li>
90			</ul>
91			<p><b><u><a name="num_vol_org"></a>Number Of Volumes And Organization</u></b></p>
92			<p>All volumes of this work are generated using <i>Wish</i> or an
93			equivalent.  (<i>Wish</i> is the Tk shell of the Tcl/Tk scripting
94			language).  Wish is used because of the
95			complexity of the LaTeX compilations--some files must be generated on the
96			fly, and there are other build complexities that require scripting
97			automation.  The maximum number of pages that can be bound in a book is on the order of
98			several hundred, and this work could easily exceed that length.  For this reason,
99			the work is designed so that it can be split into volumes.  It is logistically
100			easier to plan for the possibility of multiple volumes from the beginning,
101			rather than needing to split an existing single-volume work into multiple
102			volumes without an advance plan.</p>
103			<p>At the present time, the Wish script compiles a single-volume work, as well
104			as all volumes of a multi-volume work, re-using the same chapters as input to
105			both the single-volume work and the multi-volume work.  The number of volumes and
106			the way that chapters are assigned to volumes is controlled by arrays of strings
107			in the Wish script.  The process is nearly fully automatic.</p>
108			<p>However, the preface, which gives an overview of volumes and chapters, has to
109			be manually maintained to match the Wish script.  This is a minor inconvenience,
110			and would be very difficult to automate.</p>
111			<p>At the present time, in the multi-volume work, each volume has a separate
112			index.  A future improvement planned is to enhance the Wish script to combine the
113			indices of all volumes.  The plan is to combine index entries so that the volume
114			tag is included with each page number cited in the index.  This will give a full
115			index of all volumes.  For the single-volume work, this limitation does not
116			exist, as the index is all-inclusive.</p>
117			<p>Only the single-volume work will be published on the Web.  Readers can print
118			page ranges, so the length will not be an inconvenience.</p>
119			<p>The number and titles of volumes and the assignment of chapters to volumes is
120			not known precisely at this time.  This information will settle later as the work
121			is presented to a publisher.  However, the most important attribute of the work
122			is that it is designed in advance to be split into multiple volumes.</p>
123			<p>If the conventions outlined in this appendix are followed, the possible split
124			into multiple volumes should be straightforward and nearly fully automatic
125			(except for the preface).</p>
126			<p><b><u><a name="mech_xref"></a>Mechanisms For Cross-Referencing Across
127			Documents</u></b></p>
128			<p>David Carlisle's <i>xr</i> package is used to cross-reference across documents.
129			In practice, this creates a
130			global <font face="Courier">\label</font> and <font face="Courier">\ref</font> namespace
131			which spans <i>all</i> volumes, so care must be given to naming conventions to
132			keep order and prevent naming collisions.</p>
133			<p>The use of the <i>xr</i> package is straightforward:</p>
134			<ul>
135			<li><font face="Courier">\usepackage{xr}</font> must be specified in the preamble
136			of each compiled LaTeX volume.</li>
137			<li><font face="Courier">\externaldocument{<name>}</font> must appear in
138			the preamble once for each foreign volume whose symbols are to be imported.</li>
139			</ul>
140			<p>The use of <i>xr</i> does require that the entire set of cross-referenced
141			volumes be compiled at least twice in a round-robin fashion to resolve all
142			foreign dependencies.</p>
143			<p>The Wish script automatically generates the "main" LaTeX file for the
144			single-volume work and for each volume of the multi-volume work.  The insertion
145			of the <font face="Courier">\usepackage{xr}</font> and <font face="Courier">\externaldocument{<name>}</font>
146			commands is automatic, and is done on the basis of arrays of strings embedded in
147			the Wish script.</p>
148			<p><b><u><a name="nam_use_conv"></a>Naming And Usage Conventions</u></b></p>
149			<p>Naming and usage conventions apply at the <i>work</i> level, at the <i>volume</i>
150			level, at the <i>chapter</i> level, and optionally at the <i>section</i> level.</p>
151			<p>Naming conventions at the work level are enumerated below.</p>
152			<ul>
153			<li> Commands, environments, etc. which exist at the <i>work</i> level (are
154			intended for use everywhere in the work) begin with the string <font face="Courier">\vwork</font>.
155			An example of such a string would be <font face="Courier">\vworkrealsetnonneg</font>, which is the notation used throughout the work for
156			the set of non-negative real numbers.</li>
157			<li> Files which contain definitions common to the work and shared sections
158			common to the work (such as the title page, for example) have a file name
159			beginning with "<font face="Courier">work</font>".</li>
160			<li> All file names and paths in the work which might be accessed by LaTeX
161			(including path components) must meet the following conventions.  (The reason for these restrictions is that
162			LaTeX and some programs which
163			accompany LaTeX are very old and won't operate if the conventions above are
164			not followed.)
165			<ul>
166			<li> No file name or path component may contain a space character or
167			characters other than underscores, letters, digits, and a single ".".</li>
168			<li> No directory name may contain an extension, or have a name beyond 8
169			characters.</li>
170			<li> All file names must meet the DOS "8.3" restriction.</li>
171			<li> All file names must be "typed" (they must have an
172			extension, such as .txt, .tex, etc.).</li>
173			</ul>
174			</li>
175			<li> At present, there are no cross-references associated with the <i>work</i>
176			scope
177			(all cross-references are associated with smaller units).  However, if such
178			cross-references are eventually needed, labels should begin with "<font face="Courier">vwork</font>".</li>
179			<li> The entire work is stored in a single subdirectory and its children
180			(this is necessary to easily burn a CD or to easily compress or copy the entire
181			work).  On PC platforms, this subdirectory is assumed to be <font face="Courier">\esrgubka</font>.</li>
182			</ul>
183			<p>Naming and usage conventions at the <i>volume</i> level are
184			enumerated below.</p>
185			<ul>
186			<li> Each volume is assigned a 4-character tag, which normally [at the
187			present time] always ends in a digit. (For example, the volume entitled <i>Concepts</i> has the 4-character tag
188			<i>CON0</i>.  The 4-character tag is the
189			basis for all of the volume-based naming conventions.</li>
190			<li> The Wish script creates a <font face="Courier">.TEX</font> file for each volume, as
191			dictated by the arrays of strings embedded in the script.  This is the main
192			<font face="Courier">.TEX</font>
193			file which is compiled by LaTeX.  The Wish script populates each main <font face="Courier">.TEX</font>
194			file with the necessary <font face="Courier">\input</font> statements to include the
195			chapters and appendices.  Each main <font face="Courier">.TEX</font> file is named in accordance
196			with the 4-character volume tag.  For example, the <i>Concepts</i> volume main
197			<font face="Courier">.TEX</font>
198			file is named <font face="Courier">CON0.TEX</font>.</li>
199			<li>No volumes should be directly <i>cited</i> or alluded to except
200			in the preface.  (They should be cited or alluded to using the commands
201			described below.)  This restriction is necessary to ensure that all chapters
202			compile both as part of a single-volume work and as part of a multiple-volume
203			work and that chapters can be freely moved between volumes.</li>
204			<li> To eliminate redundant information, the association between chapters
205			and volumes (i.e. which chapters are in which volumes) and the numbers and titles of
206			volumes are specified only in the Wish script.  The Wish script, in turn,
207			populates the main <font face="Courier">.TEX</font> files with this information in the form of
208			LaTeX
209			commands.<br>
210			<br>
211			For each volume, an information block like the one below is created.<br>
212			<br>
213			<font face="Courier"> %%%% MFR0: Volume 2: Mathematical Frameworks
214			And Results %%%%<br>
215			\newcommand\vmfrzeroarabic{2} \newcommand\vmfrzeroroman{II}<br>
216			\newcommand\vmfrzerotitle{Mathematical
217			Frameworks And Results}<br>
218			\newcommand\vmfrzerocitecomma{MFR0, }<br>
219			\newcommand\vmfrzerocitehyphen{MFR0-}</font><br>
220			<br>
221			In the preface, the automatically-generated LaTeX commands of the form
222			shown above should be used rather than embedding actual volume numbers or titles
223			in the preface.  This way, changes in the Wish script definitions automatically
224			propagate to all references.</li>
225			</ul>
226			<p>Naming and usage conventions at the <i> chapter</i> level are enumerated below.</p>
227			<ul>
228			<li> Chapters, like volumes, have 4-letter tags which are used as the basis
229			for naming subdirectories, files, and LaTeX commands generated automatically
230			by the Wish script.  For example, the 4-letter tag of the chapter on
231			continued fractions is <i>CFR0</i>.</li>
232			<li> Each chapter occupies its own subdirectory, which has a name formed by
233			prepending the 4-letter chapter tag with "<i>c_</i>".  For example, the
234			subdirectory containing the chapter on continued fractions is
235			"C_CFR0".  It is
236			at the chapter author's discretion whether to create child subdirectories.
237			However, all materials for each chapter must be fully contained in a single
238			subdirectory and its children.</li>
239			<li> Within each chapter's subdirectory, the chapter's main <font face="Courier">.TEX</font>
240			file is named in the same way as the subdirectory, with the <font face="Courier">.TEX</font>
241			suffix.  For example, the main <font face="Courier">.TEX</font> file of the
242			continued fractions chapter is
243			named "C_CFR0.TEX".</li>
244			<li> Like volumes, chapters have corresponding LaTeX commands which are
245			generated automatically by the Wish script.  An example is supplied below.<br>
246			<br>
247			<font face="Courier" size="2"> %%%% Chapter CPRI0: Integers, Prime Numbers,
248			And Related Topics %%%%<br>
249			\newcommand\cprizerovolarabic{2}<br>
250			\newcommand\cprizerovolroman{II}<br>
251			\newcommand\cprizerovoltitle{Mathematical Frameworks And Results} \newcommand\cprizeroshorttitle{Integers,
252			Primes, And Related Topics}<br>
253			\newcommand\cprizerotitle{Integers, Prime Numbers,
254			And Related Topics}<br>
255			\newcommand\cprizerolongtitle{Integers, Prime Numbers, And
256			Related Topics}<br>
257			\newcommand\cprizeroxrefhyphen{MFR0-}<br>
258			\newcommand\cprizeroxrefcomma{MFR0,
259			}<br>
260			\newcommand\cprizeromcclass{Chapter}<br>
261			\newcommand\cprizeroucclass{CHAPTER}<br>
262			\newcommand\cprizerolcclass{chapter}<br>
263			<br>
264			</font>These automatically-generated \LaTeX{} commands should be used to refer to
265			chapters, rather than embedding chapter names or other information.</li>
266			<li> When a chapter refers to something in the same chapter, it can simply
267			use the <font face="Courier">\ref{}</font> command to directly refer to its own
268			equations, figures, etc.  Any internal reference of this sort will necessarily be in the same
269			volume.</li>
270			<li><p> When a chapter refers to something in another chapter, more caution
271			must be used, because the chapter may be in another volume.  For this reason, the
272			automatically-generated commands include a "xrefhyphen" and "xrefcomma"
273			form which should be used to cite other chapters.  For example, if another
274			chapter cites an equation in the "PRI0" chapter, it should use the
275			form:</p>
276			<p><font face="Courier">\cprizeroxrefhyphen\ref{eq: ...}</font></p>
277			<p>The Wish script automatically generates an empty string for
278			chapters in the same volume as the citing chapter, or else a string such as
279			"MFR0, " for foreign chapters.  This results in the correct cross-reference
280			styles.  Authors are encouraged to consult existing chapters for recommended
281			cross-referencing styles.</p>
282			</li>
283			</ul>
284			<p><b><u><a name="sub_tree_struct"></a>Subdirectory Tree Structure</u></b></p>
285			<p>Need to add a figure here to illustrate the subdirectory structure.</p>
286			<hr>
287			<p align="center" style="margin-top: -2; margin-bottom: -1"><font size="1">This
288			web page is maintained by <a href="mailto:dtashley@users.sourceforge.net">David
289			T. Ashley</a>.<br>Sound credit:  <i>As Good As It Gets</i>.<br>
290			$Header: /cvsroot/esrg/sfesrg/esrgweba/htdocs/devels/uc_sw_bk_auth_collab/auth_info.htm,v 1.4 2003/05/15 08:12:53 dtashley Exp $</font></p>
291			<hr noshade size="5">
292
293			</body>
294
295			</html>