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> |