ViewVC logotype

Contents of /sf_code/esrgweba/htdocs/devels/uc_sw_bk_auth_collab/auth_info.htm

Parent Directory Parent Directory | Revision Log Revision Log

Revision 23 - (show annotations) (download) (as text)
Sat Oct 8 06:11:57 2016 UTC (7 years, 8 months ago) by dashley
File MIME type: text/html
File size: 17264 byte(s)
Initial commit.
1 <html>
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>
12 <body background="../../bkgnds/bk10.gif">
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 &quot;<i>A
18 Practitioner's Guide To The Design And Development Of Small Microcontroller
19 Software</i>&quot;.</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.&nbsp; 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,&nbsp; 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.&nbsp; (By <i>bindable</i> we mean that the unit can stand alone as something bound by a printer.&nbsp;
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.&nbsp; 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.&nbsp; The
81 way that a chapter is broken into smaller units is at the chapter author's
82 discretion (although we do provide recommendations).&nbsp; To simplify collaboration, each chapter is laid out in its own
83 subdirectory.&nbsp; Authors are free to arrange a chapter's subdirectory
84 hierarchy in any
85 convenient way.&nbsp; Some authors will prefer a monolithic layout, with all necessary
86 files in the chapter's subdirectory.&nbsp; Others will prefer to further organize
87 chapters using child subdirectories in the chapter's subdirectory.&nbsp; 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.&nbsp; (<i>Wish</i> is the Tk shell of the Tcl/Tk scripting
94 language).&nbsp; 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.&nbsp; 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.&nbsp; For this reason,
99 the work is designed so that it can be split into volumes.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; A future improvement planned is to enhance the Wish script to combine the
113 indices of all volumes.&nbsp; The plan is to combine index entries so that the volume
114 tag is included with each page number cited in the index.&nbsp; This will give a full
115 index of all volumes.&nbsp; 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.&nbsp; 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.&nbsp; This information will settle later as the work
121 is presented to a publisher.&nbsp; 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.&nbsp;
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{&lt;name&gt;}</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 &quot;main&quot; LaTeX file for the
144 single-volume work and for each volume of the multi-volume work.&nbsp; The insertion
145 of the <font face="Courier">\usepackage{xr}</font> and <font face="Courier">\externaldocument{&lt;name&gt;}</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>.&nbsp;
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 &quot;<font face="Courier">work</font>&quot;.</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.&nbsp; (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 &quot;.&quot;.</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 &quot;8.3&quot; restriction.</li>
171 <li> All file names must be &quot;typed&quot; (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).&nbsp; However, if such
178 cross-references are eventually needed, labels should begin with &quot;<font face="Courier">vwork</font>&quot;.</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).&nbsp; 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>.&nbsp; 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.&nbsp; This is the main
192 <font face="Courier">.TEX</font>
193 file which is compiled by LaTeX.&nbsp; 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.&nbsp; Each main <font face="Courier">.TEX</font> file is named in accordance
196 with the 4-character volume tag.&nbsp; 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.&nbsp; (They should be cited or alluded to using the commands
201 described below.)&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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 &quot;<i>c_</i>&quot;.&nbsp; For example, the
234 subdirectory containing the chapter on continued fractions is
235 &quot;C_CFR0&quot;.&nbsp; 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.&nbsp; For example, the main <font face="Courier">.TEX</font> file of the
242 continued fractions chapter is
243 named &quot;C_CFR0.TEX&quot;.</li>
244 <li> Like volumes, chapters have corresponding LaTeX commands which are
245 generated automatically by the Wish script.&nbsp; 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.&nbsp; 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.&nbsp; For this reason, the
272 automatically-generated commands include a &quot;xrefhyphen&quot; and &quot;xrefcomma&quot;
273 form which should be used to cite other chapters.&nbsp; For example, if another
274 chapter cites an equation in the &quot;PRI0&quot; 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 &quot;MFR0, &quot; for foreign chapters.&nbsp; This results in the correct cross-reference
280 styles.&nbsp; 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:&nbsp; <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">
293 </body>
295 </html>

ViewVC Help
Powered by ViewVC 1.1.25