[svnbook commit] r1228 - trunk/src/en

[maxb]

Author: maxb
Date: Fri Apr 22 06:18:41 2005
New Revision: 1228

Modified:
   trunk/src/en/README
Log:
* en/README: Many edits, including some suggested by Jonathon Mah.


Modified: trunk/src/en/README
==============================================================================
--- trunk/src/en/README	(original)
+++ trunk/src/en/README	Fri Apr 22 06:18:41 2005
@@ -24,20 +24,11 @@
 
   It's very short and clears up many things.
 
-  Note that there are actually two DocBook documents here: The book
-  itself, "Version Control with Subversion", and a miscellaneous
-  holding area known only as the "misc docs" (e.g., misc-docs.pdf,
-  etc).  The Misc Docs hold material that either isn't yet ready to go
-  into the book itself, or which may never go into the book but
-  instead into companion documents that will also be available from
-  the Subversion site.  Think of Misc Docs as a temporary, but
-  published, holding area.
-
 
 II. COMPILING THE DOCS
 
 
-1. Fetch XSL stylesheets for Docbook and place them in src/tools/xsl
+1. Fetch XSL stylesheets for Docbook and place them in src/tools/xsl.
 
    The "Docbook Open Repository" on Sourceforge has a large collection
    of XSL stylesheets that specifically operate on Docbook.  Download
@@ -78,12 +69,12 @@
      If you don't want to compile libxslt, you can just fetch the
      appropriate OS binary package.  
 
-   * From the book directory, do 
+   * From this directory (en, or another language directory), do 
 
-        make all-html
+        $ make all-html
 
      This produces a single-page HTML version of the book in
-     book/book.html, and a multi-page version in book/html-chunk/.
+     book/svn-book.html, and a multi-page version in book/html-chunk/.
 
          
 3. Make a PDF file.
@@ -100,16 +91,16 @@
      installed FOP some other way, that's fine, then you can ignore
      the following recipe:
 
-        1. Download the latest from 
+        1. Download the latest version from 
            http://www.apache.org/dyn/closer.cgi/xml/fop, for example,
-           fop-0.20.4-bin.tar.gz.  Just get a binary distribution,
+           fop-0.20.5-bin.tar.gz.  Just get a binary distribution,
            there's no need for the Java source.
 
         2. Unpack it into src/tools/fop/
 
            $ cd src/tools
            $ tar zxvf fop-0.20.4-bin.tar.gz
-           $ mv fop-0.20.4 fop
+           $ mv fop-0.20.5 fop
 
      That should be enough.  The Makefile will actually invoke
      src/tools/bin/run-fop.sh.  That script attempts to find FOP already
@@ -142,11 +133,11 @@
 
      Poof!  You now have PNG support.
 
-   * From the book directory, do
+   * From this directory (en, or another language directory), do 
 
-        make all-pdf
+        $ make all-pdf
 
-     This produces PDF for the book in book/book.pdf.
+     This produces PDF for the book in book/svn-book.pdf.
 
 
 III. HACKING ON THE DOCS
@@ -172,16 +163,14 @@
 
 2. Get a validating parser.
 
-   We recommend nsgmls, a parser written by James Clark:
-   http://www.jclark.com/sp/.  It's nice to check that the XML
-   you write has matching tags, and follows the DTD correctly.
-
-   Here is one command you can use to validate your xml:
-
-   $ SP_CHARSET_FIXED=YES SP_ENCODING=XML nsgmls -wxml \
-       -mdeclaration/xml.soc -ges                      \
-       /path/to/your/declaration/xml.dcl book.xml
-
+   Actually, if you have what you need to compile the documentation,
+   then you almost certainly have an XML validator installed already -
+   it is called xmllint, and comes as part of libxml2.
+
+   The makefile is preconfigured with a suitable invocation of it,
+   so simply run:
+   
+      $ make valid
 
 
 3. Read about the DocBook lite tags.