bookshop 0.0.3 → 0.0.4

data/CHANGELOG

@@ -1,3 +1,14 @@
+0.0.4:
+		Core Changes
+				Added new mobi build
+				
+				Branding around World Uniting Press
+				
+				Added epubcheck for epub validations, v1.2
+				
+				Added kindlegen for generating mobi
+
+
 0.0.3:
     Core Changes
 				Added Java toolsets, including all necessary .jars for working with Docbook and

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2010, 2011 by D.A. "Dave" Thompson
+Copyright (C) 2010, 2011 by World Uniting (http://worlduniting.org)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.rdoc

@@ -1,6 +1,6 @@
 == Welcome to bookshop
 
-bookshop is an open-source ruby-based development framework for working with DocBook/XSL production flows. The framework is optimized to help developers quickly ramp-up, allowing them to more rapidly jump in and develop their DocBook-to-Output flows, by favoring convention over configuration, setting them up with best practices from the get-go.
+bookShop is an OSS ruby-based framework for docbook toolchain happiness and sustainable productivity. The framework is optimized to help developers quickly ramp-up, allowing them to more rapidly jump in and develop their DocBook-to-Output flows, by favoring convention over configuration, setting them up with best practices from the get-go.
 
 bookshop hopes to simplify the process by:
 * providing a Ruby Gem to make working with DocBook as easy as 'sudo gem install bookshop'
@@ -9,7 +9,11 @@ bookshop hopes to simplify the process by:
 * providing an architecture/structure that follows best-practices and simplification (DRY... Don't Repeat Yourself)
 * providing an extendable framework for other developers to add their own custom templates (and hopefully provide them for the community)
 
-== How to Install
+== Getting Started
+
+Some Useful Links For Docs, Info, Resources to help use use bookshop, or contribute as a developer to this gem.
+
+http://www.delicious.com/blueheadpublishing/bookshop
 
 === System Requirements
 
@@ -19,27 +23,56 @@ bookshop hopes to simplify the process by:
 
 === Install bookshop
 
-<tt>$ sudo gem install bookshop</tt>
+    $ sudo gem install bookshop
 
 === Create a bookshop application
 
-<tt>$ bookshop new ~/Path/to/NewApplication</tt>
+    $ bookshop new name_of_application
+
+	This will create a new bookshop app in /path/to/name_of_application
+	
+* If you can't issue bookshop from your command line, make sure you have included your gems folder in your system $PATH. In unix you can add the following to your .bashrc file in your home folder (this example is for Ubuntu 10.10):
 
-	This will create a new bookshop app in ~/Path/to/NewApplication
+		PATH="$PATH:/var/lib/gems/1.8/bin"
+		export PATH
 
+	
 === Install the java tools. All of the java tools (.jars, etc) can be found in /tools/java/ in the new application.
 
 * For Mac you should copy the contents of /tools/java/ into your system /Library/Java/Extensions or your user ~/Library/Java/Extensions folder. This is the default location for the Java Classpath
 
-* For *nix systems, you can define your classpath by creating a CLASSPATH variable in your .bash_profile (or whatever shell/profile you are using) profile, so:
-
-	CLASSPATH="YOUR_APP_PATH/tools/java/"
+* For *nix systems, you can define your classpath by creating a CLASSPATH variable in your .bashrc (or whatever shell/profile you are using). This example is for Ubuntu 10.10. Make sure to substitute:
+
+		CLASSPATH="/path/to/name_of_application/tools/java/fop.jar:\
+		/path/to/name_of_application/tools/java/avalon-framework-4.2.0.jar:\
+		/path/to/name_of_application/tools/java/xalan.jar:\
+		/path/to/name_of_application/tools/java/batik-all-1.7.jar:\
+		/path/to/name_of_application/tools/java/commons-io-1.3.1.jar:\
+		/path/to/name_of_application/tools/java/commons-logging-1.0.4.jar:\
+		/path/to/name_of_application/tools/java/fop-hyph.jar:\
+		/path/to/name_of_application/tools/java/jai-codec.jar:\
+		/path/to/name_of_application/tools/java/jai_core.jar:\
+		/path/to/name_of_application/tools/java/serializer.jar:\
+		/path/to/name_of_application/tools/java/xercesImpl.jar:\
+		/path/to/name_of_application/tools/java/xml-apis.jar:\
+		/path/to/name_of_application/tools/java/xmlgraphics-commons-1.4.jar"
+		export CLASSPATH
 
 * For Windows systems you can either use Cygwin and follow the directions for *nix systems above, or edit your Classpath via the Control Panel
 
+=== Building Your First Book
+
+To build a pdf format of your book from the docbook source:
+
+    bookshop build pdf
+	
+To build an epub format of your book from the docbook source:
+
+    bookshop build epub
+
 == Getting Help
 
-* Checkout the wiki page which is in development currently for installation help and links to other articles and help content. https://github.com/blueheadpublishing/bookshop/wiki
+* Checkout the wiki page which is in development currently for installation help and links to other articles and help content. https://github.com/worlduniting/bookshop/wiki
 
 * bookshop comes with a built in help feature. Simply run 'bookshop --help' from the command line to get list of possible commands to issue including possible options. You can also run 'bookshop COMMAND --help' (where COMMAND is the command you want) to get a list of possible options for that particular command
 
@@ -73,12 +106,12 @@ The default directory structure of a generated bookshop app:
 	|   |-- epub
 	|   |-- html
 	|   |-- mobi
-			`-- pdf
+	|	  `-- pdf
 	|-- stylesheets
 	|-- tools
-	|		|-- dtd
-	|		|-- xsl
-	|		`-- java
+	|   |-- dtd
+	|   |-- xsl
+	|   `-- java
 
 book
   Holds all the manuscript DocBook code/files. This is where your master manuscript lives from which everything is built.
@@ -106,7 +139,7 @@ tools
 	
 == Copyright (MIT-LICENSE)
 
-Copyright (C) 2010, 2011 by D.A. "Dave" Thompson
+Copyright (C) 2010, 2011 by World Uniting (http://worlduniting.org)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/bookshop.gemspec

@@ -5,16 +5,15 @@ Gem::Specification.new do |s|
   s.name        = "bookshop"
   s.version     = Bookshop::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ['D.A. "Dave" Thompson']
-  s.email       = ['da@blueheadpublishing.com']
+  s.authors     = ['D.a. Thompson']
+  s.email       = ['git@worlduniting.org']
   s.homepage    = "http://rubygems.org/gems/bookshop"
-  s.summary     = "A framework for DocBook toolchain happiness and sustainable productivity."
-  s.description = "bookShop is an open-source ruby-based development framework for working 
-                    with DocBook/XSL tool-chain flows. The framework is optimized to help 
-                    developers quickly ramp-up, allowing them to more rapidly jump in and 
-                    develop their DocBook-to-Output flows, by favoring convention over 
+  s.summary     = "An OSS Ruby-Based Framework for DocBook Toolchain Happiness and Sustainable Productivity."
+  s.description = "bookShop is an OSS ruby-based framework for docbook toolchain happiness and sustainable productivity. 
+                    The framework is optimized to help developers quickly ramp-up, allowing them to more rapidly 
+                    jump in and develop their DocBook-to-Output flows, by favoring convention over 
                     configuration, setting them up with best practices, standards and
-                    tools from the get-go."
+                    tools from the get-go. This gem is brought to you by World Uniting Press, a division of World Uniting."
 
   s.required_rubygems_version = ">= 1.3.6"
   s.rubyforge_project         = "bookshop"

data/lib/bookshop/commands/build.rb

@@ -24,18 +24,79 @@ module Bookshop
       
       case build
       when 'pdf'
-        puts "Deleting your old ebook"
+        puts "Deleting any old builds"
         File.delete("builds/pdf/book.pdf") if File::exists?( "builds/pdf/book.pdf" )
         puts "File Deleted"
         puts "Building new pdf at builds/pdf/book.pdf"
-        cmd = %x[java org.apache.fop.cli.Main -xml book/book.xml -xsl stylesheets/fo-stylesheet.xsl builds/pdf/book.pdf]
+        cmd = %x[java -jar tools/java/fop.jar -xml book/book.xml -xsl stylesheets/fo-stylesheet.xsl builds/pdf/book.pdf]
       
       when 'epub'
-        puts "Deleting your old ebook"
+        puts "Deleting any old builds"
+        File.delete("builds/epub/book.epub") if File::exists?( "builds/epub/book.epub" )
+        puts "File Deleted"
+        
+        puts "Building new epub at builds/epub/book.epub"
+        cmd = %x[tools/xsl/epub/bin/dbtoepub -v book/book.xml -o builds/epub/book.epub]
+        
+        puts "Validating epub"
+        cmd = %x[java -jar tools/java/epubcheck-1.2.jar builds/epub/book.epub]
+
+      
+      # fix this
+      when 'mobi'
+        puts "Deleting any old builds"
+        File.delete("builds/mobi/book.*") if File::exists?( "builds/mobi/book.*" )
+        puts "File Deleted"
+        
+        puts "Building new epub at builds/mobi/book.epub"
+        cmd = %x[tools/xsl/epub/bin/dbtoepub -v book/book.xml -o builds/mobi/book.epub]
+        
+        puts "Validating epub"
+        cmd = %x[java -jar tools/java/epubcheck-1.2.jar builds/mobi/book.epub]
+        
+        puts "Generating mobi file at builds/mobi/book.mobi"
+        cmd = %x[tools/kindle/kindlegen builds/mobi/book.epub]
+        
+        puts "Cleaning up..."
+        File.delete("builds/mobi/book.epub") if File::exists?( "builds/mobi/book.epub" )
+        
+      # to be fixed
+      
+      # when 'html'
+        # puts "Deleting your old html build"
+        # File.delete("builds/html/book.html") if File::exists?( "builds/html/book.html" )
+        # puts "File Deleted"
+        
+        # puts "Building new html at builds/html/book.html"
+        # cmd = %x[java -jar tools/java/xalan.jar -in book/book.xml -xsl stylesheets/html-stylesheet.xsl -out builds/html/book.html]
+        
+      when 'all'        
+        puts "Building pdf..."
+        puts "Deleting any old builds"
+        File.delete("builds/pdf/book.pdf") if File::exists?( "builds/pdf/book.pdf" )
+        puts "File Deleted"
+        puts "Building new pdf at builds/pdf/book.pdf"
+        cmd = %x[java -jar tools/java/fop.jar -xml book/book.xml -xsl stylesheets/fo-stylesheet.xsl builds/pdf/book.pdf]
+
+        puts "Building epub..."
+        puts "Deleting any old builds"
         File.delete("builds/epub/book.epub") if File::exists?( "builds/epub/book.epub" )
         puts "File Deleted"
         puts "Building new pdf at builds/epub/book.epub"
         cmd = %x[tools/xsl/epub/bin/dbtoepub -v book/book.xml -o builds/epub/book.epub]
+
+        puts "Building mobi..."
+        puts "Deleting any old builds"
+        File.delete("builds/mobi/book.*") if File::exists?( "builds/mobi/book.*" )
+        puts "File Deleted"
+        puts "Building new epub at builds/mobi/book.epub"
+        cmd = %x[tools/xsl/epub/bin/dbtoepub -v book/book.xml -o builds/mobi/book.epub]
+        puts "Validating epub"
+        cmd = %x[java -jar tools/java/epubcheck-1.2.jar builds/mobi/book.epub]
+        puts "Generating mobi file at builds/mobi/book.mobi"
+        cmd = %x[tools/kindle/kindlegen builds/mobi/book.epub]
+        puts "Cleaning up..."
+        File.delete("builds/mobi/book.epub") if File::exists?( "builds/mobi/book.epub" )
         
       else
         puts "Error: Command not recognized" unless %w(-h --help).include?(build)
@@ -45,6 +106,8 @@ module Bookshop
       The most common build commands are:
        pdf          Builds a new pdf at /builds/pdf/book.pdf
        epub         Builds a new epub at /builds/epub/book.epub
+       html         Builds a new html at /builds/html/book.html
+       all          Builds all possible builds in their respective locations
 
       All commands can be run with -h for more information.
         EOT

data/lib/bookshop/generators/bookshop/app/app_generator.rb

@@ -12,7 +12,7 @@ module Bookshop
                                         
 
       class_option :dtd,                :type => :string, :aliases => "-dtd",
-                                        :desc => "DTD version [ 4.5, 5.0 ]", :default => "5.0"
+                                        :desc => "DTD version [ 4.5, 5.0 ]", :default => "4.5"
 
       class_option :xsl,                :type => :string, :aliases => "-xsl",
                                         :desc => "DocBook-XSL version [ 1.75.2, 1.76.1 ]", :default => "1.76.1"
@@ -24,11 +24,13 @@ module Bookshop
 
       # Create the project from templates
       def create_base_project
+        puts "creating base project"
         directory "templates", "#{app_path}"
       end
 
       # Adds the dtd specified by user
       def add_dtd
+        puts "creating dtd"
         dtd = "#{options[:dtd]}"
         directory "tools/dtd/#{options[:dtd]}", "#{app_path}/tools/dtd"
       end
@@ -48,6 +50,15 @@ module Bookshop
         directory "tools/java/", "#{app_path}/tools/java"
       end
       
+      # Add the Kindlegen dependencies
+      def add_kindle
+        directory "tools/kindle/", "#{app_path}/tools/kindle"
+      end
+      
+      # Change the permissions so kindlegen is executable 
+      def chmod_kindlegen
+        chmod "#{app_path}/tools/kindle/kindlegen", 0755
+      end
     protected
 
       def self.banner

data/lib/bookshop/generators/bookshop/app/templates/README.rdoc

@@ -1,41 +1,117 @@
-== Welcome to bookShop
+== Welcome to bookshop
 
-bookShop is an open-source ruby-based development framework for working with DocBook/XSL production flows. The framework is optimized to help developers quickly ramp-up, allowing them to more rapidly jump in and develop their DocBook-to-Output flows, by favoring convention over configuration, setting them up with best practices from the get-go.
+bookShop is an OSS ruby-based framework for docbook toolchain happiness and sustainable productivity. The framework is optimized to help developers quickly ramp-up, allowing them to more rapidly jump in and develop their DocBook-to-Output flows, by favoring convention over configuration, setting them up with best practices from the get-go.
 
-bookShop hopes to simplify the process by:
-* providing a Ruby Gem to make working with DocBook as easy as 'sudo gem install bookShop'
-* pulling all the DocBook tools together into one place
+bookshop hopes to simplify the process by:
+* providing a Ruby Gem to make working with DocBook as easy as 'sudo gem install bookshop'
+* pulling all the DocBook tools together into one place (DocBook DTD, XSL Stylesheets, XSLT Processor, XSL-FO Processor)
 * giving the developer a set of scripts to automate the redundant stuff
 * providing an architecture/structure that follows best-practices and simplification (DRY... Don't Repeat Yourself)
 * providing an extendable framework for other developers to add their own custom templates (and hopefully provide them for the community)
 
 == Getting Started
 
-=== Make sure that you have installed the java tools in your Java Classpath. All of the java tools (.jars, etc) can be found in /tools/java/.
+Some Useful Links For Docs, Info, Resources to help use use bookshop, or contribute as a developer to this gem.
 
-* For Mac you should copy the contents of /tools/java/ into you system /Library/Java/Extensions or your user ~/Library/Java/Extensions folder. This is the default location for the Java Classpath
+http://www.delicious.com/blueheadpublishing/bookshop
 
-* For *nix systems, you can define your classpath by creating a CLASSPATH variable in your .bash (or whatever shell you are using) profile, so:
+=== System Requirements
 
-	CLASSPATH="APP_PATH/tools/java/"
+* Ruby v1.8.7 or v1.9.2 http://www.ruby-lang.org/en/downloads/
+* Rubygems v1.3.6 http://docs.rubygems.org/read/chapter/3
+* Java v1.6 http://www.java.com/
 
-* For Windows systems you can either use Cygwin and follow the directions for *nix systems above, or edit your Classpath
+=== Install bookshop
 
-== Description of Contents
+    $ sudo gem install bookshop
 
-The default directory structure of a generated bookShop project:
+=== Create a bookshop application
+
+    $ bookshop new name_of_application
+
+	This will create a new bookshop app in /path/to/name_of_application
+	
+* If you can't issue bookshop from your command line, make sure you have included your gems folder in your system $PATH. In unix you can add the following to your .bashrc file in your home folder (this example is for Ubuntu 10.10):
+
+		PATH="$PATH:/var/lib/gems/1.8/bin"
+		export PATH
+
+	
+=== Install the java tools. All of the java tools (.jars, etc) can be found in /tools/java/ in the new application.
+
+* For Mac you should copy the contents of /tools/java/ into your system /Library/Java/Extensions or your user ~/Library/Java/Extensions folder. This is the default location for the Java Classpath
+
+* For *nix systems, you can define your classpath by creating a CLASSPATH variable in your .bashrc (or whatever shell/profile you are using). This example is for Ubuntu 10.10. Make sure to substitute:
+
+		CLASSPATH="/path/to/name_of_application/tools/java/fop.jar:\
+		/path/to/name_of_application/tools/java/avalon-framework-4.2.0.jar:\
+		/path/to/name_of_application/tools/java/xalan.jar:\
+		/path/to/name_of_application/tools/java/batik-all-1.7.jar:\
+		/path/to/name_of_application/tools/java/commons-io-1.3.1.jar:\
+		/path/to/name_of_application/tools/java/commons-logging-1.0.4.jar:\
+		/path/to/name_of_application/tools/java/fop-hyph.jar:\
+		/path/to/name_of_application/tools/java/jai-codec.jar:\
+		/path/to/name_of_application/tools/java/jai_core.jar:\
+		/path/to/name_of_application/tools/java/serializer.jar:\
+		/path/to/name_of_application/tools/java/xercesImpl.jar:\
+		/path/to/name_of_application/tools/java/xml-apis.jar:\
+		/path/to/name_of_application/tools/java/xmlgraphics-commons-1.4.jar"
+		export CLASSPATH
+
+* For Windows systems you can either use Cygwin and follow the directions for *nix systems above, or edit your Classpath via the Control Panel
+
+=== Building Your First Book
+
+To build a pdf format of your book from the docbook source:
+
+    bookshop build pdf
+	
+To build an epub format of your book from the docbook source:
+
+    bookshop build epub
+
+== Getting Help
+
+* Checkout the wiki page which is in development currently for installation help and links to other articles and help content. https://github.com/blueheadpublishing/bookshop/wiki
+
+* bookshop comes with a built in help feature. Simply run 'bookshop --help' from the command line to get list of possible commands to issue including possible options. You can also run 'bookshop COMMAND --help' (where COMMAND is the command you want) to get a list of possible options for that particular command
+
+== Thanks
+
+We would like to thank:
+
+* The Xerces Team
+* The DocBook Team
+* The Ruby/Rubygems Team
+
+== Description of Gem Contents
+
+The basic bookshop gem architecture:
+
+  |-- bin
+  |-- lib
+
+bin
+	command file copied to /usr/bin upon installation (which is then called from the command line)
+	
+lib
+	bookshop gem library files
+
+== Description of bookshop app contents
+
+The default directory structure of a generated bookshop app:
 
 	|-- book
 	|-- builds
 	|   |-- epub
 	|   |-- html
 	|   |-- mobi
-			`-- pdf
+	|	  `-- pdf
 	|-- stylesheets
 	|-- tools
-	|		|-- dtd
-	|		|-- xsl
-	|		`-- java
+	|   |-- dtd
+	|   |-- xsl
+	|   `-- java
 
 book
   Holds all the manuscript DocBook code/files. This is where your master manuscript lives from which everything is built.
@@ -60,10 +136,10 @@ stylesheets
 	
 tools
 	Holds the DocBook DTD, DocBook-XSL specs and Java tools which serve as the base for building formats. Customization should not happen here, but rather with the stylesheets in the "stylesheets" folder. Files here should remain largely unchanged unless you know what you are doing.
-
+	
 == Copyright (MIT-LICENSE)
 
-Copyright (C) 2010, 2011 by D.A. "Dave" Thompson
+Copyright (C) 2010, 2011 by BlueHead Publishing LLC (http://blueheadpublishing.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/bookshop/generators/bookshop/app/templates/book/book.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book>
+  <title>bookshop</title>
+	<subtitle>the un-ultimate guide to docbook authoring</subtitle>
+
+  <xi:include href="bookinfo.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="ch00.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="ch01.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="ch02.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="ch03.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</book>

data/lib/bookshop/generators/bookshop/app/templates/book/bookinfo.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+  <bookinfo>
+    <!-- All rights reserved. -->
+
+    <edition>1</edition>
+
+    <author>
+      <othername>D.a. Thompson</othername>
+
+      <email>press@worlduniting.org</email>
+    </author>
+
+<!--Markup for downstream formats; not necessary to add at the manuscript phase-->
+<mediaobject id="coverd1e4" role="cover">
+  <imageobject remap="lrg" role="front-large">
+    <imagedata fileref="covers/cover.jpg" format="JPG"/>
+  </imageobject>
+</mediaobject>
+
+  </bookinfo>

data/lib/bookshop/generators/bookshop/app/templates/book/ch00.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<preface>
+  <title>Getting Started</title>
+
+  <para><ulink url="http://docbook.org">DocBook</ulink> is an OASIS standard
+  for XML that is ideal for writing long, technical documents that have
+  complex structure and cross-references. With its semantic tagging, DocBook
+  can be rendered as PDF for printing, HTML, <literal
+  moreinfo="none">man</literal> pages, audio, or even Braille. This
+  versatility and <phrase role="keep-together">reusability</phrase> make
+  DocBook 4.5 XML the preferred format for <phrase
+  role="keep-together">O’Reilly</phrase> books.</para>
+
+  <para id="getting_started">Not only does this document explain how to start
+  writing in DocBook, but it was created using the same markup and toolchain
+  used for a typical O’Reilly book, so you can treat it as a model for your
+  own manuscript. <xref linkend="docbook_xml_markup_guidelines" /> contains
+  information about markup.</para>
+
+  <note>
+    <para>This document exists in two PDF forms: a print-friendly version
+    (<filename>docbookguidelines_print.pdf</filename>), which displays URLs in
+    parentheses after links, and a web-friendly version
+    (<filename>docbookguidelines_web.pdf</filename>), which displays links in
+    blue and hides the URLs. Please be aware that if you print out the
+    web-friendly version, you may not be able to tell where the links are. See
+    <xref linkend="web_pdfs" /> and <xref linkend="inserting_hyperlinks" />
+    for more about web versus print PDFs.</para>
+  </note>
+
+  <sect1>
+    <title>Why DocBook?</title>
+
+    <para>Why not troff? Why not LaTeX?</para>
+
+    <para>We’ve got nothing against LaTeX, troff, or any other formatting
+    markup system. But typesetting markup like LaTeX is inherently focused on
+    formatting—font size, margins, alignment, etc. We’d rather you spend your
+    time focused on the semantic structure of your book (how sections are
+    divided, which information goes in a sidebar versus a note, and so on),
+    and that’s where DocBook shines. In the same way most well-designed
+    websites separate content from formatting using XHTML and CSS (XHTML for
+    the content, and CSS for the formatting), DocBook lets us abstract
+    formatting decisions away from content decisions.</para>
+
+    <?dbfo-need height=”1in”
+?>
+
+    <para>Particularly as O’Reilly expands its efforts to provide content in
+    multiple formats and at multiple stages of the content’s life cycle,
+    cost-effectively generating multiple, distinct output formats from the
+    same source document becomes critical, even though it means losing some
+    degree of granular control over the output.</para>
+
+    <para>What does that mean for your book? It means that you’ll be able to
+    view drafts of your book throughout the authoring process that are
+    formatted much as they will be for print, and it means once your book is
+    finished, it will go live almost immediately on <ulink
+    url="http://my.safaribooksonline.com/?portal=oreilly">Safari Books
+    Online</ulink> and other digital and ebook retail channels, rather than
+    needing to first be converted into DocBook from another format, which can
+    take a week or longer.</para>
+  </sect1>
+
+  <sect1>
+    <title>For More Information on DocBook</title>
+
+    <para>This guide is tailored specifically to help authors get the most out
+    of O’Reilly’s DocBook authoring toolchain. For more general information,
+    see Norm Walsh’s <ulink
+    url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook: The
+    Definitive Guide</ulink>, an excellent online reference for DocBook
+    XML.<footnote>
+        <para>Although we’re publishing <citetitle><ulink
+        role="orm:hideurl:ital"
+        url="http://oreilly.com/catalog/9780596805012">DocBook 5: The
+        Definitive Guide</ulink></citetitle> any minute now, we’re sticking
+        with DocBook 4.5 for the foreseeable future.</para>
+      </footnote> You’ll find <ulink role="orm:hideurl"
+    url="http://www.docbook.org/tdg/en/html/part2.html">reference
+    pages</ulink> for every DocBook element, including its content model, a
+    description of its purpose, a list of parents that can contain the element
+    and children that can be nested in the element, and the attributes the
+    element takes. Other resources that may be helpful include:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><ulink url="http://www.docbook.org/">DocBook.org</ulink></para>
+      </listitem>
+
+      <listitem>
+        <para><ulink
+        url="http://www.dpawson.co.uk/docbook/reference.html">DocBook Basics
+        and References</ulink></para>
+      </listitem>
+
+      <listitem>
+        <para><ulink
+        url="http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">The
+        DocBook DTD</ulink></para>
+      </listitem>
+
+      <listitem>
+        <para><ulink
+        url="http://www.sagehill.net/docbookxsl/index.html">DocBook XSL: The
+        Complete Guide</ulink></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+</preface>