evergreen-docs:dig_toolset
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
evergreen-docs:dig_toolset [2009/08/12 16:29] – tji | evergreen-docs:dig_toolset [2022/02/10 13:34] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ===== Initial DocBook Tools ===== | ||
+ | |||
+ | Jeremy Buhler, Karen Schneider, Tina Ji | ||
+ | |||
+ | ==== Creating valid DocBook XML files: authoring tools ==== | ||
+ | |||
+ | Basically any text processor that can save plain text files can be used as a DocBook authoring tool. Professional XML editors will help you to write error-free XML documents, validate your XML against a DTD or a schema, and force you to stick to a valid XML structure. | ||
+ | |||
+ | There are numerous XML editors available. Unless otherwise noted the editors below have the following features: | ||
+ | |||
+ | *Add closing tags to your opening tags automatically | ||
+ | *Force you to write valid XML | ||
+ | *Color code or indent your XML syntax | ||
+ | *Verify your XML against DocBook v.5 | ||
+ | *Transformation function | ||
+ | *Multiple views function | ||
+ | |||
+ | |||
+ | === Fee-based: === | ||
+ | |||
+ | |||
+ | [[http:// | ||
+ | |||
+ | [[http:// | ||
+ | |||
+ | [[http:// | ||
+ | |||
+ | |||
+ | === Free: === | ||
+ | |||
+ | |||
+ | [[ http:// | ||
+ | |||
+ | |||
+ | [[ http:// | ||
+ | |||
+ | |||
+ | [[ http:// | ||
+ | |||
+ | |||
+ | [[ http:// | ||
+ | |||
+ | |||
+ | For more DocBook authoring tools, go to [[http:// | ||
+ | |||
+ | |||
+ | ==== Converting Word document to DocBook 5 XML ==== | ||
+ | |||
+ | Many Evergreen community documents (documentation, | ||
+ | |||
+ | There are three options for converting Word to DocBook 5: using brute force (rekeying the documents), using a commercial | ||
+ | |||
+ | |||
+ | The DocBook wiki also maintains a list of [[http:// | ||
+ | |||
+ | === Brute Force Method === | ||
+ | |||
+ | This is sometimes the best way to convert very small documents, especially those that are in types not supported by conversion tools, such as glossaries. | ||
+ | |||
+ | === Using commercial conversion tools === | ||
+ | |||
+ | (Needs description) | ||
+ | |||
+ | |||
+ | === Converting Word to DocBook with OpenOffice === | ||
+ | |||
+ | The Open Office method has a clear cost advantage (where labor is free or low-cost), but the bad news is that the resulting files will be in the DocBook 4 format, and will also be limited to a few tags and document types. The files will require extensive cleanup and reformatting. But it's a start. | ||
+ | |||
+ | |||
+ | ==Step 1: Convert text and layout== | ||
+ | |||
+ | Open the source file (the Word document) in OpenOffice. | ||
+ | |||
+ | This creates a DocBook XML file with the text and general layout of the source. | ||
+ | |||
+ | If you don't need to convert images from the source document, you're done; othwerwise proceed to step 2. | ||
+ | |||
+ | ==Step 2: Extract embedded images== | ||
+ | |||
+ | Much like HTML, DocBook XML files do not have embedded images. | ||
+ | |||
+ | Use //File > Save As// to re-save the source file as type //HTML Document// | ||
+ | |||
+ | The last step is to link the extracted images to the DocBook XML file created in Step 1. Delete the HTML file, rename the image files (optional), then open the DocBook file in an XML or text editor and edit the < | ||
+ | |||
+ | ==== Transforming: | ||
+ | |||
+ | The [[http:// | ||
+ | ==== Formatting output: using CSS ==== | ||
+ | Transformed with the standard XSL stylesheets, | ||
+ | |||
+ | The Evergreen project currently does not have a set of CSS for DocBook. | ||
+ | |||
+ | |||
+ | ===== Setting up DocBook Transforms ===== | ||
+ | If you are using an XML editor that does not have document transformation function, you may set up the transformation process by the following guide. | ||
+ | |||
+ | ==== On Linux ==== | ||
+ | Every Linux distribution seems to ship with different tools for transforming DocBook. It is relatively simple to set up a set of transforms to XHTML and PDF using the standard XSLT stylesheets and FO tools. This guide will get you up and running quickly. | ||
+ | |||
+ | ===Prerequisite=== | ||
+ | We require just one binary package included in your distribution. Every distribution makes the libxslt processor, '' | ||
+ | |||
+ | ===Preparing the build tools=== | ||
+ | In this phase, we download, extract, and create symbolic links to the build tools. You can probably use more recent versions of the tools as they become available. | ||
+ | |||
+ | < | ||
+ | mkdir doctools | ||
+ | cd doctools | ||
+ | |||
+ | # Install the DocBook RelaxNG schema | ||
+ | wget http:// | ||
+ | wget http:// | ||
+ | |||
+ | # Install the DocBook XSL stylesheets | ||
+ | tar xjf docbook-xsl-1.73.2.tar.bz2 | ||
+ | ln -sf docbook-xsl-1.73.2 docbook | ||
+ | |||
+ | # Install Apache FOP | ||
+ | wget http:// | ||
+ | tar xzf fop-0.94-bin-jdk1.4.tar.gz | ||
+ | ln -sf fop-0.94 fop | ||
+ | |||
+ | # Install hypenation support for Apache FOP | ||
+ | wget http:// | ||
+ | unzip offo-hyphenation.zip | ||
+ | </ | ||
+ | |||
+ | ===Generating the XHTML and PDF from a DocBook source file=== | ||
+ | The following is a simple script for generating XHTML and PDF from a DocBook source file. It assumes that your tools are installed in a subdirectory called '' | ||
+ | FOP=~/ | ||
+ | XSL=~/ | ||
+ | DOC=~/ | ||
+ | |||
+ | # Generate XHTML | ||
+ | xsltproc $XSL/ | ||
+ | |||
+ | #Generate PDF via FO | ||
+ | xsltproc $XSL/ | ||
+ | $FOP/fop $DOC/ | ||
+ | </ | ||
+ | |||
+ | ==== On Windows ==== | ||
+ | |||
+ | [[http:// | ||
+ | |||
+ | Some XML processors that run on Windows, such as oXygen ($), automate all or part of the following, and for substantial editorial work in a Windows environment, | ||
+ | |||
+ | === Installing a free Windows-based XSL validator and processor === | ||
+ | |||
+ | Download: | ||
+ | |||
+ | - The latest libxml2 package | ||
+ | - The latest libxslt package | ||
+ | |||
+ | Note: The above packages can be downloaded from http:// | ||
+ | |||
+ | Then on your computer: | ||
+ | |||
+ | - Create a new directory, '' | ||
+ | - Extract the contents of both the libxml2 and libxslt zip files to '' | ||
+ | - Rename the sub-directories to C: | ||
+ | - Open a terminal session and add C: | ||
+ | set PATH=%PATH%; | ||
+ | |||
+ | - Test that XSLT processing tools work: <code dos> | ||
+ | xsltproc --help</ | ||
+ | - If you get a list of options for passing to xsltproc, then everything is set up correctly. | ||
+ | - If you get an error dialog saying "The procedure entry point xmlXPathCompiledEvalToBoolean could not be located in the dynamic link library libxml2.dll" | ||
+ | rename C: | ||
+ | |||
+ | - Download the DocBook XML schema package from http:// | ||
+ | - Extract the contents of the zip file to C: | ||
+ | - Download the DocBook XSL Stylesheet distribution (docbook-xsl) from http:// | ||
+ | - Extract the docbook-xsl ZIP file to C: | ||
+ | - Using the sample XML files you downloaded, test a basic transform: <code dos> | ||
+ | xsltproc C: | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||