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