Information For Authors And Collaborators
This document contains information for authors and other individuals
collaborating on the book, a work in progress, tentatively entitled "A
Practitioner's Guide To The Design And Development Of Small Microcontroller
Software".
Bookmarks (To This Page)
License And Copyright Information
The license for the book is still under construction. 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.
Typographic,
LaTeX, Etc. Conventions
Choice Of Word-Processing Software
LaTeX was chosen as the word-processing software for this work, for the
following reasons:
- Its proven ability to handle very large documents (before beginning
this work, LaTeX was tested to 10,000 pages).
- The heavy mathematical content of much of the subject matter and LaTeX's proven ability to handle complex mathematical equations and typesetting.
- LaTeX's proven ability to handle high-resolution grayscale drawings.
- The ease of translation to .PDF
format for distribution on the Web.
- The scientific bent of most of our potential authors and
contributors---meaning that they would mostly already be LaTeX users.
- The cross-platform nature of LaTeX (it exists on Unix and Linux as
well as Windows platforms).
Nomenclature Of Scopes
There are four scopes discussed in this document:
- By work, we mean the entire collection of volumes
and supporting materials that comprise this effort.
- By volume, 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. (By bindable we mean that the unit can stand alone as something bound by a printer.
To stand
alone, it must have a title page, a table of contents, a bibliography, and an
index.)
- By chapter, we mean a single chapter or appendix
of a volume. 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.
- By subsection, we mean sub-units of a chapter. The
way that a chapter is broken into smaller units is at the chapter author's
discretion (although we do provide recommendations). To simplify collaboration, each chapter is laid out in its own
subdirectory. Authors are free to arrange a chapter's subdirectory
hierarchy in any
convenient way. Some authors will prefer a monolithic layout, with all necessary
files in the chapter's subdirectory. Others will prefer to further organize
chapters using child subdirectories in the chapter's subdirectory. Any
organization is acceptable, so long as all chapter contents are contained in the
chapter's subdirectory and its children.
Number Of Volumes And Organization
All volumes of this work are generated using Wish or an
equivalent. (Wish is the Tk shell of the Tcl/Tk scripting
language). 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. 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. For this reason,
the work is designed so that it can be split into volumes. 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.
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. The number of volumes and
the way that chapters are assigned to volumes is controlled by arrays of strings
in the Wish script. The process is nearly fully automatic.
However, the preface, which gives an overview of volumes and chapters, has to
be manually maintained to match the Wish script. This is a minor inconvenience,
and would be very difficult to automate.
At the present time, in the multi-volume work, each volume has a separate
index. A future improvement planned is to enhance the Wish script to combine the
indices of all volumes. The plan is to combine index entries so that the volume
tag is included with each page number cited in the index. This will give a full
index of all volumes. For the single-volume work, this limitation does not
exist, as the index is all-inclusive.
Only the single-volume work will be published on the Web. Readers can print
page ranges, so the length will not be an inconvenience.
The number and titles of volumes and the assignment of chapters to volumes is
not known precisely at this time. This information will settle later as the work
is presented to a publisher. However, the most important attribute of the work
is that it is designed in advance to be split into multiple volumes.
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).
Mechanisms For Cross-Referencing Across
Documents
David Carlisle's xr package is used to cross-reference across documents.
In practice, this creates a
global \label and \ref namespace
which spans all volumes, so care must be given to naming conventions to
keep order and prevent naming collisions.
The use of the xr package is straightforward:
- \usepackage{xr} must be specified in the preamble
of each compiled LaTeX volume.
- \externaldocument{<name>} must appear in
the preamble once for each foreign volume whose symbols are to be imported.
The use of xr 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.
The Wish script automatically generates the "main" LaTeX file for the
single-volume work and for each volume of the multi-volume work. The insertion
of the \usepackage{xr} and \externaldocument{<name>}
commands is automatic, and is done on the basis of arrays of strings embedded in
the Wish script.
Naming And Usage Conventions
Naming and usage conventions apply at the work level, at the volume
level, at the chapter level, and optionally at the section level.
Naming conventions at the work level are enumerated below.
- Commands, environments, etc. which exist at the work level (are
intended for use everywhere in the work) begin with the string \vwork.
An example of such a string would be \vworkrealsetnonneg, which is the notation used throughout the work for
the set of non-negative real numbers.
- 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 "work".
- All file names and paths in the work which might be accessed by LaTeX
(including path components) must meet the following conventions. (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.)
- No file name or path component may contain a space character or
characters other than underscores, letters, digits, and a single ".".
- No directory name may contain an extension, or have a name beyond 8
characters.
- All file names must meet the DOS "8.3" restriction.
- All file names must be "typed" (they must have an
extension, such as .txt, .tex, etc.).
- At present, there are no cross-references associated with the work
scope
(all cross-references are associated with smaller units). However, if such
cross-references are eventually needed, labels should begin with "vwork".
- 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). On PC platforms, this subdirectory is assumed to be \esrgubka.
Naming and usage conventions at the volume level are
enumerated below.
- Each volume is assigned a 4-character tag, which normally [at the
present time] always ends in a digit. (For example, the volume entitled Concepts has the 4-character tag
CON0. The 4-character tag is the
basis for all of the volume-based naming conventions.
- The Wish script creates a .TEX file for each volume, as
dictated by the arrays of strings embedded in the script. This is the main
.TEX
file which is compiled by LaTeX. The Wish script populates each main .TEX
file with the necessary \input statements to include the
chapters and appendices. Each main .TEX file is named in accordance
with the 4-character volume tag. For example, the Concepts volume main
.TEX
file is named CON0.TEX.
- No volumes should be directly cited or alluded to except
in the preface. (They should be cited or alluded to using the commands
described below.) 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.
- 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. The Wish script, in turn,
populates the main .TEX files with this information in the form of
LaTeX
commands.
For each volume, an information block like the one below is created.
%%%% MFR0: Volume 2: Mathematical Frameworks
And Results %%%%
\newcommand\vmfrzeroarabic{2} \newcommand\vmfrzeroroman{II}
\newcommand\vmfrzerotitle{Mathematical
Frameworks And Results}
\newcommand\vmfrzerocitecomma{MFR0, }
\newcommand\vmfrzerocitehyphen{MFR0-}
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. This way, changes in the Wish script definitions automatically
propagate to all references.
Naming and usage conventions at the chapter level are enumerated below.
- 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. For example, the 4-letter tag of the chapter on
continued fractions is CFR0.
- Each chapter occupies its own subdirectory, which has a name formed by
prepending the 4-letter chapter tag with "c_". For example, the
subdirectory containing the chapter on continued fractions is
"C_CFR0". 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.
- Within each chapter's subdirectory, the chapter's main .TEX
file is named in the same way as the subdirectory, with the .TEX
suffix. For example, the main .TEX file of the
continued fractions chapter is
named "C_CFR0.TEX".
- Like volumes, chapters have corresponding LaTeX commands which are
generated automatically by the Wish script. An example is supplied below.
%%%% Chapter CPRI0: Integers, Prime Numbers,
And Related Topics %%%%
\newcommand\cprizerovolarabic{2}
\newcommand\cprizerovolroman{II}
\newcommand\cprizerovoltitle{Mathematical Frameworks And Results} \newcommand\cprizeroshorttitle{Integers,
Primes, And Related Topics}
\newcommand\cprizerotitle{Integers, Prime Numbers,
And Related Topics}
\newcommand\cprizerolongtitle{Integers, Prime Numbers, And
Related Topics}
\newcommand\cprizeroxrefhyphen{MFR0-}
\newcommand\cprizeroxrefcomma{MFR0,
}
\newcommand\cprizeromcclass{Chapter}
\newcommand\cprizeroucclass{CHAPTER}
\newcommand\cprizerolcclass{chapter}
These automatically-generated \LaTeX{} commands should be used to refer to
chapters, rather than embedding chapter names or other information.
- When a chapter refers to something in the same chapter, it can simply
use the \ref{} command to directly refer to its own
equations, figures, etc. Any internal reference of this sort will necessarily be in the same
volume.
When a chapter refers to something in another chapter, more caution
must be used, because the chapter may be in another volume. For this reason, the
automatically-generated commands include a "xrefhyphen" and "xrefcomma"
form which should be used to cite other chapters. For example, if another
chapter cites an equation in the "PRI0" chapter, it should use the
form:
\cprizeroxrefhyphen\ref{eq: ...}
The Wish script automatically generates an empty string for
chapters in the same volume as the citing chapter, or else a string such as
"MFR0, " for foreign chapters. This results in the correct cross-reference
styles. Authors are encouraged to consult existing chapters for recommended
cross-referencing styles.
Subdirectory Tree Structure
Need to add a figure here to illustrate the subdirectory structure.
This
web page is maintained by David
T. Ashley.
Sound credit: As Good As It Gets.
$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 $