This style guide is intended to be *an addition to* the O'Reilly and
Associates style guide at http://www.ora.com/oreilly/author/stylesheet.html
===========================================================================


===========
PROSE GUIDE
===========


Tone: somewhere between formal and informal. 
      For example:
      - We use contractions
      - We don't say things like "You see"

- Always title sidebars  

- High level chapter outline: 
  - This is what I'm going to tell you.
  - I'm telling you this *right now*.
  - This is what I told you.

- We have a "Version Control System", NOT a "Revision Control
  System"

- We have "working copies", not "working directories"

- Always use long Subversion commands (e.g. "checkout", not "co", etc)

- We perform "commits"; we don't "check in" or do "checkins"

- They are URL "schemes"; not "schemas".

- Use double-quotes with spaceful command-line arguments instead of single-
  quotes wherever possible, to increase the likelihood of the command
  working on Windows.

- No first-level section should assume that the reader has read any
  other first-level section in the book, unless it explicitly states
  that such an assumption is being made (or rather, recommends that
  the reader first visit said other section).

- Common compound words or phrases we tend to be inconsistent about
  (some of this is redundant with O'Reilly's Word List, some learned via
  the copyedit process):

     datatype (n.)
     logfile (n.)
     out of date (see "up to date")
     out-of-date (see "up-to-date")
     plain-text (adj.)
     up to date (as in, "bring the working copy up to date")
     up-to-date (adj., as is "an up-to-date working copy")
     web site (n.)

================
SUBVERSION GUIDE
================


- ### TODO: Our sample repository will be its own repository that all
  examples come from and it will be publically accessible.

- Primary user: Sally (username "sally")

- Secondary user: Harry (username "harry")

- Tertiary user: Ira (username "ira")

- Primary server machine/URL: svn.red-bean.com


============
MARKUP GUIDE
============


- The book uses the DocBook 4.4 DTD, found in our source tree.

- *Always* validate your XML before committing.  Do not commit XML
  that is not well-formed.  See the README for how to validate your XML.

- We use commented-out divider lines to help us quickly locate section
  boundaries.

- There are some ASCII character sequences and faux characters of
  sorts which are more accurately (and more flexibly) expressed using
  XML entities or UTF-8 characters.  We tend to use the XML entities;
  O'Reilly prefers the UTF-8, where available.  But the
  transformations should be reversible in either case:

       Name            ASCII      XML Tag/Entity     UTF-8
     --------------   -------   ------------------   -----
     apostophe           '            '           ’   ### NOT YET ###
     ellipsis           ...          …          …
     emdash             --           —           —
     double-quotes     "..."    <quote>...</quote>
     minus               -           &minus;           −

  Of course, use the ASCII sequence where it appears literally, such
  as in source code listings and computer output.

- Screen output and program listings should be limited to 78 characters
  in width.  Use backslash ('\') as a line continuation character.

- When referring to the name of binary programs (svn, svnadmin,
  httpd), making a non-specific reference to one of their subcommands,
  use the <command> tag:

     You can create a repository using <command>svnadmin</command>.
     Use the <command>svnadmin create</command> subcommand for this
     purpose.

  But when suggesting inline a particular command-line invocation, use
  <userinput>:

     For example, if you run <userinput>svnadmin create 
     /path/to/repos</userinput>, Subversion will create a new
     repository for you in <filename>/path/to/repos</filename>.

  This policy means you can't use phrases such as "run 'svn switch
  --relocate'".  Why?  Because if a user typed, literally, 'svn switch
  --relocate<Enter>', she'd get an error.  And there's no svn
  subcommand called 'svn switch --relocate'.  To fix this, you need to
  either expand the command-line invocation into something complete:

     Run <userinput>svn switch --relocate <replaceable>FROM-URL</replaceable>
     <replaceable>TO-URL</replaceable></userinput>.

  or embed the option of interest in the surrounding prose:

     Run <command>svn switch</command> with the 
     <option>--relocate</option> option.
     
  Avoid referring to "the svn command" except in contexts where the
  user would literally have run 'svn<Enter>'.  Instead, talk about
  "the <command>svn</command> program".

  Also, avoid referring to "the update subcommand" or "Subversion's
  status command" -- subcommands are specific to particular binary
  programs, and not to Subversion as a whole.  It's better to say "the
  <command>svn update</command> subcommand" and "the <command>svn
  status</command> subcommand".

- Module names like "mod_dav_svn" and "libsvn_ra_neon" are not
  technically <command>s, but we'll use that tag for them (unless they
  are being used in the context of a directory listing or somesuch, in
  which case we'll use <filename> and the full name, "mod_dav_svn.so").
  
- All markup should be properly indented, with the exception of
  <screen> and <programlisting>blocks, which (save for their opening
  tag) should be aligned all the way to the left:

         <para>This is what that output looks like:</para>

         <screen>
     $ svn --version --quiet
     1.5.0-rc1
     $
     </screen>

         <para>See how concise that was?</para>

- Markup options with aliases like so:

     <option>--revision</option> (<option>-r</option>)

  not like:

     <option>--revision (-r)</option>


====================
PRE-PROCESSING NEEDS
====================


Because of the way we've chosen to format our XML (with a goal of
increased readability), there are some pre-processing steps required
to get technically correct formatting of our rendered book contents:

- Any whitespace after a <screen> or <programlisting> tag, up to and
  including the first carriage return, should be removed.

- Whitespace (including carriage returns) before a <footnote> tag and
  after a </footnote> tag should be removed.


==================
ABBREVIATION RULES
==================


- Subcommand names: we always use long names of subcommands,
  e.g. "checkout", not "co".  This goes for both prose and examples.

- Options, not switches: Those --blorg things are called options and
  not switches.  Don't ever call them switches.

- Option names:

    - By default, identify an option by *both* its long and
      short name in the prose, e.g. "use the --revision (-r) option to
      do blah..."

    - For examples (those in <screen> tags, as we as those embedded in
      the prose with <command> tags), use the short version, so as to
      be more realistic and get users comfortable with the
      abbreviations.


=============
MISCELLANEOUS
=============


- Anything that needs attention or fixing should be marked with
  ###TODO so that it's easy to find. Also, please add your userid to
  any inline comments to facilitate discussion 'in the code.'

- Do you want to mention svnbook.el in here?  Note that it's already
  mentioned in the top-level HACKING file.  Maybe this HACKING file
  should be merged into that one?  I dunno, you guys make the call.


==============
SAMPLE CHAPTER
==============


<chapter id="svn-ch-pi">
<title>Tips</title>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-pi-sect-1">
    <title>Flornthorple Plathering</title>
    
    <para>The real key to <firstterm>Plathering</firstterm> is to start with
       a good glab. A good glab provides a solid thorpy foundation.</para>

    <!-- =============================================================== -->
    <sect2 id="svn-ch-pi-sect-1.1">
      <title>Cross-blather</title>
      
      <para>Cross-blather tends to create a hoopy pile of crandy. You
        can avoid this by using cross-blather's <command>cb-avoid</command>
        command:</para>

      <screen>        <!-- We use an EOL here, but technically shouldn't -->
$ cb-avoid
Avoiding blather......... Done
$
</screen>                       <!-- Closing tag at the left-most column -->

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <sect3>
        <title>Exceptions</title>
 
        <para>There's one to every rule.
          <footnote>  <!-- We bring this down, but technically shouldn't -->
            <para>Exception, that is.  Were we talking about inches,
              there would be twelve.</para>
          </footnote>
          Except this one.</para>

      </sect3>

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <sect3>
        <title>Final thoughts</title>
 
        <para>I see a bright light coming toward me&hellip;.</para>

      </sect3>
              
    </sect2>

  </sect1>

</chapter>