[svnbook commit] r3208 - trunk/src/en

[cmpilato]

Author: cmpilato
Date: Fri Jul 25 00:29:07 2008
New Revision: 3208

Log:
Update HACKING with recent guideline additions/enhancements.

Modified:
   trunk/src/en/HACKING

Modified: trunk/src/en/HACKING
==============================================================================
--- trunk/src/en/HACKING	(original)
+++ trunk/src/en/HACKING	Fri Jul 25 00:29:07 2008
@@ -46,16 +46,14 @@
 ================
 
 
-- Our sample repository will be its own repository that all
-  examples come from and it will be publically accessible. ###TODO
+- ### TODO: Our sample repository will be its own repository that all
+  examples come from and it will be publically accessible.
 
-- Primary user: Sally
+- Primary user: Sally (username "sally")
 
-- Secondary user: Harry
+- Secondary user: Harry (username "harry")
 
-- Tertiary user: Ira
-
-- Primary client machine: newyork
+- Tertiary user: Ira (username "ira")
 
 - Primary server machine/URL: svn.red-bean.com
 
@@ -65,19 +63,77 @@
 ============
 
 
+- 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.
 
-- The book is using the DocBook 4.4 DTD, which maybe be found in our
-  source tree.
+- 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>
 
-- You should *always* validate your xml before committing.  Do not
-  commit xml that is not well-formed.  See the README for how to
-  validate your xml.
+  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:
@@ -92,7 +148,6 @@
 
          <para>See how concise that was?</para>
 
-- We keep 
 - Markup options with aliases like so:
 
      <option>--revision</option> (<option>-r</option>)
@@ -176,10 +231,9 @@
     <sect2 id="svn-ch-pi-sect-1.1">
       <title>Cross-blather</title>
       
-      <para>Cross-blather tends to create a hoop
-      y pile of crandy. You
-        can avoid this by using the cross-blather avoid
-        command.</para>
+      <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