[svnbook commit] r3035 - trunk/src/en
noreply at red-bean.com
Wed Apr 9 08:13:19 CDT 2008
Date: Wed Apr 9 08:13:19 2008
New Revision: 3035
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
--- 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
+- 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
+ <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
+ <para>This is what that output looks like:</para>
+ $ svn --version --quiet
+ <para>See how concise that was?</para>
+- We keep
- Markup options with aliases like so:
@@ -92,6 +102,22 @@
+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.
@@ -165,7 +191,12 @@
- <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>
+ Except this one.</para>
More information about the svnbook-dev