[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