特殊:Badtitle/NS100:DocBook:修订间差异

来自Ubuntu中文
跳到导航跳到搜索
Wikibot留言 | 贡献
无编辑摘要
Wikibot留言 | 贡献
无编辑摘要
 
第4行: 第4行:
The purpose of this page is to give an overview of the DocBook format. It offers an explanation of the advantages of this format, links further reading on this subject and contains a short tutorial.
The purpose of this page is to give an overview of the DocBook format. It offers an explanation of the advantages of this format, links further reading on this subject and contains a short tutorial.
=== What is DocBook? ===
=== What is DocBook? ===
DocBook is an XML based standard, which is used in many of todays documentation tasks. Practically speaking, when you want to create a DocBook document source, you write XML files which describe the documents layout, paragraph division and other attributes. XML file structure may look familiar to you if you have seen HTML code before. XML tends to be an improvment over the older HTML specification and can be used to produce complete web pages and other markup documents.
DocBook is an XML based standard, which is used in many of today's documentation tasks. When you want to create a DocBook document source, you write XML files which describe the document layout, paragraph division and other attributes. XML file structure may look familiar to you if you have seen HTML code before. XML tends to be an improvement over the older HTML specification and can be used to produce complete web pages and other markup documents.
=== What are the Advantages of Docbook? ===
=== What are the Advantages of DocBook? ===
Docbook is an OASIS standard and the format in which most open source projects store their documentation. Docbook is developed as an open source application. The project is hosted at Source''''''Forge and is made available under the GPL. Docbook is available as a Document Type Definition (DTD) and XML Schema (XSD). The project has a large developer and support community spanning both open source and commercial groups.
DocBook is an OASIS standard and the format in which most open source projects store their documentation. Docbook is developed as an open source application. The project is hosted at Source''''''Forge and is made available under the GPL. DocBook is available as a Document Type Definition (DTD) and XML Schema (XSD). The project has a large developer and support community spanning both open source and commercial groups.
The most important reasons why the project uses Docbook include:
The most important reasons why the project uses DocBook include:
<ol><li>Docbook is a standard
<ol><li>DocBook is a standard
</li><li>Docbook is open source
</li><li>DocBook is open source
</li><li>Docbook is used by most major projects
</li><li>DocBook is used by most major projects
</li><li>Docbook has a large developer and support community</li></ol>
</li><li>DocBook has a large developer and support community</li></ol>


Docbook is also an XML application and XML technologies solve a number of publishing problems for documentation teams, including:
DocBook is also an XML application and XML technologies solve a number of publishing problems for documentation teams, including:
* Single-sourcing
* Single-sourcing
* Collaborative authoring
* Collaborative authoring
第22行: 第22行:
* Negating vendor lock-in
* Negating vendor lock-in
More information on these points can be found at http://www.sastc.org.za/index.php?option=com_content&task=view&id=18&Itemid=35
More information on these points can be found at http://www.sastc.org.za/index.php?option=com_content&task=view&id=18&Itemid=35
If you already understand XML then you are in a good position to start learning Docbook. If you do not understand XML the good news is that learning Docbook will help you learn XML. Below are two books that are a must read for anyone just starting with Docbook.
If you already understand XML then you are in a good position to start learning DocBook. If you do not understand XML the good news is that learning DocBook will help you learn XML. Below are two books that are a must read for anyone just starting with DocBook.
=== Further Reading ===
=== Further Reading ===
* Doc''''''Book - The Definitive Guide http://www.docbook.org/tdg/en/html/docbook.html
* Doc''''''Book - The Definitive Guide http://www.docbook.org/tdg/en/html/docbook.html
第36行: 第36行:
lynx /usr/share/doc/docbook-defguide/html/docbook.html
lynx /usr/share/doc/docbook-defguide/html/docbook.html
</nowiki></pre>  
</nowiki></pre>  
Whilst reading these works it is useful to experiment. For this you will need an XML publishing tool-chain and an XML Editor. The Docbook Web site and Wiki will provide you with links to more information on the tool chain and editors you can use to author Docbook documents.
Whilst reading these works it is useful to experiment. For this you will need an XML publishing tool-chain and an XML Editor. The DocBook Web site and Wiki will provide you with links to more information on the tool chain and editors you can use to author DocBook documents.
For an explanation of the Ubuntu Documentation Projects usage of Docbook see the "[Ubuntu Docbook Interchange Protocol]."
For an explanation of the Ubuntu Documentation Projects usage of DocBook see the "[Ubuntu DocBook Interchange Protocol]."
=== Quick Tutorial ===
=== Quick Tutorial ===
==== What does DocBook look like? ====
==== What does DocBook look like? ====
DocBook defines a number of 'tags' just like HTML does. To set the authors name you would write something like...
DocBook defines a number of 'tags' just like HTML does. To set the authors name you would write something like...
<pre><nowiki>
<pre><nowiki>
<author>
<author>
Christoph Haas
Christoph Haas
</author>
</author>
</nowiki></pre>
</nowiki></pre>
As you can see this is very similar to HTML. Below is a working example of a complete XML document.
As you can see this is very similar to HTML. Below is a working example of a complete XML document.
第79行: 第79行:
<pre><nowiki>  
<pre><nowiki>  


<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd">
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd">
<article>
<article>
  <title>My first Docbook document</title>
  <title>My first DocBook document</title>
  <sect1>
  <sect1>
      <title>The greeting</title>
    <title>The greeting</title>
      <para>
    <para>
        Hello world
      Hello world
      </para>
    </para>
  </sect1>
  </sect1>
</article>
</article>


</nowiki></pre>  
</nowiki></pre>  
第96行: 第96行:
Run this command::
Run this command::
<pre><nowiki>
<pre><nowiki>
  xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl test.xml
xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl test.xml
</nowiki></pre>
</nowiki></pre>
You should find a file 'test.html' in the current directory. View it with your
You should find a file 'test.html' in the current directory. View it with your
第112行: 第112行:
Usually you write your own stylesheet that imports the 'standard' style sheet. For example::
Usually you write your own stylesheet that imports the 'standard' style sheet. For example::
<pre><nowiki>  
<pre><nowiki>  
<?xml version='1.0'?>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
  <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
    <xsl:param name="toc.max.depth">1</xsl:param>
  <xsl:param name="toc.max.depth">1</xsl:param>
    <xsl:param name="html.stylesheet" select="'/ubuntu.css'"/>
  <xsl:param name="html.stylesheet" select="'/ubuntu.css'"/>
    <xsl:template name="user.header.content">
  <xsl:template name="user.header.content">
      <a href="/">Back to main page</a>
    <a href="/">Back to main page</a>
    </xsl:template>
  </xsl:template>
</xsl:stylesheet>
</xsl:stylesheet>
</nowiki></pre>  
</nowiki></pre>  
This stylesheet first imports the docbook.xsl mentioned earlier.
This stylesheet first imports the docbook.xsl mentioned earlier.
第137行: 第137行:
the processing done in a Makefile. For example::
the processing done in a Makefile. For example::
<pre><nowiki>  
<pre><nowiki>  
# Add your language file here:
# Add your language file here:
TARGETS = faq.html
TARGETS = faq.html


XSLTPROC = /usr/bin/xsltproc
XSLTPROC = /usr/bin/xsltproc
XSL = ubuntu.xsl
XSL = ubuntu.xsl


%.html: %.xml $(XSL)
%.html: %.xml $(XSL)
    @$(XSLTPROC) -o $@ $(XSL) $<
  @$(XSLTPROC) -o $@ $(XSL) $<


all: $(TARGETS)
all: $(TARGETS)


clean:
clean:
    @rm -f *.html
  @rm -f *.html
</nowiki></pre>
</nowiki></pre>
=== DocBook to PDF ===
=== DocBook to PDF ===
The simplest way to convert a Docbook to PDF is to install the xsl-fo stylesheet (to convert to FO format), and fop (to convert FO to PDF). For some reason, the xsl-fo stylesheet is in the docbook-xsl-doc-pdf package.
The simplest way to convert a DocBook to PDF is to install the xsl-fo stylesheet (to convert to FO format), and fop (to convert FO to PDF). For some reason, the xsl-fo stylesheet is in the docbook-xsl-doc-pdf package.
[code]sudo aptitude install fop docbook-xsl-doc-pdf[/code]
<pre><nowiki>
sudo aptitude install fop docbook-xsl-doc-pdf
</nowiki></pre>
Now to convert your docbook file to pdf run:
Now to convert your docbook file to pdf run:
<pre><nowiki>
<pre><nowiki>
第178行: 第180行:
</nowiki></pre>
</nowiki></pre>
To use the makefile, just change the input and output names (networkmanager-manual.*) to whatever you want them to be.
To use the makefile, just change the input and output names (networkmanager-manual.*) to whatever you want them to be.
''Note:'' The w3-Organization has blocked the download of the necessary dtd files by unknown user agents. Due to this (at least in Karmic) fop throws a TransformerException with the notice that the w3 server returned a 503 HTTP response. The workaround seems to be to set up a local dtd repository, as noted [http://old.nabble.com/fop-error-fetching-DTDs-%28being-blocked,-can-I-look-locally-instead%29-td24111380.html here] and [http://sct.sphene.net/board/thread/1893/pdf-generation/ here].
The [http://packages.ubuntu.com/hardy/dblatex dblatex] program can also do this.
The [http://packages.ubuntu.com/hardy/dblatex dblatex] program can also do this.
=== Editing Programs ===
=== Editing Programs ===

2010年5月19日 (三) 22:06的最新版本

{{#ifexist: :DocBook/zh | | {{#ifexist: DocBook/zh | | {{#ifeq: {{#titleparts:DocBook|1|-1|}} | zh | | }} }} }} {{#ifeq: {{#titleparts:DocBook|1|-1|}} | zh | | }}

Purpose

The purpose of this page is to give an overview of the DocBook format. It offers an explanation of the advantages of this format, links further reading on this subject and contains a short tutorial.

What is DocBook?

DocBook is an XML based standard, which is used in many of today's documentation tasks. When you want to create a DocBook document source, you write XML files which describe the document layout, paragraph division and other attributes. XML file structure may look familiar to you if you have seen HTML code before. XML tends to be an improvement over the older HTML specification and can be used to produce complete web pages and other markup documents.

What are the Advantages of DocBook?

DocBook is an OASIS standard and the format in which most open source projects store their documentation. Docbook is developed as an open source application. The project is hosted at Source'Forge and is made available under the GPL. DocBook is available as a Document Type Definition (DTD) and XML Schema (XSD). The project has a large developer and support community spanning both open source and commercial groups. The most important reasons why the project uses DocBook include:

  1. DocBook is a standard
  2. DocBook is open source
  3. DocBook is used by most major projects
  4. DocBook has a large developer and support community

DocBook is also an XML application and XML technologies solve a number of publishing problems for documentation teams, including:

  • Single-sourcing
  • Collaborative authoring
  • Cross-platform editing
  • Multi-channel publishing
  • Improving information quality and consistency
  • Enhancing functionality of electronic output
  • Negating vendor lock-in

More information on these points can be found at http://www.sastc.org.za/index.php?option=com_content&task=view&id=18&Itemid=35 If you already understand XML then you are in a good position to start learning DocBook. If you do not understand XML the good news is that learning DocBook will help you learn XML. Below are two books that are a must read for anyone just starting with DocBook.

Further Reading

If you have installed the package 'docbook-defguide' you can access the guide either through your web browser as:

 
http://localhost/doc/docbook-defguide/html/docbook.html (assuming that your Apache still has /doc aliased to /usr/share/doc) 

You can also access it from the command line using:

 
lynx /usr/share/doc/docbook-defguide/html/docbook.html

Whilst reading these works it is useful to experiment. For this you will need an XML publishing tool-chain and an XML Editor. The DocBook Web site and Wiki will provide you with links to more information on the tool chain and editors you can use to author DocBook documents. For an explanation of the Ubuntu Documentation Projects usage of DocBook see the "[Ubuntu DocBook Interchange Protocol]."

Quick Tutorial

What does DocBook look like?

DocBook defines a number of 'tags' just like HTML does. To set the authors name you would write something like...

<author>
Christoph Haas
</author>

As you can see this is very similar to HTML. Below is a working example of a complete XML document. The 'flavor' used to write these tags is XML. Therefore it is called DocBook/XML. (The other 'flavor' would be SGML which is not greatly different. XML is stricter than SGML. HTML is a kind of SGML language. Most people believe that SGML is deprecated. Thus documentation in Debian is currently converted to XML.) Even if you have not yet used XML you should not have much trouble.

Style sheets

To create the output document from your XML input you also need a style sheet. Stylesheets are called 'XSL Transformations' (XSLT) and are written in a language called 'Extensible Stylesheet Language' (XSL). Basically XSLT describes how to convert one document into another. Usually you will not need to know how style sheets look. You also need a 'processor' that takes the XML and the XSLT and creates the output file from it. We will use the free 'xsltproc' program for that purpose. There is a number of stylesheets available to convert your document into: - Postscript - PDF - XHTML - man - texinfo Other converters exist to convert DocBook into formats like Yelp. Yelp is the the Gnome Help format.

Hello World

First you need to install the following packages:

- xsltproc (the XSL Transformations Processor)
- docbook-xsl (stylesheets for HTML, XHTML, HTML Help and others)
- docbook-defguide (The Definitive Guide to DocBook - recommended)

Enter these lines into a file and call it test.xml:

 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd">
<article>
  <title>My first DocBook document</title>
  <sect1>
     <title>The greeting</title>
     <para>
       Hello world
     </para>
  </sect1>
</article>

Please note that you should use UTF-8 as a character encoding. You may need to switch your terminal and your editor to UTF-8 mode too. Run this command::

xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl test.xml

You should find a file 'test.html' in the current directory. View it with your favorite web browser. Now what did that line actually do? 'xsltproc' is the converter program. '-o test.html' sets the output file. The next parameter '.../docbook.xsl' is the stylesheet you are using for the conversion - this one converts XML to XHTML. And finally the 'test.xml' tells xsltproc where your input file is located.

Customising style sheets

You will probably be disappointed with the look of the DocBook output. It is great to have it convert the document automatically but it probably does not fit into your web design or 'corporate identity' at all. There is a remedy however. Style sheets usually provide a number of parameters that you can adjust. Usually you write your own stylesheet that imports the 'standard' style sheet. For example::

 
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
   <xsl:param name="toc.max.depth">1</xsl:param>
   <xsl:param name="html.stylesheet" select="'/ubuntu.css'"/>
   <xsl:template name="user.header.content">
     <a href="/">Back to main page</a>
   </xsl:template>
</xsl:stylesheet>

This stylesheet first imports the docbook.xsl mentioned earlier. It also sets a few parameters: - Set the maximum depth of the TOC (table of contents) to '1'. So only the <sect1> sections will be included in the TOC. - The final XHTML document will use the 'ubuntu.css' style sheet (CSS). - Include a link to the main page on top of the page. These settings only work with the XHTML style sheet. For other output format you need other settings. The settings above are documented at /usr/share/doc/docbook-xsl/doc/html/index.html You will also want to use http://www.sagehill.net/docbookxsl/ as a reference.

Makefile

If you have multiple XML files or style sheets you may want to have all the processing done in a Makefile. For example::

 
# Add your language file here:
TARGETS = faq.html

XSLTPROC = /usr/bin/xsltproc
XSL = ubuntu.xsl

%.html: %.xml $(XSL)
   @$(XSLTPROC) -o $@ $(XSL) $<

all: $(TARGETS)

clean:
   @rm -f *.html

DocBook to PDF

The simplest way to convert a DocBook to PDF is to install the xsl-fo stylesheet (to convert to FO format), and fop (to convert FO to PDF). For some reason, the xsl-fo stylesheet is in the docbook-xsl-doc-pdf package.

sudo aptitude install fop docbook-xsl-doc-pdf

Now to convert your docbook file to pdf run:

xsltproc -o intermediate-fo-file.fo /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl input-docbook-file.xml
fop -pdf final-pdf-file.pdf -fo intermediate-fo-file.fo

Here's an example Makefile for a docbook named networkmanager-manual.xml:

STYLESHEETS_DIR = /usr/share/xml/docbook/stylesheet/nwalsh

all: html pdf

html:
	xsltproc -o networkmanager-manual.html $(STYLESHEETS_DIR)/xhtml/docbook.xsl networkmanager-manual.xml

fo:
	xsltproc -o networkmanager-manual.fo $(STYLESHEETS_DIR)/fo/docbook.xsl networkmanager-manual.xml

pdf: fo
	fop -pdf networkmanager-manual.pdf -fo networkmanager-manual.fo

clean:
	rm -rf networkmanager-manual.html networkmanager-manual.fo networkmanager-manual.pdf

To use the makefile, just change the input and output names (networkmanager-manual.*) to whatever you want them to be. Note: The w3-Organization has blocked the download of the necessary dtd files by unknown user agents. Due to this (at least in Karmic) fop throws a TransformerException with the notice that the w3 server returned a 503 HTTP response. The workaround seems to be to set up a local dtd repository, as noted here and here. The dblatex program can also do this.

Editing Programs

  1. Bluefish
  1. conglomerate (WYSIWYG)
  • Somewhat beta. Doesn't hide the gory details. You still need to read the DocBook reference. Just makes it graphical.
  • See http://www.conglomerate.org/
  1. VIM file type plugin "xmledit"
  1. EMACS XML support
  • Some say DocBook is easy to write only under psgml. Some use Emacs only for psgml-mode.
  • nxml-mode however is far superior to psgml-mode. It does real-time syntax and error highlighting.
  1. See also DocBookEditors.