[svnbook commit] r3035 - trunk/src/en

cmpilato noreply at red-bean.com
Wed Apr 9 08:13:19 CDT 2008


Author: cmpilato
Date: Wed Apr  9 08:13:19 2008
New Revision: 3035

Log:
Update the HACKING file, adding some notes about how we do things, as well
as a section on what kind of pre-processing is technically required for
correct output.

Modified:
   trunk/src/en/HACKING

Modified: trunk/src/en/HACKING
==============================================================================
--- trunk/src/en/HACKING	(original)
+++ trunk/src/en/HACKING	Wed Apr  9 08:13:19 2008
@@ -65,24 +65,34 @@
 ============
 
 
-- The DTD used for the Subversion book is the Docbook Lite DTD as
-  defined by O'Reilly & Associates. You'll find it at in our source
-  tree and in ftp://ftp.oreilly.com/pub/dblite/
+- 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.
 
-- You should *always* validate your xml before checking in. Do not
-  check in xml that is not well-formed. See the README for how to
+- You should *always* validate your xml before checking in.  Do not
+  check in xml that is not well-formed.  See the README for how to
   validate your xml.
 
 - Screen output and program listings should be limited to 78 characters
   in width.  Use backslash ('\') as a line continuation character.
 
 - All markup should be properly indented, with the exception of
-  <screen></screen> blocks, which should be aligned all the way to the
-  left. 
+  <screen> and <programlisting>blocks, which (save for their opening
+  tag) should be aligned all the way to the left:
 
-- We use commented-out divider lines to help us quickly locate section
-  boundarties.
+         <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>
+
+- We keep 
 - Markup options with aliases like so:
 
      <option>--revision</option> (<option>-r</option>)
@@ -92,6 +102,22 @@
      <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
 ==================
@@ -165,7 +191,12 @@
       <sect3>
         <title>Exceptions</title>
  
-        <para>There's one to every rule.  Except this one.</para>
+        <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>
 




More information about the svnbook-dev mailing list