[svnbook] r4419 committed - * en/HACKING...
svnbook at googlecode.com
svnbook at googlecode.com
Fri Feb 8 13:34:31 CST 2013
Revision: 4419
Author: cmpilato at gmail.com
Date: Fri Feb 8 11:34:12 2013
Log: * en/HACKING
Note that we're using DocBook 4.5, and add a section describing how
(and when) index terms are marked up.
http://code.google.com/p/svnbook/source/detail?r=4419
Modified:
/trunk/en/HACKING
=======================================
--- /trunk/en/HACKING Fri Jul 8 12:25:31 2011
+++ /trunk/en/HACKING Fri Feb 8 11:34:12 2013
@@ -75,7 +75,7 @@
============
-- The book uses the DocBook 4.4 DTD, found in our source tree.
+- The book uses the DocBook 4.5 DTD.
- *Always* validate your XML before committing. Do not commit XML
that is not well-formed. See the README for how to validate your XML.
@@ -177,6 +177,63 @@
<option>--revision (-r)</option>
+- Index generation introduces all kinds of fun. Pay attention to the
+ existing index entry, and try to work new items into existing index
+ heirarchies if they fit
+
+ In general, we try to have an <indexterm> for every <firstterm>
+ item, but some <firstterm>s are rather disinteresting outside of the
+ very specific single section in which they are mentioned. For such
+ terms, it's okay to omit an index entry.
+
+ We try to mark up index entries as close to the relevant text as
+ possible, but prefer to anchor to the beginnings of paragraphs,
+ trying to avoid unnecessary whitespace in the primary text flow as
+ much as possible.
+
+ For example:
+
+ [...]
+
+ <para>
+ <indexterm>
+ <primary>copies</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>copy</tertiary>
+ </indexterm>If you wish to copy something in Subversion, you
+ use the <command>svn copy</command> command. This command is
+ [...]
+
+ One exception to this rule is when indexing items in a list. Our
+ processors don't seem to apply a finer granularity to the anchor
+ points beyond "the list", so we clump <indexterm>s at the head of
+ the list:
+
+ [...]
+
+ <variablelist>
+
+ <indexterm>
+ <primary>properties</primary>
+ <secondary>svn:ignore</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>properties</primary>
+ <secondary>svn:keywords</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>properties</primary>
+ <secondary>svn:eol-style</secondary>
+ </indexterm>
+
+ <varlistentry>
+ <term>svn:ignore</term>
+ <listitem>This property causes Subversion to wiggle its
+ [...]
+
====================
PRE-PROCESSING NEEDS
More information about the svnbook-dev
mailing list