Introduction To Docbook 4 .5 Authoring


Published on

DocBook is a general purpose XML and SGML document type particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

For sample code, Please see

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • DocBook XML is a structured future-proof content for publishers.
  • DocBook allows an author to concentrate on the organisation and meaning of the document, in order to ensure all documents have consistent appearance irrespective of the technical writer.
  • DocBook V5.0 is a test release at the time of writing this presentation.
  • XML catalog to locate the DTD With an XML catalog, you can have the best of both local and network access. The catalog lets you map the standard network URL to a local file. If the catalog processor finds the local file during processing, it will use it. Otherwise, it falls back to using the network URL. With this arrangement, you get the speed of local access with the reliability and portability of network access. An XML catalog entry looks like the following: <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <group id="DocbookDTD" prefer="public"> <system systemId="" uri="file:///usr/share/xml/docbook45/docbookx.dtd"/> </group> </catalog>
  • It doesn’t use an XML syntax and, as far as I know, it’s not an easy language.
  • Some authoring tools (like Adobe FrameMaker) provide ways to hide character entities form the author. Special characters are entered through its dedicated interface.
  • Remark RM : Why should I use a DocBook Package? Answer : You don’t have to but it is still good to know that such a thing exists.
  • Other root elements are also possible. The system identifier following the public identifier is just a backup in case the application can’t resolve the public identifier. In my opinion slide 32 to 39 should be recreated. Its better to first mention that you can have an external or an internal DOCTYPE declaration and explain the difference between them and tell that combinations are possible. After that you can say that you have PUBLIC and SYSTEM DOCTYPE declarations and explain when to use the public and system identifiers. I believe the information would be transferred to the audience in a more logical way.
  • The syntax: <!DOCTYPE root-element PUBLIC “ public identifier” “system identifier”> <!DOCTYPE root-element SYSTEM “system identifier”> Depending on the use of the public identifier the token ‘PUBLIC’ or ‘SYSTEM’ should be used.
  • The prefix is either a “+” or a “-” Registered public identifiers begin with “+”; unregistered identifiers begin with “-”. owner-identifier identifies the person or organization that owns the identifier. Registration guarantees a unique owner identifier The text class identifies the kind of document that is associated with this public identifier like DOCUMENT, DTD, ELEMENTS, ENTITIES, NONSGML text-description field provides a description of the document language indicates the language in which the document is written. ISO standard's two-letter language code is used if possible display-version distinguishes between public texts that are the same except for the display device or system to which they apply.
  • PUBLIC The PUBLIC keyword maps public identifiers to system identifiers: <public publicId="-//OASIS//DTD DocBook XML V4.5//EN" uri="docbookx.dtd"/> SYSTEM The SYSTEM keyword maps system identifiers to system identifiers: <system systemId="" uri="docbookx.dtd"/> <system systemId="" uri="docbookx.dtd"/> OVERRIDE The OVERRIDE keyword indicates whether or not public identifiers override system identifiers. If a given declaration includes both a system identifer and a public identifier, most systems attempt to process the document referenced by the system identifier, and consequently ignore the public identifier. Specifying ‘OVERRIDE YES’ in the catalog informs the processing system that resolution should be attempted first with the public identifier. CATALOG The CATALOG keyword allows one catalog to include the content of another. DOCTYPE The DOCTYPE keyword allows you to specify a default system identifier
  • Entities help to reduce the entry of repetitive information and also allow for easier editing. There are two types of entity declarations: GENERAL entity declarations, and PARAMETER entity declarations. INTERNAL GENERAL ENTITY Declaration: Refer to data that an XML processor has to parse Syntax : <!ENTITY name "entity_value"> Example : <?xml version="1.0" standalone="yes" ?> <!DOCTYPE author [ <!ELEMENT author (#PCDATA)> <!ENTITY js "Jo Smith"> ]> <author>&js;</author> EXTERNAL (PARSED) GENERAL ENTITY Declaration: They are useful for creating a common reference that can be shared between multiple documents. There are two types of external entities: Private - Identified by the keyword SYSTEM and are intended for use by a single author or group of authors Syntax : <!ENTITY name SYSTEM "URI"> Example : <?xml version="1.0" standalone="no" ?> <!DOCTYPE copyright [ <!ELEMENT copyright (#PCDATA)> <!ENTITY c SYSTEM ""> ]> <copyright>&c;</copyright> Public - Identified by the keyword PUBLIC and are intended for broad use. Syntax : <!ENTITY name PUBLIC "public_ID" "URI"> Example : <?xml version="1.0" standalone="no" ?> <!DOCTYPE copyright [ <!ELEMENT copyright (#PCDATA)> <!ENTITY c PUBLIC "-//W3C//TEXT copyright//EN" ""> ]> <copyright>&c;</copyright> EXTERNAL (UNPARSED) GENERAL ENTITY Declaration: Refer to data that an XML processor does not have to parse. Syntax : <!ENTITY name SYSTEM "URI" NDATA name> <!ENTITY name PUBLIC "public_ID" "URI" NDATA name> Example : <?xml version="1.0" standalone="no" ?> <!DOCTYPE img [ <!ELEMENT img EMPTY> <!ATTLIST img src ENTITY #REQUIRED> <!ENTITY logo SYSTEM "" NDATA gif> <!NOTATION gif PUBLIC "gif viewer"> ]> <img src="logo"/> The PARAMETER ENTITY Declaration (not be used within mark-up in an internal DTD ) has following two types, INTERNAL - used to declare entities existing only in the DTD Syntax : <!ENTITY % name "entity_value"> Example : <!--external DTD example--> <!ELEMENT author (#PCDATA)> <!ENTITY % js "Jo Smith"> <!--note that the general entity statement below is used to reference a parameter entity--> <!ENTITY wb "written by %js;"> EXTERNAL - used to link external DTDs. Again, there are two types of external entities: private, and public. Syntax : <!ENTITY % name SYSTEM "URI"> %name; <!ENTITY % name PUBLIC "public_ID" "URI"> %name; Example : <?xml version="1.0" standalone="no"?> <!DOCTYPE student [ <!ENTITY % student SYSTEM ""> %student; ]>
  • The DocBook definition of a book is very loose and general. Given the number of different conventions for book organisation used in various countries, attempting to impose a strict ordering of elements can make the content model extremely complex. Therefore, DocBook provides a free reign. It's common to use a local customisation layer to impose a more strict ordering for applications.
  • What is important is that you choose to mark up not every possible item, but only those for which distinctive tagging will be useful in the production of the finished document for the readers who will search through it.
  • If you try to use xref or link to cross reference to another file module, then your mini document is no longer valid. That is because those elements use an IDREF-type attribute to form the link, and the ID it points, must reside in the same document. They will be together when you assemble your modules into a larger document, but the individual mini documents will be incomplete. When you try to open such a module in a structured editor, it will complain that the document is not valid.
  • The value of href attribute in an XInclude can be an absolute path a relative path (taken as relative to the document that contains the XInclude element) an HTTP URL that accesses a web server or any other URI. Also, it can be mapped with XML catalog entries.
  • In theory you would be able to create a loop. Note : A document's root element can be an XInclude element. In that case, there should be only one such occurrence, since a well-formed document can only have a single root element. Likewise, the included content must resolve to a single element, with its children.
  • For selections based on id, the included document must have a DOCTYPE declaration that correctly points to the DocBook DTD. If the file does not have the DOCTYPE or if the DTD cannot be opened, then such references will not resolve. Note : When you omit the href attribute, and add an xpointer attribute, it is interpreted as selecting from the current document. One cannot select the entire document or that part of the document which has the XInclude element, because that would be a circular reference. Also, you don’t want to repeat content that has id attributes, as duplicate id values are invalid.
  • Note : The fallback content must be equally valid when inserted into the document for it to work.
  • Question RM : Do you also need Olink to make a link to a location in a file which is included in the file containing the Olink by XInclude? Remark RM : Perhaps you could make this process much clearer by illustrating it step by step.
  • Generally, the HTML files for multiple documents are output to different directories, particularly if chunks are used. Therefore one must decide the names and arrangement of the HTML output directories for all the documents in collection as a preliminary step. It is only the relative location that counts; the top level name is not used because the style-sheet computes the relative path for cross reference URLs using the relative locations. Chunking - It is the process of splitting the output for a large document into several HTML files. The individual output files are called chunks . The results are a coherent set of linked files, with a title page containing a table of contents as the starting point for browsing the set.
  • “ Only ” generates the target data file, but does not process the document for output. Use the option “ yes ” to also continue to process the document for output. When master target database document is processed, the content of the target.db file is assimilated into its proper location in the hierarchy using its system entity reference, thus forming the complete cross reference database. The use of system entities permits the individual target.db data files for each document to be updated as needed, and the database automatically gets the update the next time it is processed. If the DocBook chunking feature is used, then it would be the path to chunk.xsl instead.
  • target.database.document - provides the location of the master target database file. As the document is processed and when the style sheet encounters an olink that has targetdoc and targetptr attributes, it looks up the values in the target database and resolves the reference. If it cannot open the database or find a particular olink reference, then it reports an error. current.docid informs the processor of the current document's targetdoc identifier. Sometimes, current document's identifier is not recorded in the document itself, so the processor must be told of it by using this parameter. current.docid parameter can be automatically set if the id attribute of the document's root element is assigned the targetdoc value. This is accomplished by adding the following to customisation layer. <xsl:param name="current.docid" select="/*/@id"/>
  • Question RM : So this is a m * n relation?
  • Most are familiar with the term 'Web content management system'; which is a software used to manage and control a dynamic collection of web material. Primarily, maintenance tool designed to serve non-technical administrators; for a web-site that will constantly have new content (like products or company news) added /updated to it.
  • Compound document - A single document that contains a combination of data structures such as text, graphics, spreadsheets, sound and video clips. The document may embed the additional data types or reference external files by pointers of some kind. SGML and HTML are examples of compound document formats.
  • Most of us are familiar with the term 'Web content management system'; which is a software used to manage and control a dynamic collection of web material. Primarily, maintenance tool designed to serve non-technical administrators; for a web-site that will constantly have new content (like products or company news) added /updated to it.
  • Introduction To Docbook 4 .5 Authoring

    1. 1. DocBook - by Viswanath Jayachandran
    2. 2. Quick introduction <ul><li>DocBook is a very popular set of tags for describing books, articles, and other textual documents, particularly technical documentation. </li></ul><ul><li>DocBook is defined using the native DTD syntax of SGML and XML </li></ul>
    3. 3. Quick introduction <ul><li>DocBook is a XML vocabulary that enables us to author and store document content in a presentation-neutral form that captures the logical structure of the content. </li></ul><ul><li>DocBook XML can be used to transform in to numerous structured document and the content can be published in many formats. </li></ul>
    4. 4. Quick introduction <ul><li>DocBook XML is a structured future-proof content format for publishers. </li></ul><ul><li>It is easier to revise as it can be directly accessed by using popular desktop publishing softwares, such as, Adobe FrameMaker, InDesign, QuarkXpress, etc </li></ul>
    5. 5. A more detailed look
    6. 6. A detailed introduction to DocBook <ul><li>DocBook is a strictly structured mark-up language very similar to HTML designed by OASIS consortium, specifically for technical documentation . </li></ul><ul><li>It provides a rich set of tags to describe the document’s content. The tags provide structure to the document and appear intermixed with informational text. </li></ul>
    7. 7. A detailed introduction to DocBook <ul><li>Technically, DocBook format is expressed in XML DTD and can thus profit from XML aware tools. </li></ul><ul><li>DocBook is not a presentation language. It specifies semantics rather than presentation. All the presentation issues are handled by style sheets. </li></ul>
    8. 8. A detailed introduction to DocBook <ul><li>Because of its modular organisation, DocBook is easily customisable to meet one’s requirements. </li></ul><ul><li>DocBook is extensive as it has a large number of tags that can accommodate a wide range of situations and processing expectations </li></ul>
    9. 9. A detailed introduction to DocBook <ul><li>DocBook uses long and self-explanatory tags that is a lot easier to read than an HTML source for example. </li></ul><ul><li>DocBook does not ensure upwards compatibility between major releases because it ensures a clean design even if wrong choices have been made previously by the DocBook Commitee at OASIS. Also, documents written with different DTDs can co-exist. </li></ul>
    10. 10. Why DocBooks ? (Raison d'être) <ul><li>Traditional approaches suffer from a few serious problems. </li></ul><ul><ul><li>Longevity of the document was adversely affected – Information of significance is interspersed with information that will become obsolete ( like typesetting information) </li></ul></ul><ul><ul><li>Lack of structure - The traditional markup (like HTML) did not express content, but rather the page layout. Locating and indexing a semantic content of importance was a challenging task. </li></ul></ul>
    11. 11. Objective <ul><li>Emphasise semantic content such that useful information can be extracted and indexed. </li></ul><ul><li>DocBook provides a very rich set of markup tags that relate to the structure and nature of the document’s content. </li></ul>
    12. 12. Pro and con <ul><li>Benefit </li></ul><ul><li>A search engine would provide the information actually sought without all the extra references that just happen to use those words casually. </li></ul><ul><li>Hurdle </li></ul><ul><li>DocBook has hundreds of tags (as opposed to just a few in HTML), hence the learning curve is steep. </li></ul>
    13. 13. Getting started with DocBook <ul><li>DocBook follows the syntax of XML, just like XHTML does. It can be converted to other formats through XSLT style sheets for instance, and a PDF layout can be accomplished through a XSL-FO engine. </li></ul>
    14. 14. DocBook tools <ul><li>DocBook-tools is a collection of free software tools necessary to work upon and format DocBook documents </li></ul><ul><li>The Docbook tools are categorised as </li></ul><ul><ul><li>Authoring tools - Editing applications </li></ul></ul><ul><ul><li>Publishing tools - Transform DocBook to other formats </li></ul></ul><ul><ul><li>Convenience tools - Scripts, utilities, and web services that act as easier-to-use front ends to DocBook publishing tools. </li></ul></ul>
    15. 15. DocBook Authoring Tools <ul><li>Validating editors are schema / DTD aware applications that interactively validate documents as user edits them. </li></ul><ul><li>Context-sensitive editors that provide off-the-shelf DocBook support. </li></ul><ul><li>Sometimes bundled with DocBook XSL stylesheets or other custom DocBook transformation support. </li></ul>
    16. 16. DocBook Publishing Tools <ul><li>Tools for transforming DocBook documents into other formats. </li></ul><ul><li>DocBook Publishing Tools are broadly classified as </li></ul><ul><ul><li>DocBook specific publishing tools - Publishing tools designed specifically for use with DocBook include </li></ul></ul><ul><ul><li>XSL publishing tools - Tools in the DocBookXslStylesheets toolchain include general-purpose XSLT engines and FO engines. </li></ul></ul><ul><ul><li>DSSSL publishing tools </li></ul></ul>
    17. 17. DocBook toolchain <ul><li>DocBook tools configured to work together are termed DocBook toolchain. </li></ul><ul><li>For instance, in <oXygen/> XML Editor, DocBookAuthoringTools contain publishing tool-chains built in. </li></ul><ul><li>It includes the Apache FOP Processor, for generating PDF and PostScript. Other FO processors can be configured as plug-in. </li></ul>
    18. 18. Installation of DocBook DTD <ul><li>Obtain DocBook from the website of Oasis that maintains it. The url is </li></ul><ul><li>At the time of writing this presentation, DocBook version 4.5 is the official latest version available. DTDs are available for both XML and SGML. The presentation confines its scope only to XML. </li></ul><ul><li>Other forms that are available like RELAX NG and W3C XML Schema are unofficial. </li></ul>
    19. 19. Installation of DocBook DTD
    20. 20. DocBook DTD <ul><li>DocBook XML DTD consists of a main file docbookx.dtd that pulls several module files to form the complete DTD. </li></ul><ul><li>In XML documents, DTD(s) must be identified by means of a DOCTYPE declaration at the beginning of the XML file that provides the processor with clues for finding the DTD files. </li></ul><ul><li>The DOCTYPE declaration for network DTD access looks like the following </li></ul><ul><li><!DOCTYPE book PUBLIC &quot;-//OASIS//DTD DocBook XML V4.5//EN&quot; &quot;;> </li></ul>
    21. 21. DocBook stylesheets <ul><li>DocBook stylesheets transform DocBook into some other format such as HTML, XSL-FO, nroff (man) pages, OASIS OpenDocument etc </li></ul><ul><li>DocBook stylesheets come in three flavours </li></ul><ul><ul><li>DocBookDssslStylesheets – used with Jade/Openjade DSSSL engine </li></ul></ul><ul><ul><li>DocBookXslStylesheets – used with XSLT engines </li></ul></ul><ul><ul><li>DocBookCssStylesheets - used for controlling direct rendering of DocBook documents in Web browsers and in WYSIWYG XML editors. </li></ul></ul><ul><li>DocBookXslStylesheets alone are in-scope of the presentation. </li></ul>
    22. 22. DSSSL <ul><li>DSSSL - Document Style Semantics and Specification Language. </li></ul><ul><li>A style sheet and transformation language for SGML documents. It allows an SGML document to be formatted for presentation or converted into another structure. </li></ul><ul><li>Jade is an example of a DSSSL processor written by James Clark. </li></ul>
    23. 23. DocBookXslStylesheets <ul><li>Designed and actively developed by NormanWalsh, stylesheets( maintained by DocBookOpenRepository ( </li></ul><ul><li>DocBook XSL Configurator ( ) contains swing applications used to create DocBook XSL customization layers (FO, HTML, and Manpages) and then execute external sub-processes to transform DocBook XML and view the output. </li></ul>
    24. 24. Validation and Character entities <ul><li>The DocBook DTD defines the character entities that make it easy to add special characters to your XML files. </li></ul><ul><ul><li>For example - To enter a copyright symbol, for example, it is easier to remember a name like &copy; than the equivalent © Unicode entity. </li></ul></ul><ul><li>Most XSL processors will not automatically validate your document while it is converting it. </li></ul>
    25. 25. Validation and Character entities <ul><li>The XSL processor will read a DOCTYPE declaration in the XML file and try to find the DTD, and will likely report an error if it cannot. </li></ul><ul><li>If it does find the DTD, it will read and use an entity declarations in it. Thus, If you use any DocBook character entities, the processor must be able to find the DTD to resolve those entity references. </li></ul><ul><li>DocBook stylesheets expect to be processing a valid document thus it is advised validate the documents prior to processing them. </li></ul>
    26. 26. DocBook Packages <ul><li>There are also package installation software available for various operating system platforms. For the Windows platform e-novative and CygwinPackages are good choices. </li></ul><ul><li>E-novative is DocBook environment for Windows released under GPL. It incorporates well-documented parametrisation and customisation of the original DocBook XSL stylesheets, enabling document type and document specific settings a breeze. </li></ul><ul><li>Cygwin is a Linux-like environment for Windows which enables us to use many standard UNIX utilities. </li></ul>
    27. 27. e-novative DocBook Environment <ul><li>eDE can be downloaded from </li></ul><ul><li>eDE installs to c:docbook </li></ul><ul><li>The folders </li></ul><ul><ul><li>dtd : Has the DocBook XML DTD. </li></ul></ul><ul><ul><li>fop : Has Apache Form Objects Processor to generate PDF documents </li></ul></ul>
    28. 28. e-novative DocBook Environment <ul><li>include - Holds boilerplate texts that can be included into any eDE document </li></ul><ul><li>output - Has one subdirectoy for each eDE document. Each document subdirectory has a subdirectory for each output format. </li></ul><ul><li>repository - Each document directory consists of the DocBook XML source file, a subdirectory for all the figures to appear in the document and entities for document-specific boilerplate text. </li></ul>
    29. 29. e-novative DocBook Environment <ul><li>stylesheet – Holds XSL and CSS stylesheets. </li></ul><ul><li>template - eDE templates documents for articles, books and boilerplate text. </li></ul><ul><li>backup - Used by eDE to backup XML source files and settings on an update </li></ul><ul><li>xsl - Original DocBook XSL stylesheets that define the transformation from DocBook XML to the various output formats </li></ul><ul><li>deploy - one subdirectory for each document that holds a zip file for each output format. </li></ul>
    30. 30. Creating DocBook Documents <ul><li>Objective of this section is to provide basic skeletal information in order to write DocBook documents. </li></ul><ul><li>This section is designed to give an overview and certainly not an exhaustive list of every element’s detail in DocBook. </li></ul>
    31. 31. Creating DocBook - XML basics <ul><li>Identify the version of XML to ensure that future changes to the XML specification will not alter the semantics of the document. </li></ul><ul><li>The standalone declaration simply makes explicit the fact that this document cannot “stand alone,” and that it relies on an external DTD. </li></ul><ul><li><?xml version=&quot;1.0&quot; standalone=&quot;no&quot;?> </li></ul>
    32. 32. Creating DocBook - XML basics <ul><li>Even though XML documents don't require a DTD, DocBook XML documents will mostly have one. </li></ul><ul><li>The DOCTYPE declaration below indicates that the root element will be <book> and that the DTD used will be the one identified by the public identifier --//OASIS//DTD DocBook XML V4.5//EN . </li></ul><ul><li><!DOCTYPE book PUBLIC &quot;-//OASIS//DTD DocBook XML V4.5//EN&quot; “”> </li></ul>
    33. 33. Creating DocBook - XML basics <ul><li>External declarations in XML must include a system identifier (the public identifier used here is optional). </li></ul><ul><li><!DOCTYPE book PUBLIC &quot;-//OASIS//DTD DocBook XML V4.5//EN&quot; “”> </li></ul><ul><li>System identifiers in XML must be URIs. Many systems may accept filenames and interpret them locally as file: URLs, but it's always correct to fully qualify them. </li></ul><ul><li>file:///usr/local/xml/docbook/4.5/docbook.dtd </li></ul>
    34. 34. Creating DocBook - XML basics <ul><li>When a DTD or other external file is referenced from a document, the reference can be specified in three ways: using </li></ul><ul><ul><li>a public identifier , </li></ul></ul><ul><ul><li>a system identifier , or </li></ul></ul><ul><ul><li>both. </li></ul></ul><ul><li>In XML, the system identifier is generally required and the public identifier is optional. </li></ul>
    35. 35. Creating DocBook - XML basics <ul><li>A public identifier is a globally unique, abstract name. </li></ul><ul><li>The advantage of using the public identifier is that it makes documents more portable. </li></ul><ul><li>For any system on which DocBook is installed, the public identifier will resolve to the appropriate local version of the DTD (if public identifiers can be resolved at all). </li></ul>
    36. 36. Creating DocBook - XML basics <ul><li>A public identifier can be any string of upper- and lowercase letters, digits, any of the following symbols: “'”, “(“, “)”, “+”, “,”, “-”, “.”, “/”, “:”, “=”, “?”, and white space, including line breaks. </li></ul><ul><li>Most public identifiers conform to the ISO 8879 standard. </li></ul><ul><li>prefix//owner-identifier//text-class text-description//language//display-version </li></ul>
    37. 37. Creating DocBook - XML basics <ul><li>Catalog files are the standard mechanism for resolving public identifiers into system identifiers. See </li></ul><ul><li>A catalog is a text file that contains a number of keyword/value pairs. </li></ul><ul><li>The most frequently used keywords are PUBLIC, SYSTEM, SGMLDECL, DTDDECL, CATALOG, OVERRIDE, DELEGATE, and DOCTYPE. </li></ul>
    38. 38. Creating DocBook - XML basics <ul><li>Internal Subset - It's also possible to provide additional declarations in a document by placing them in the document type declaration. </li></ul><ul><li><?xml version=&quot;1.0&quot;?> </li></ul><ul><li><!DOCTYPE author [ <!ELEMENT author (#PCDATA)> <!ENTITY email &quot;;> </li></ul><ul><li><!--the following use of a general entity is legal if it is used in the XML document--> </li></ul><ul><li><!ENTITY js &quot;Jo Smith &email;&quot;> ]> </li></ul><ul><li><author>&js;</author> </li></ul>
    39. 39. Creating DocBook - XML basics <ul><li>The declarations stored in the file referenced by the public or system identifier in the DOCTYPE declaration is called the external subset , which is technically optional. Note that these files do not and must not have document type declarations . </li></ul><ul><li>It is legal to put the DTD in the internal subset and to have no external subset, but for a DTD as large as DocBook, that would make very little sense. </li></ul><ul><li><?xml version=&quot;1.0&quot; standalone=&quot;no&quot; ?> </li></ul><ul><li><!DOCTYPE copyright [ <!ELEMENT copyright (#PCDATA)> <!ENTITY c SYSTEM &quot;;> ]> </li></ul><ul><li><copyright>&c;</copyright> </li></ul>
    40. 40. Categories of Elements in DocBook <ul><li>DocBook elements can be broadly classified into the following : </li></ul><ul><li>Sets </li></ul><ul><li>Books </li></ul><ul><li>Divisions, - That divide books into parts </li></ul><ul><li>Components - That divide books or divisions into chapters </li></ul><ul><li>Sections - That subdivide components </li></ul><ul><li>Meta-information elements </li></ul><ul><li>Block elements </li></ul><ul><li>Inline elements </li></ul>
    41. 41. Elements in DocBook - Sets <ul><li>Sets – Hierarchical top of DocBook that contains more than one Books. </li></ul><ul><li>Set tag is typically used for a series of books on a particular subject that is accessed and maintained as a single unit. </li></ul><ul><li>Example : End user’s guide for a product. </li></ul>
    42. 42. Elements in DocBook - Books <ul><li>Most common top-level element in a document that consists of a mixture of the following elements </li></ul><ul><ul><li>Dedication </li></ul></ul><ul><ul><li>Navigational Components </li></ul></ul><ul><ul><li>Divisions </li></ul></ul><ul><ul><li>Components </li></ul></ul>
    43. 43. Elements in DocBook - Books <ul><li>Dedication frequently appears on a page by itself at the beginning of a book. </li></ul><ul><li>Navigational Components are component-level elements designed for navigation like </li></ul><ul><ul><li>ToC, for Tables of Contents; </li></ul></ul><ul><ul><li>LoT, for Lists of Titles (for lists of figures, tables, examples, and so on); and </li></ul></ul><ul><ul><li>Index, for indexes. </li></ul></ul>
    44. 44. Elements in DocBook - Divisions and Components <ul><li>Divisions are the first hierarchical level below Book. They contain </li></ul><ul><ul><li>Parts – Contains components </li></ul></ul><ul><ul><li>References – Contains RefEntry </li></ul></ul><ul><li>Components are chapter-like elements of a Book or Part. Books can contain components directly and are not required to contain divisions. </li></ul><ul><li>Components generally contain block elements and/or sections , but some can also contain navigational components and RefEntrys . </li></ul>
    45. 45. Elements in DocBook - Sections <ul><li>Sections sub-divide components and have several flavours. Namely, </li></ul><ul><ul><li>Sect1…Sect5 elements </li></ul></ul><ul><ul><li>Section element </li></ul></ul><ul><ul><li>SimpleSect element </li></ul></ul><ul><ul><li>BridgeHead </li></ul></ul><ul><ul><li>RefSect1…RefSect3 elements </li></ul></ul><ul><ul><li>GlossDiv, BiblioDiv, and IndexDiv </li></ul></ul>
    46. 46. Elements in DocBook - Meta-Information <ul><li>Wrapper designed to contain </li></ul><ul><ul><li>Bibliographic information about the content (Author, Title, Publisher etc) and </li></ul></ul><ul><ul><li>Other meta-information (such as revision histories, keyword sets, and index terms. </li></ul></ul><ul><li>Applies to all the elements at the section level and above </li></ul>
    47. 47. Elements in DocBook – Paragraph level elements <ul><li>At the paragraph-level, elements are divided into </li></ul><ul><ul><ul><li>Block and </li></ul></ul></ul><ul><ul><ul><li>Inline </li></ul></ul></ul><ul><ul><li>elements from a structural point of view based on their relative size. </li></ul></ul><ul><li>Block elements are presented with a paragraph break before and after them. Usually, they contain other block elements, character data and inline elements. </li></ul>
    48. 48. Elements in DocBook – Block Elements <ul><li>Block elements occur immediately below the component and sectioning elements. </li></ul><ul><li>They can be divided into a number of categories: </li></ul><ul><ul><li>Lists </li></ul></ul><ul><ul><li>Admonitions </li></ul></ul><ul><ul><li>Line-specific environments </li></ul></ul><ul><ul><li>Synopses of several sorts </li></ul></ul><ul><ul><li>Tables </li></ul></ul><ul><ul><li>Figures </li></ul></ul><ul><ul><li>Examples and </li></ul></ul><ul><ul><li>A dozen or more miscellaneous elements. </li></ul></ul>
    49. 49. Elements in DocBook – Inline Elements <ul><li>Inline elements are generally represented without any obvious breaks. They may be distinguished through a change in font or may also have absence of visual distinction. </li></ul><ul><li>Inline elements are used to mark up data such as cross references, filenames, commands, options, subscripts and superscripts, and glossary terms. </li></ul><ul><li>Inline elements contain character data and possibly other inline elements, but they never contain block elements. </li></ul>
    50. 50. Elements in DocBook – Inline Elements <ul><li>Sub categories of inline elements are as follows. </li></ul><ul><ul><li>Traditional publishing inlines – Identify items that occur in general writing. Like Acronym, Footnote, Trademark, Footnote, Quote etc. </li></ul></ul><ul><ul><li>Cross references – Identify both explicit cross references such as Link and implicit cross references like GlossTerm. </li></ul></ul><ul><ul><li>Markup - used to mark up text for special presentation </li></ul></ul><ul><ul><li>Mathematics – elements representing equations </li></ul></ul><ul><ul><li>User interfaces – elements that describe the aspect of a UI </li></ul></ul><ul><ul><li>Programming languages and constructs </li></ul></ul><ul><ul><li>Operating System </li></ul></ul><ul><ul><li>General purpose </li></ul></ul>
    51. 51. Creating a DocBook - Book <ul><li>A typical Book, in English at least, consists of </li></ul><ul><ul><li>Some meta-information in a BookInfo (Title, Author, Copyright, and so on) </li></ul></ul><ul><ul><li>One or more Prefaces </li></ul></ul><ul><ul><li>Several Chapters and </li></ul></ul><ul><ul><li>Perhaps a few Appendixes. </li></ul></ul><ul><li>A Book may also contain </li></ul><ul><ul><li>Bibliographies </li></ul></ul><ul><ul><li>Glossaries </li></ul></ul><ul><ul><li>Indexes and </li></ul></ul><ul><ul><li>A Colophon. </li></ul></ul><ul><li>See the example for a typical book in english </li></ul>
    52. 52. Creating a DocBook - Chapter <ul><li>Chapter(s), Preface(s), and Appendix(es) have a similar structure. They consist of a </li></ul><ul><ul><li>Title </li></ul></ul><ul><ul><li>Meta-information (optional) </li></ul></ul><ul><ul><li>Block-level element(s) followed by top level section(s) </li></ul></ul><ul><ul><ul><li>Each section may in turn contain any number of block-level elements followed by next section level </li></ul></ul></ul><ul><li>See the example for better understanding. </li></ul>
    53. 53. Creating a DocBook - Article <ul><li>Article is the most logical starting point for documents smaller than books like journal, white-paper, technical notes etc.It has same body as any component-level element like chapter. </li></ul><ul><li>An Article is composed of a header and a body. </li></ul><ul><li>Please take a moment to look at the sample article. </li></ul>
    54. 54. Creating a DocBook – Para <ul><li>A Para is a paragraph in DocBook that may contain almost all inline and most block elements. </li></ul><ul><li>DocBook offers two variants of paragraph apart from the general Para element </li></ul><ul><ul><li>SimPara - cannot contain block elements </li></ul></ul><ul><ul><li>FormalPara - has a title </li></ul></ul><ul><li>Look at the example for better understanding. </li></ul>
    55. 55. Creating a DocBook - Literal <ul><li>Other frequently used elements of DocBook DTD include literal. </li></ul><ul><li>A literal is some specific piece of data, taken literally, from a computer system. </li></ul><ul><li>A literal is frequently distinguished typographically and its ‘moreinfo’ attribute can help generate a link or query to retrieve additional information. </li></ul><ul><li>Again, please take a look at the example </li></ul>
    56. 56. Creating a DocBook - Others <ul><li>The XRef element forms a cross-reference from its location to another part of document it points. </li></ul><ul><li><xref linkend=&quot;text-of-the-link“ endterm=&quot; cross-reference-target &quot;/> </li></ul><ul><li>Also see mediaobject and table </li></ul>
    57. 57. Modular DocBook files <ul><li>Modular DocBook means your content collection is broken up into smaller file modules that are recombined for publication. </li></ul><ul><li>The advantages of modular documentation include: </li></ul><ul><ul><li>Reusable content units. </li></ul></ul><ul><ul><li>Smaller file units to load into an editing program. </li></ul></ul><ul><ul><li>Distributed authoring. </li></ul></ul><ul><ul><li>Finer grain version control. </li></ul></ul><ul><li>The best tools for modular documentation are XIncludes and olinks. </li></ul>
    58. 58. Modular DocBook files - XInclude <ul><li>XInclude replaces the old way of using system entities that were always a problem as system entities cannot have a DOCTYPE declaration, and therefore cannot be valid documents on their own. </li></ul><ul><li>However with XInclude, the modular files can be valid mini documents, complete with DOCTYPE declaration. </li></ul><ul><li>Conveniently, the module's DOCTYPE does not generate an error when its content is injected using the XInclude mechanism. </li></ul>
    59. 59. Modular DocBook files - Olink <ul><li>Olinks enable us to form cross references among modular files. </li></ul><ul><li>Olinks do not use IDREF attributes to form the cross reference; instead they are resolved by the style sheet at run-time, whether you are processing a single module or the assembled document. </li></ul>
    60. 60. Modular DocBook files - using XInclude <ul><li>Synopsis : One can divide the content into several valid file modules, and use XInclude to assemble them into larger valid documents. </li></ul><ul><li>For example, each chapter of a book can be separated into its own document file for writing and editing; that can later be assembled into a book for processing and publication. </li></ul><ul><li>Please see the example. </li></ul>
    61. 61. Modular DocBook files - using XInclude <ul><li>Constituting or Embodying file modules of a Docbook must have a complete DOCTYPE declaration to identify it as a mini-document. Unless otherwise specified, an XInclude fetches the root element and all its children. </li></ul><ul><li>The syntax for the inclusion is an empty element whose name is include, that is defined in the namespace for XInclude. It is customary to use the prefix xi:. The href attribute contains a URI that points to the file to include. </li></ul>
    62. 62. Modular DocBook files - using XInclude <ul><li>When the XInclude is resolved during the processing, the <xi:include> element will be replaced by the included chapter element and all of its children. </li></ul><ul><li>It is the author's responsibility to ensure that the included content is valid in the location where it is injected. </li></ul><ul><li>One can also nest Xincludes. </li></ul>
    63. 63. Modular DocBook files - using XInclude <ul><li>XInclude standard permits us to select a part of a file for inclusion instead of the entire file. </li></ul><ul><li>In a modular source setup, that means we can organise our modules into logical units for authoring, and perform selections from the content of a file module when required. </li></ul><ul><li>The simplest syntax just has an id value in an xpointer attribute. </li></ul><ul><li><xi:include href=&quot;intro.xml&quot; xpointer=&quot;Installing&quot; xmlns:xi=&quot;;/> </li></ul><ul><li>More complex selections can be made using the full XPointer syntax. </li></ul>
    64. 64. Modular DocBook files - using XInclude (Including plain text) <ul><li>The attribute parse=&quot;text&quot; attribute of XInclude facilitates us by indicating the processor to treat the incoming content as plain text instead of the default XML. </li></ul><ul><li>XInclude can thus be used to include plain text files by pointing the href attribute to the file-name. The encoding of the incoming text is specified by adding an encoding attribute. </li></ul><ul><li>Since the included text is not XML, one cannot use an xpointer attribute with XPointer syntax to select part of it. </li></ul>
    65. 65. Modular DocBook files - using XInclude (fallback mechanism) <ul><li>XInclude contains some fallback content that permits processing to continue if an include cannot be resolved at runtime. </li></ul><ul><li>Usage : Insert a single xi:fallback child element to indicate that the content of the child should be used if XInclude resolution fails. </li></ul><ul><li><xi:include href=&quot;intro.xml&quot; xmlns:xi=&quot;;> </li></ul><ul><li><xi:fallback> </li></ul><ul><li><para>FIXME: MISSING XINCLUDE CONTENT</para> </li></ul><ul><li></xi:fallback> </li></ul><ul><li></xi:include> </li></ul>
    66. 66. Modular DocBook files - using XInclude (fallback mechanism) <ul><li>xi:fallback element can contain another xi:include , which the processor will try to resolve as a secondary resource. The secondary include can also contain a secondary fallback, and so on. </li></ul><ul><li>Processing of a document does not stop when an XInclude cannot be resolved and it has a fallback child, even if that child is empty. </li></ul><ul><li>Usage guideline - If you want your processing to always continue regardless of how the includes resolve, then add a fallback element to all of your XInclude elements. Otherwise, do not use fallback elements on the innermost includes and let the processing fail. </li></ul>
    67. 67. Modular DocBook files - using XInclude (entities for filenames) <ul><li>XIncludes are intended to replace SYSTEM entities but it’s still possible to use regular entities with XInclude. </li></ul><ul><li>Typical usage : One can declare regular entities for filenames in a file's DOCTYPE declaration, and subsequently use an entity reference in the href attribute of an XInclude element. That allows us to more easily manage various file includes instead of scattering them throughout. </li></ul><ul><li>See the example. </li></ul>
    68. 68. Modular DocBook files - using Olink <ul><li>Steps to form cross linking between documents using ‘olinks’ </li></ul><ul><li>Identify the documents that have to be included in the domain for cross referencing and assign each of them a document id. </li></ul><ul><li>Insert an olink element in your document where a cross reference has to be formed to another document. </li></ul><ul><ul><li>An olink contains two attributes namely; ' targetptr ' and ' targetdoc '. ' targetdoc ' is the document id of the destination end of the link and ' targetptr ' is the xml:id value of the element in that target document. </li></ul></ul>
    69. 69. Modular DocBook files - using Olink <ul><li>In order to form cross references between documents in HTML, one must be aware of their relative locations . </li></ul><ul><li>Create a master target database document for the collection that resolves all olinks for every document in the collection. </li></ul><ul><li>Since all the document data is gathered dynamically, the target database document is authored manually and is static, except for changes to the collection. </li></ul>
    70. 70. Modular DocBook files - using Olink <ul><li>For each document in the collection, generate a data file that contains all the potential cross reference targets. It is accomplished by processing the document using regular DocBook XSL stylesheet but with an additional collect.xref.targets parameter. See an example below that should generate in the current directory a target data file, named target.db by default </li></ul><ul><ul><li>xsltproc </li></ul></ul><ul><ul><li>--stringparam collect.xref.targets &quot;only&quot; </li></ul></ul><ul><ul><li>docbook.xsl </li></ul></ul><ul><ul><li>userguide.xml </li></ul></ul>
    71. 71. Modular DocBook files - using Olink <ul><li>Process each document to generate its output using the normal XSL DocBook stylesheet with an additional parameter which is the database filename. </li></ul><ul><li>xsltproc --output /http/guides/mailuser/userguide.html </li></ul><ul><li>--stringparam target.database.document &quot;olinkdb.xml&quot; </li></ul><ul><li>--stringparam current.docid &quot;MailUserGuide&quot; </li></ul><ul><li>docbook.xsl userguide.xml </li></ul>
    72. 72. DocBook 5 <ul><li>DocBook 5 is the next generation of DocBook that significantly changes the foundation on which DocBook is based. </li></ul><ul><li>The version 5.0 (under active development) is a complete rewrite of DocBook in RELAX NG. </li></ul><ul><li>The Technical Committee has simplified a number of content models and tightened constraints where RELAX NG makes them possible. </li></ul><ul><li>The Technical Committee provides the DocBook 5.0 schema in other schema languages, including W3C XML Schema and an XML DTD, but the RELAX NG Schema is the normative schema. </li></ul>
    73. 73. DocBook 5 <ul><li>All element in DocBook 5 are defined in the namespace </li></ul><ul><li>In DocBook 4.x, only a few elements like link and xref were used to form links. In DocBook 5, most elements that generate some output can be made into a link with a set of attributes that are defined in the XLink namespace. The link can go to an internal or external destination. Also, the id attribute is replaced with the xml:id attribute. </li></ul>
    74. 74. DocBook 5 <ul><li>In DocBook 5, elements from DocBook 4 such as bookinfo, chapterinfo, sectioninfo , etc. are all replaced by a single info element. </li></ul><ul><li>RelaxNG permits an element to have a different content model when the element appears in a different context. </li></ul><ul><li>For example, the DocBook 5 info element in book can contain a title , but the info element in para cannot. </li></ul>
    75. 75. DocBook 5 <ul><li>DocBook 5 has a new system for associating annotations with elements. It defines two new elements namely; </li></ul><ul><ul><li>alt for short description </li></ul></ul><ul><ul><li>annotation for an arbitrarily complex description. </li></ul></ul><ul><li>Example of alt </li></ul><ul><li><mediaobject> </li></ul><ul><li><alt>mouse buttons</alt> </li></ul><ul><li><imageobject> </li></ul><ul><li><imagedata fileref=&quot;mouse.png&quot;/> </li></ul><ul><li></imageobject> </li></ul><ul><li></mediaobject> </li></ul>
    76. 76. DocBook 5 <ul><li>Annotation meets the needs when alt is limited. An annotation element's content can be any mix of DocBook block elements. </li></ul><ul><li>An annotation is associated with an element using attributes, not by placement. Specifically : </li></ul><ul><ul><li>An annotates attribute on an annotation element matches the value of the xml:id of the element it is annotating. </li></ul></ul><ul><ul><li>An annotations attribute on any element matches the value of the xml:id of an annotation element associated with it. </li></ul></ul><ul><li>Both attributes accept multiple space-separated values. One can assign a role attribute to an annotation to identify it as a certain kind of annotation. There are no predefined role values. </li></ul>
    77. 77. Industry's trend : WYSIWYG XML Editing
    78. 78. Introduction to WYSIWYG <ul><li>WYSIWYG - What You See Is What You Get </li></ul>
    79. 79. Introduction to WYSIWYG <ul><li>Problem – Often, ones who maintain the content of a web-site (typically through a WCM in a large corporation) have beginners knowledge of a web-developer. </li></ul><ul><li>One of the elegant solutions – To provide the company with a browser based WYSIWYG editor similar to Microsoft's FrontPage or Adobe's Dreamweaver. </li></ul>
    80. 80. What is a WYSIWYG ? <ul><li>WYSIWYG implies a user interface that allows the user to view something very similar to the end result while the document is under creation. </li></ul><ul><li>WYSIWYG encompasses the user interfaces in </li></ul><ul><ul><li>Presentation programs, Word Processing applications and Desktop Publishing applications for Compound documents (including web pages) </li></ul></ul><ul><ul><li>3D computer graphics or 3D models in computer-aided design. </li></ul></ul>
    81. 81. Support for WYSIWYG in web browsers <ul><li>Internet Explorer 5 and later supports a set of commands to facilitate complete browser based content creation. </li></ul><ul><li>Firefox also provides WYSIWYG widgets within Web CMS systems using Mozilla's &quot;extensions&quot; paradigm as well as its API facilities. Please follow this link for more information . </li></ul>
    82. 82. Support for WYSIWYG in operating systems <ul><li>Mac OS X and all higher versions support unconstrained glyph placement. </li></ul><ul><li>Applications for Microsoft windows that use the windows presentation foundation (included with the OS since windows vista), may also freely place glyphs. </li></ul><ul><li>By default, the positioning and spacing of glyphs on-screen will exactly match the printed documents. </li></ul>
    83. 83. WYSIWYG XML editors <ul><li>Author mode of the < oXygen /> XML Editor </li></ul><ul><li>Adobe FrameMaker </li></ul><ul><li>Syntext Serna Enterprise WYSIWYG XML editor </li></ul><ul><li>Web based editors </li></ul><ul><li>BXE (open source) </li></ul><ul><li>Xopus (proprietary) </li></ul>
    84. 84. <ul><li>Xopus is a WYSIWYG XML Editor that runs in web-browsers (Firefox and Internet explorer). It presents the author with a friendly interface to structured and complex XML content where the author cannot break the XML structure or write content that does not conform to the XML Schema. </li></ul><ul><li>Quality and consistency of xml documents can be controlled as they could be necessitated to conform to enterprise standards such as DITA and DocBook. </li></ul>Xopus – An WYSIWYG XML editor
    85. 85. Xopus – An WYSIWYG XML editor <ul><li>As it's based on popular open standards such as XML, XML Schema, XSLT, Javascript and CSS stylesheets, it is easy to integrate Xopus into web server environments and content management systems. </li></ul><ul><li>It supports rich copy-paste from applications, such as Microsoft Word and Open Office, change tracking, spell checking and multi-lingual support in the user interface. </li></ul>
    86. 86. Demo
    87. 87. The road ahead <ul><li>Parsing and publishing DocBook documents </li></ul><ul><li>Customising DocBook documents </li></ul>
    88. 88. Time to answer your questions