Техникалық құжаттамаға арналған DocBook тілі

Markup language for documentation

DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software, but it can be used for any other sort of documentation. As a semantic language, DocBook enables its users to create document content in a presentation neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages, WebHelp and HTML Help, without requiring users to make any changes to the source. In other words, when a document is written in DocBook format it becomes easily portable into other formats, rather than needing to be rewritten.

Rules are formally defined in the DocBook XML schema. Appropriate programming tools can validate an XML document (DocBook or otherwise), against its corresponding schema, to determine if (and where) the document fails to conform to that schema. XML editing tools can also use schema information to avoid creating non conforming documents in the first place.

Because DocBook is XML, documents can be created and edited with any text editor. A dedicated XML editor is likewise a functional DocBook editor. DocBook provides schema files for popular XML schema languages, so any XML editor that can provide content completion based on a schema can do so for DocBook. Many graphical or WYSIWYG XML editors come with the ability to edit DocBook like a word processor. Tables, list items, and other stylized content can be copied and pasted into the DocBook editor and will be preserved in the DocBook XML output. DocBook is available in both SGML and XML forms, as a DTD. RELAX NG and W3C XML Schema forms of the XML version are available. Starting with DocBook 5, the RELAX NG version is the "normative" form from which the other formats are generated. DocBook originally started out as an SGML application, but an equivalent XML application was developed and has now replaced the SGML one for most uses. (Starting with version 4 of the SGML DTD, the XML DTD continued with this version numbering scheme.) Initially, a key group of software companies used DocBook since their representatives were involved in its initial design. Eventually, however, DocBook was adopted by the open source community where it has become a standard for creating documentation for many projects, including FreeBSD, KDE, GNOME desktop documentation, the GTK+ API references, the Linux kernel documentation (which, as of July 2016, is transitioning to Sphinx/reStructuredText), and the work of the Linux Documentation Project.

Until DocBook 5, DocBook was defined normatively by a Document Type Definition (DTD). Because DocBook was built originally as an application of SGML, the DTD was the only available schema language. DocBook 4. x formats can be SGML or XML, but the XML version does not have its own namespace. DocBook 4. x formats had to live within the restrictions of being defined by a DTD. The most significant restriction was that an element name uniquely defines its possible contents. That is, an element named info must contain the same information no matter where it is in the DocBook file. As such, there are many kinds of info elements in DocBook 4. x: bookinfo, chapterinfo, etc. Each has a slightly different content model, but they do share some of their content model. Additionally, they repeat context information. The book's info element is that, because it is a direct child of the book; it does not need to be named specially for a human reader. However, because the format was defined by a DTD, it did have to be named as such. The root element does not have or need a version, as the version is built into the DTD declaration at the top of a pre DocBook 5 document. DocBook 4. x documents are not compatible with DocBook 5, but can be converted into DocBook 5 documents via an XSLT stylesheet. One (db4 upgrade. xsl) is provided as part of the distribution of the DocBook 5 schema and specification package.

DocBook files are used to prepare output files in a wide variety of formats. Nearly always, this is accomplished using DocBook XSL stylesheets. These are XSLT stylesheets that transform DocBook documents into a number of formats (HTML, XSL FO for later conversion into PDF, etc.). These stylesheets can be sophisticated enough to generate tables of contents, glossaries, and indexes. They can oversee the selection of particular designated portions of a master document to produce different versions of the same document (such as a "tutorial" or a "quick reference guide", where each of these consist of a subset of the material). Users can write their own customized stylesheets or even a full fledged program to process the DocBook into an appropriate output format as their needs dictate. Norman Walsh and the DocBook Project development team maintain the key application for producing output from DocBook source documents: A set of XSLT stylesheets (as well as a legacy set of DSSSL stylesheets) that can generate high quality HTML and print (FO/PDF) output, as well as output in other formats, including RTF, man pages and HTML Help. Web help also provides an example of web help and is part of the DocBook XSL distribution. The major features are its fully CSS based page layout, search of the help content, and a table of contents in collapsible tree form. Search has stemming, match highlighting, explicit page scoring, and the standard multilingual tokenizer. The search and TOC are in a pane that appears as a frameset, but is actually implemented with div tags and cookies (so that it is progressive).

DocBook offers a large number of features that may be overwhelming to a new user. For those who want the convenience of DocBook without a steep learning curve, Simplified DocBook was designed. It is a small subset of DocBook designed for single documents such as articles or white papers (i. e., "books" are not supported). The Simplified DocBook DTD is currently at version 1.1.

Ingo Schwarze, the author of OpenBSD's mandoc, considers DocBook inferior to the semantic mdoc macro for man pages. In an attempt to write a DocBook to mdoc converter (previous converters like docbook to man do not cover semantic elements), he finds the semantic parts "bloated, redundant, and incomplete at the same time" compared to elements covered in mdoc. Moreover, Schwarze finds the DocBook specification not specific enough about the use of tags, the language non portable across versions, rough in details and overall inconsistent.