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
• Typographic, LaTeX, Etc. Conventions
  • Choice Of Word-Processing Software
  • Nomenclature Of Scopes
  • Number Of Volumes And Organization
  • Mechanisms For Cross-Referencing Across Documents
  • Naming And Usage Conventions
  • Subdirectory Tree Structure

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 $