DocBook: Difference between revisions
m (using an external editor) |
m (→Tutorials) |
||
(35 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
== Definition == | == Definition == | ||
'''DocBook''' is a [[document standard]] popular for writing large documentation. | '''DocBook''' is a [[XML]]-based [[document standard]] popular for writing large documentation. This [[structured authoring]] standard was originally created by software companies to support writing of technical documentation. However, since then, it has been adapted to many purposes. According to Wikipedia, {{quotation|DocBook began in 1991 as a joint project of HAL Computer Systems and O'Reilly & Associates and eventually spawned its own maintenance organization (the Davenport Group) before moving in 1998 to the SGML Open consortium, which subsequently became OASIS. DocBook is currently maintained by the DocBook Technical Committee at OASIS.}} | ||
{{quotation|As a semantic language, DocBook documents do not describe what their contents "look like," but rather the '''meaning of those contents'''. For example, rather than explaining how the abstract for an article might be visually formatted, DocBook simply says that a particular section '''''is''''' an abstract. It is up to an '''external processing tool''' or application to decide where on a page the abstract should go and what it should look like. (And, indeed, to decide whether or not it should be included in the final output at all.). DocBook provides a vast number of semantic element tags. They are divided into three broad categories: '''structural''', '''block-level''', and '''inline'''.}} ([http://en.wikipedia.org/wiki/Docbook wikipedia], retrieved nov 3 2010). | |||
See also [[DITA]] (a more modular alternative) and the [http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages Comparison of document markup languages] at Wikipedia. | |||
== The principle == | == The principle == | ||
{{quotation|The core DocBook standard is the DocBook Document Type Definition (DTD) maintained by the DocBook Technical Committee in OASIS. The DTD defines the vocabulary of content elements that an author can use and how they relate to each other. For example, a book element can contain a title element, any number of para elements for paragraphs, and any number of chapter elements. Using the DTD and XML syntax, authors mark up their text content with tag names enclosed in angle brackets like <chapter>. The markup is similar to HTML, but with more tags and tighter rule}} ([http://www.sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide]], retrieved 22: | {{quotation|The core DocBook standard is the DocBook Document Type Definition (DTD) maintained by the DocBook Technical Committee in OASIS. The DTD defines the vocabulary of content elements that an author can use and how they relate to each other. For example, a book element can contain a title element, any number of para elements for paragraphs, and any number of chapter elements. Using the DTD and XML syntax, authors mark up their text content with tag names enclosed in angle brackets like <chapter>. The markup is similar to HTML, but with more tags and tighter rule}} ([http://www.sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide]], retrieved 22:26, 4 June 2007 (MEST). | ||
Docbook is interesting if you have: | Docbook is interesting if you have: | ||
Line 17: | Line 21: | ||
One can author docbook with any [[XML editor]] (see [[WYSIWYM]]), but there exist also near or full [[WYSIWYG]] solutions, e.g. FrameMaker. | One can author docbook with any [[XML editor]] (see [[WYSIWYM]]), but there exist also near or full [[WYSIWYG]] solutions, e.g. FrameMaker. | ||
DocBook has a [http://nwalsh.com/docs/articles/extreme2004/ large number of elements], i.e. about 400. The current version V 5.x is specified with a [[Relax NG]] grammar. Non-normative versions for DTD and W3C XML Schema versions are also available. The 5.0 architecture has been redesigned with respect to 4.x. The two versions are [http://www.docbook.org/tdg5/en/html/ch01.html#s.shorthistory not compatible], but there is an upgrading script. | |||
DocBook can be customized to fit specific user's needs (requires the expertise of an information architect). | DocBook can be customized to fit specific user's needs (requires the expertise of an information architect). | ||
Line 23: | Line 29: | ||
Docbook is also used in education, e.g. | Docbook is also used in education, e.g. | ||
* To write documentation | * To write documentation and manuals, e.g. the schoolbus Project (dead project/link) | ||
* To write course materials, e.g. in the [http://edukalibre.org/software Edukalibre] project. | |||
== An example == | == An example == | ||
The following code are bits from [http://www.iosn.net/government/foss-government-primer/FOSS_Government_and_Policy_Primer.xml/view FOSS Government and Policy Primer (docbook xml)] | The following code are bits from [http://www.iosn.net/government/foss-government-primer/FOSS_Government_and_Policy_Primer.xml/view FOSS Government and Policy Primer (docbook xml)] (deadlink, the project was made into [https://en.wikibooks.org/wiki/FOSS_Government_Policy a Wikibook]. | ||
< | <source lang="xml"> | ||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> | ||
<book> | <book> | ||
title>Free/Open Source Software: Government Policy</title> | title>Free/Open Source Software: Government Policy</title> | ||
Line 99: | Line 105: | ||
[.....] | [.....] | ||
</book | </book | ||
</source> | |||
On the internal open source network web site when it was still there, one could the primer in various rendering, e.g. as wikibook, or PDF or OpenOffice | |||
== Styling docbook == | |||
Typically, informal docbook publications are style with an XSLT stylesheet. | |||
The most popular and semi-official stylesheet was mostly written by Norman Walsh and is available for free through sourceforge as [http://wiki.docbook.org/topic/DocBookXslStylesheets explained in the DocBook Wiki] | |||
This DocBook XML Publishing XSLT stylewheet can produce HTML, Chunked HTML, PDF and PostScript as shown in the following figure. | |||
[[image:xmlpubxslt.png|frame|none|Copyright: [http://nwalsh.com/docbook/procdiagram/index.html Norman Walsh], reproduced without permission]] | |||
In addition, one can use the [http://sourceforge.net/projects/db-xsl-cfg/ DocBook XSL Configurator]. It contains three Java (Swing) applications used to create DocBook XSL customization layers (FO, HTML, and Manpages) and then execute external subprocesses to transform DocBook XML and view the output (not tested). | |||
It also is possible to import Docbook into some word processors, e.g. FrameMaker or OpenOffice. | |||
Below we show a screen capture that shows the title page, automatically generated table of contents and the first page of the FOSS example shown above. | |||
[[image:docbook-foss-text-example.jpg|thumb|800px|none|Screenshot of an Open Office document inititally produced with DocBook]] | |||
== Links == | == Links == | ||
Line 110: | Line 133: | ||
* [http://docbook.org/ DocBook]. The official home page for DocBook: The Definitive Guide. Includes downloads for various variants. | * [http://docbook.org/ DocBook]. The official home page for DocBook: The Definitive Guide. Includes downloads for various variants. | ||
* [http://docbook.org/ | * [http://docbook.org/xml/simple Simplified DocBook] | ||
=== Manuals === | |||
* [https://github.com/docbook/wiki/wiki The DocBook Wiki] Contains '''most everything to start''' (Tutorials, Books, Documentation, Software, ...)! | |||
* [http://docbook.org/tdg5/en/html/docbook.html DocBook 5: The Definitive Guide]. Free online book from O'Reilly. by Norman Walsh, edited by Richard Hamilton, ISBN: 9780596805029, | |||
* [http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html DocBook 3: The Definitive Guide] (1999) ISBN 1-56592-580-7. (SGML version, if you have to deal with legacy contents ...) | |||
* [http://www.dpawson.co.uk/docbook/reference.html DocBook Basics and References] | |||
* Bob Stayton, [http://www.sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide], A guide to using XSLT stylesheets with DocBook. | |||
=== Summaries, short manuals, etc. === | |||
* [http://www.informatik.tu-cottbus.de/~agiurca/tutorials/DocBook/index.htm DocBook Tutorial] by Adrain Giurca. On of the best or the best as of 13:31, 30 October 2012 (CET). | |||
* [http://docbook.org/tdg/en/html/quickref.html DocBook Quick Reference] (official) | |||
=== XSLT === | === XSLT === | ||
* [http://docbook.sourceforge.net/ The DocBook Project] on sourceforge supports the open-source development of a variety of DocBook resources; in particular, the DocBook XSL stylesheets. | * [http://docbook.sourceforge.net/ The DocBook Project] on sourceforge supports the open-source development of a variety of DocBook resources; in particular, the DocBook XSL stylesheets. | ||
* [http://sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide], Forth edition by Bob Stayton. Also available in print. | |||
* See also the docbook wiki | |||
=== Tutorials === | === Tutorials === | ||
* [http://www. | ; General | ||
* [http://www.vogella.com/articles/DocBook/article.html DocBook - Tutorial] by Lars Vogel (2008-2012). | |||
* [http://xml.web.cern.ch/XML/goossens/dbatcern/ Writing Documentation Using DocBook] by Michel Goossens (last edition, 2002 as of 13:44, 30 October 2012 (CET)). | |||
* [http://en.wikibooks.org/wiki/XML_-_Managing_Data_Exchange/DocBook XML - Managing Data Exchange/DocBook] (Wikibooks) | |||
* [http://sources.redhat.com/docbook-tools/ redhat] doctool may include tutorials (last time checked, the links were broken) | |||
* See e.g. [http://www-4.ibm.com/software/developer/library/xml-matters3.html XML Matters article] by David Mertz for getting started with docbook. | * See e.g. [http://www-4.ibm.com/software/developer/library/xml-matters3.html XML Matters article] by David Mertz for getting started with docbook. | ||
=== | ; Specific | ||
* Framemaker. Is is still somewhat supported ? Knowing Adobe, it probably is not .... | |||
* [http://chimera.labs.oreilly.com/books/1234000001627 O'Reilly uses Docbook] (among other alternatives) | |||
=== Software === | |||
; Editors | |||
Any good [[XML editor]] (structure or wysiwyg editor) can be used to edit DocBook. Some vendors already include schemas and Stylesheets. | |||
* [http://wiki.docbook.org/topic/DocBookAuthoringTools DocBook Wiki - Validating Editors] | |||
; Complete frameworks (not complete !!) | |||
* [http://www.agynamix.de/products/dobudish/ DobuDish] is a Docbook publishing framework. (last modification 2008 as of 13:36, 30 October 2012 (CET)) | |||
; Bibliography tools (not complete) | |||
* [http:// | * [http://refdb.sourceforge.net/ RefDB] is a reference database and bibliography tool for SGML, XML, and LaTeX/BibTeX documents. | ||
* | * [http://www.linuxfocus.org/English/September2002/article257.shtml Using BibTeXML in DocBook XML to Write Scientific Articles] | ||
=== Other === | === Other === | ||
* [http://nwalsh.com/docbook/ DocBook] page by Norman Walsh. Norman is one of the major XML players and contributed a lot to DocBook (e.g. he is chair of the DocBook technical committee, wrote most of the XSLT stylesheet, co-author of the ''DocBook: The Definitive Guide''...). | |||
* [http://refdb.sourceforge.net/ RefDB], RefDB is a reference database and bibliography tool for DocBook SGML/XML documents. It allows users to share databases over a network. Finally something like this is emerging :) 6/2001 | * [http://refdb.sourceforge.net/ RefDB], RefDB is a reference database and bibliography tool for DocBook SGML/XML documents. It allows users to share databases over a network. Finally something like this is emerging :) 6/2001 | ||
* [http://www.oreillynet.com/xml/blog/2007/05/docbook_elements_in_the_wild_a.html DocBook in the Wild: A Look at Newer Content] by Keith Fahlgren, XML.com. This article shows most popular tags used in more recent O'Reilly books. | |||
* [http://docbook.sourceforge.net/projects/xsl/doc/tools/profiling.html Profiling DocBook documents] article by Jirka Kosek | * [http://docbook.sourceforge.net/projects/xsl/doc/tools/profiling.html Profiling DocBook documents] article by Jirka Kosek | ||
Line 139: | Line 209: | ||
* [http://wiki.docbook.org/topic/WhoUsesDocBook Who Uses Doc Book] | * [http://wiki.docbook.org/topic/WhoUsesDocBook Who Uses Doc Book] | ||
* [http://en.wikipedia.org/wiki/DocBook DocBook] (Wikipedia) | |||
=== Who uses docbook / examples === | |||
* See [http://wiki.docbook.org/topic/WhoUsesDocBook WhoUsesDocBook] in the DocBook wiki. A list of some projects, organizations, individuals and companies that are using DocBook | |||
=== Links of links === | |||
* .... | |||
[[Category: XML]] | [[Category: XML]] | ||
[[Category: Standards]] | [[Category: Standards]] | ||
[[Category: Document standards]] | |||
[[fr:docBook]] |
Latest revision as of 21:21, 26 March 2017
Definition
DocBook is a XML-based document standard popular for writing large documentation. This structured authoring standard was originally created by software companies to support writing of technical documentation. However, since then, it has been adapted to many purposes. According to Wikipedia, “DocBook began in 1991 as a joint project of HAL Computer Systems and O'Reilly & Associates and eventually spawned its own maintenance organization (the Davenport Group) before moving in 1998 to the SGML Open consortium, which subsequently became OASIS. DocBook is currently maintained by the DocBook Technical Committee at OASIS.”
“As a semantic language, DocBook documents do not describe what their contents "look like," but rather the meaning of those contents. For example, rather than explaining how the abstract for an article might be visually formatted, DocBook simply says that a particular section is an abstract. It is up to an external processing tool or application to decide where on a page the abstract should go and what it should look like. (And, indeed, to decide whether or not it should be included in the final output at all.). DocBook provides a vast number of semantic element tags. They are divided into three broad categories: structural, block-level, and inline.” (wikipedia, retrieved nov 3 2010).
See also DITA (a more modular alternative) and the Comparison of document markup languages at Wikipedia.
The principle
“The core DocBook standard is the DocBook Document Type Definition (DTD) maintained by the DocBook Technical Committee in OASIS. The DTD defines the vocabulary of content elements that an author can use and how they relate to each other. For example, a book element can contain a title element, any number of para elements for paragraphs, and any number of chapter elements. Using the DTD and XML syntax, authors mark up their text content with tag names enclosed in angle brackets like <chapter>. The markup is similar to HTML, but with more tags and tighter rule” (DocBook XSL: The Complete Guide], retrieved 22:26, 4 June 2007 (MEST).
Docbook is interesting if you have:
- Large quantities of content.
- Structured content.
- Content that needs to be interchanged among otherwise incompatible systems.
- Content that you also want to process with a computer
- Content to be rendered in multiple output forms and versions (HTML, PDF, PS, ...)
One can author docbook with any XML editor (see WYSIWYM), but there exist also near or full WYSIWYG solutions, e.g. FrameMaker.
DocBook has a large number of elements, i.e. about 400. The current version V 5.x is specified with a Relax NG grammar. Non-normative versions for DTD and W3C XML Schema versions are also available. The 5.0 architecture has been redesigned with respect to 4.x. The two versions are not compatible, but there is an upgrading script.
DocBook can be customized to fit specific user's needs (requires the expertise of an information architect).
In education
Docbook is also used in education, e.g.
- To write documentation and manuals, e.g. the schoolbus Project (dead project/link)
- To write course materials, e.g. in the Edukalibre project.
An example
The following code are bits from FOSS Government and Policy Primer (docbook xml) (deadlink, the project was made into a Wikibook.
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book>
title>Free/Open Source Software: Government Policy</title>
<bookinfo>
<publisher>
<publishername>International Open Source Network</publishername>
</publisher>
<authorgroup>
<author>
<firstname>Kenneth</firstname>
<surname>Wong</surname>
</author>
</authorgroup>
</bookinfo>
<preface>
<title>FOREWORD</title>
<para>Free software means software that respects the user's
freedom. It means that users are free to run the programs as they
wish, free to study and change the software (or hire others to do
it for them), free to redistribute copies to others, and free to
publish modified versions. As a consequence, users are free to
share, and form communities to exercise effective control over the
software they use. Free software may also be gratis, zero price,
but this is not always the case.</para>
[.....]
<para>Richard M. Stallman</para>
</preface>
<preface>
<title>PREFACE</title>
<para>Free and Open Source Software (FOSS) has grown incredibly in
the past few years. Once considered a hobbyist's toy, FOSS has
grown by leaps and bounds and is now used widely throughout the
world, even in critical environments such as financial systems and
network backbones.</para>
[ ....]
</preface>
[ ....]
<chapter>
<title>Introduction</title>
<blockquote>
<attribution>David Wheeler</attribution>
<para>Briefly, OSS/FS programs are programs whose licenses give
users the freedom to run the program for any purpose, to study
and modify the program, and to redistribute copies of either the
original or modified program (without having to pay royalties to
previous developers).
<footnote>
<para>Wheeler, David, "Why OSS/FS? Look at the Numbers!" [home
page online]; available from <ulink
url="http://www.dwheeler.com/oss_fs_why.html">
http://www.dwheeler.com/oss_fs_why.html</ulink>;
Internet; accessed on November 7, 2003.</para>
</footnote>
</para>
</blockquote>
<para>The above quotation summarizes the guiding principles of
FOSS - the freedom to use, understand, modify and distribute
software. Seemingly a simple matter, today, these principles can
have a profound impact on the economics and dynamics of the
software industry.</para> [.... ]
</chapter>
[.....]
</book
On the internal open source network web site when it was still there, one could the primer in various rendering, e.g. as wikibook, or PDF or OpenOffice
Styling docbook
Typically, informal docbook publications are style with an XSLT stylesheet. The most popular and semi-official stylesheet was mostly written by Norman Walsh and is available for free through sourceforge as explained in the DocBook Wiki
This DocBook XML Publishing XSLT stylewheet can produce HTML, Chunked HTML, PDF and PostScript as shown in the following figure.
![](/mediawiki/images/2/2b/Xmlpubxslt.png)
In addition, one can use the DocBook XSL Configurator. It contains three Java (Swing) applications used to create DocBook XSL customization layers (FO, HTML, and Manpages) and then execute external subprocesses to transform DocBook XML and view the output (not tested).
It also is possible to import Docbook into some word processors, e.g. FrameMaker or OpenOffice.
Below we show a screen capture that shows the title page, automatically generated table of contents and the first page of the FOSS example shown above.
Links
DocBook Schemas
Docbook schemas are available in several languages including RELAX NG, SGML and XML DTDs, and W3C XML Schema.
- DocBook. The official home page for DocBook: The Definitive Guide. Includes downloads for various variants.
Manuals
- The DocBook Wiki Contains most everything to start (Tutorials, Books, Documentation, Software, ...)!
- DocBook 5: The Definitive Guide. Free online book from O'Reilly. by Norman Walsh, edited by Richard Hamilton, ISBN: 9780596805029,
- DocBook 3: The Definitive Guide (1999) ISBN 1-56592-580-7. (SGML version, if you have to deal with legacy contents ...)
- Bob Stayton, DocBook XSL: The Complete Guide, A guide to using XSLT stylesheets with DocBook.
Summaries, short manuals, etc.
- DocBook Tutorial by Adrain Giurca. On of the best or the best as of 13:31, 30 October 2012 (CET).
- DocBook Quick Reference (official)
XSLT
- The DocBook Project on sourceforge supports the open-source development of a variety of DocBook resources; in particular, the DocBook XSL stylesheets.
- DocBook XSL: The Complete Guide, Forth edition by Bob Stayton. Also available in print.
- See also the docbook wiki
Tutorials
- General
- DocBook - Tutorial by Lars Vogel (2008-2012).
- Writing Documentation Using DocBook by Michel Goossens (last edition, 2002 as of 13:44, 30 October 2012 (CET)).
- XML - Managing Data Exchange/DocBook (Wikibooks)
- redhat doctool may include tutorials (last time checked, the links were broken)
- See e.g. XML Matters article by David Mertz for getting started with docbook.
- Specific
- Framemaker. Is is still somewhat supported ? Knowing Adobe, it probably is not ....
- O'Reilly uses Docbook (among other alternatives)
Software
- Editors
Any good XML editor (structure or wysiwyg editor) can be used to edit DocBook. Some vendors already include schemas and Stylesheets.
- Complete frameworks (not complete !!)
- DobuDish is a Docbook publishing framework. (last modification 2008 as of 13:36, 30 October 2012 (CET))
- Bibliography tools (not complete)
- RefDB is a reference database and bibliography tool for SGML, XML, and LaTeX/BibTeX documents.
Other
- DocBook page by Norman Walsh. Norman is one of the major XML players and contributed a lot to DocBook (e.g. he is chair of the DocBook technical committee, wrote most of the XSLT stylesheet, co-author of the DocBook: The Definitive Guide...).
- RefDB, RefDB is a reference database and bibliography tool for DocBook SGML/XML documents. It allows users to share databases over a network. Finally something like this is emerging :) 6/2001
- DocBook in the Wild: A Look at Newer Content by Keith Fahlgren, XML.com. This article shows most popular tags used in more recent O'Reilly books.
- Profiling DocBook documents article by Jirka Kosek
- JReferences, is a tool to store and retrieve bibliographic references from a file or MySQL database. It reads BibTeXML, DocBook XML and RIS type references, and can output these and BibTex. A bibtex like alternative is also provided for DocBook. See BibTexML for details about the BibTexML standard and other tools
- DocBook (Wikipedia)
Who uses docbook / examples
- See WhoUsesDocBook in the DocBook wiki. A list of some projects, organizations, individuals and companies that are using DocBook
Links of links
- ....