DocBook: Difference between revisions
m (using an external editor) |
m (using an external editor) |
||
Line 105: | Line 105: | ||
Below we show a screen capture that shows the title page, automatically generated table of contents and the first page of the Open Office version: | Below we show a screen capture that shows the title page, automatically generated table of contents and the first page of the Open Office version: | ||
[[image:docbook-foss-text-example. | [[image:docbook-foss-text-example.jpg|frame|none|Screenshot of an Open Office document inititally produced with DocBook]] | ||
== Links == | == Links == |
Revision as of 18:12, 1 November 2010
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.
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 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
- 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)
<!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, you can see various rendering, e.g. as wikibook, or PDF or OpenOffice
Below we show a screen capture that shows the title page, automatically generated table of contents and the first page of the Open Office version:
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.
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 (docbook wiki, a very short how to)
Tutorials
- Writing Documentation Using DocBook Crash Course for using the KDE DocBook Tools. The tools themselves are at redhat.
- See e.g. XML Matters article by David Mertz for getting started with docbook.
- O'Reilly has instructions for authors including how to use DocBook with the XML Mind editor. (user = guest, pw = empty or see the Chapter 2: The Proposal
Manuals
- The DocBook Wiki Contains most everything to start (Tutorials, Books, Documentation, Software, ...)!
- DocBook: The Definitive Guide ON-LINE O'Reilly book, nice on paper too.
- Walsh, Norman and Leonard Muellner (1999). DocBook: The Definitive Guide. O'Reilly. ISBN 1-56592-580-7
- Bob Stayton, DocBook XSL: The Complete Guide, A guide to using XSLT stylesheets with DocBook.
Software
Any good XML editor (structure or wysiwyg editor) can be used to edit DocBook. Some vendors already include schemas and Stylesheet.
Other
- 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)
Links of links
- DocBook Bookmarks 2002 Mark Johnson.