0
Introduction
  Starting with Docbook
         Advanced usage




An introduction to Docbook
      Master on Free Software
...
Introduction
                             Starting with Docbook
                                    Advanced usage




   ...
Introduction
                    Starting with Docbook
                           Advanced usage


Summary




    Introdu...
Introduction
                    Starting with Docbook
                           Advanced usage


What are SGML and XML?
...
Introduction
                   Starting with Docbook
                          Advanced usage


Objectives


  Docbook:
 ...
Introduction
                   Starting with Docbook
                          Advanced usage


Docbook
  What is Docbook...
Introduction
                     Starting with Docbook
                            Advanced usage


Docbook (II)


  Curr...
Introduction
                    Starting with Docbook
                           Advanced usage


The Environment


  Bef...
Introduction
                            Starting with Docbook
                                   Advanced usage


Docbook...
Introduction
                    Starting with Docbook
                           Advanced usage


Compile your book!

  E...
Introduction
                   Starting with Docbook
                          Advanced usage


Compile your book! (alter...
Introduction
                  Starting with Docbook
                         Advanced usage


Docbook XML basics



     ...
Introduction
                    Starting with Docbook
                           Advanced usage


The Docbook documents

...
Introduction
                            Starting with Docbook
                                   Advanced usage


The boo...
Introduction
                  Starting with Docbook
                         Advanced usage


The article document

  <?x...
Introduction
                            Starting with Docbook
                                   Advanced usage


Typical...
Introduction
                     Starting with Docbook
                            Advanced usage


Typical article conte...
Introduction
                   Starting with Docbook
                          Advanced usage


Typical article contents
...
Introduction
                  Starting with Docbook
                         Advanced usage


Simple lists

  Simple list...
Introduction
                Starting with Docbook
                       Advanced usage


Descriptions


  <variablelist>...
Introduction
                  Starting with Docbook
                         Advanced usage


Other block elements



   ...
Introduction
                    Starting with Docbook
                           Advanced usage


Elements within a line
...
Introduction
                            Starting with Docbook
                                   Advanced usage


Tables
...
Introduction
                Starting with Docbook
                       Advanced usage


Figures



  <mediaobject>
    ...
Introduction
                  Starting with Docbook
                         Advanced usage


Formal figures and tables

 ...
Introduction
                            Starting with Docbook
                                   Advanced usage


Bibliog...
Introduction
                    Starting with Docbook
                           Advanced usage


Entities
      Entities...
Introduction
                    Starting with Docbook
                           Advanced usage


Exercise


      Using ...
Upcoming SlideShare
Loading in...5
×

An introduction to Docbook

2,569

Published on

Published in: Technology, News & Politics
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,569
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
56
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Transcript of "An introduction to Docbook"

  1. 1. Introduction Starting with Docbook Advanced usage An introduction to Docbook Master on Free Software Juanjo Amor jjamor@gsyc.escet.urjc.es GSyC/Libresoft October 25th 2007 Juanjo Amor An introduction to Docbook
  2. 2. Introduction Starting with Docbook Advanced usage (cc) 2007 Juanjo Amor Some rights reserved. This work licensed under Creative Commons Attribution-ShareAlike License. To view a copy of full license, see http://creativecommons.org/licenses/by-sa/2.0/ or write to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. Juanjo Amor An introduction to Docbook
  3. 3. Introduction Starting with Docbook Advanced usage Summary Introduction. Starting with Docbook. “Advanced” usage. Juanjo Amor An introduction to Docbook
  4. 4. Introduction Starting with Docbook Advanced usage What are SGML and XML? Some characteristics... SGML and XML are “markup languages”. HTML, the language used in web pages, is a subset of SGML. Markup languages? Provide a way to combine text and extra information about it. The extra information is expressed through a “markup”. The extra information covers from character aspect (ex: bold, italic) to structure, layout or meta-data. DTD: Document Type Definition The “schema” for defining a particular set of markups in the markup language. For us, Docbook is a DTD of SGML or XML for writing technical documents. Juanjo Amor An introduction to Docbook
  5. 5. Introduction Starting with Docbook Advanced usage Objectives Docbook: A DTD for writing technical documents in SGML or XML. Defacto standard for technical documentation in a wide range of FLOSS projects. Objectives: To know the Docbook concepts. To have the abilities to write Docbook/XML documents. To know the software needed for compiling Juanjo Amor An introduction to Docbook
  6. 6. Introduction Starting with Docbook Advanced usage Docbook What is Docbook? DocBook is a markup language for technical documentation. Of course it can be used for other type of documentation. Benefits: Users can create document content in a presentation-neutral form that captures the logical structure of the content. Content can be published in a variety of formats (HTML, PDF, RTF, man pages, etc), by using some tools. Who created Docbook? 1991: Some companies (O’Reilly, Hal Computer Systems) proposed first versions. Later moved to the SGML Open Consortium. Currently maintained by OASIS (Organization for the Advancement of Structured Information Standards). Juanjo Amor An introduction to Docbook
  7. 7. Introduction Starting with Docbook Advanced usage Docbook (II) Current Docbook: Currently: Version 4.5. Next release: Version 5. Publication planned for November 2007. Documentation: There is a lot of documentation about Docbook. However, the main reference is: N. Walsh, L. Muellner. “Docbook. The Definitive Guide”. O’Reilly & Associates, 1999. Main references available at: http://www.docbook.org/ Juanjo Amor An introduction to Docbook
  8. 8. Introduction Starting with Docbook Advanced usage The Environment Before more acronyms, let’s start with Docbook. What do we need? An editor. Forget WYSIWYG. Use emacs or bluefish (or whatever you prefer). A set of tools. Exercise: Install and test bluefish. Verify the installation of docbook tools (SGML). Install XMLTO and FOP. Juanjo Amor An introduction to Docbook
  9. 9. Introduction Starting with Docbook Advanced usage Docbook example <?xml version=quot;1.0quot; encoding=quot;UTF-8quot; ?> <!DOCTYPE book PUBLIC quot;-//OASIS//DTD Docbook XML V4.5//ENquot; quot;file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtdquot;> <book lang=quot;enquot;> <bookinfo> <title>My first book written in Docbook</title> <author> <firstname>John</firstname> <surname>Smith</surname> </author> </bookinfo> <chapter> <title>Preface</title> <para> Welcome to my first document in Docbook. </para> </chapter> </book> Juanjo Amor An introduction to Docbook
  10. 10. Introduction Starting with Docbook Advanced usage Compile your book! Exercise: Compile it as HTML. Compile it as HTML in one file. Compile it as PDF. Typical output without errors (but warnings): $ xmlto fo prueba.xml Making portrait pages on USletter paper (8.5inx11in) $ /opt/fop-0.94/fop -fo prueba.fo -pdf prueba.pdf Oct 21, 2007 7:57:53 PM org.apache.fop.hyphenation.Hyphenator getHyphenationTree SEVERE: Couldn’t find hyphenation pattern en Juanjo Amor An introduction to Docbook
  11. 11. Introduction Starting with Docbook Advanced usage Compile your book! (alternate method) Exercise: Download db2latex.xml Follow teacher instructions. Examine the output. Conclusions? Juanjo Amor An introduction to Docbook
  12. 12. Introduction Starting with Docbook Advanced usage Docbook XML basics All markups are case-sensitive. All markups must be written in lowercase. Attribute values must be quoted with a quote (’ or quot;). Processing instructions begin and end with question mark: <?pitarget data> Empty elements: </xref> Juanjo Amor An introduction to Docbook
  13. 13. Introduction Starting with Docbook Advanced usage The Docbook documents Docbook documents we will write: Books. A book consists of one preface, several chapters. Articles. An article consists of several sections. Sections can be nested. There are other optional or mandatory elements to be included into a book or an article. Exercise: Learn to look for a Docbook element in the reference. See the elements of a book and an article. Juanjo Amor An introduction to Docbook
  14. 14. Introduction Starting with Docbook Advanced usage The book document <?xml version=quot;1.0quot; encoding=quot;UTF-8quot; ?> <!DOCTYPE book PUBLIC quot;-//OASIS//DTD Docbook XML V4.5//ENquot; quot;file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtdquot;> <book lang=quot;enquot;> <bookinfo> <title>My first book written in Docbook</title> <author> <firstname>John</firstname> <surname>Smith</surname> </author> </bookinfo> <chapter> <title>Preface</title> <para> Welcome to my first document in Docbook. </para> <section> <title>Section title</title> <para>We can divide a chapter in sections</para> </section> </chapter> </book> Juanjo Amor An introduction to Docbook
  15. 15. Introduction Starting with Docbook Advanced usage The article document <?xml version=quot;1.0quot; encoding=quot;UTF-8quot; ?> <!DOCTYPE article PUBLIC quot;-//OASIS//DTD Docbook XML V4.5//ENquot; quot;file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtdquot;> <article lang=quot;enquot;> <artheader> <title>My Article</title> <author><honorific>Dr</honorific> <firstname>Emilio</firstname> <surname>Lizardo</surname></author> </artheader> <para> ... </para> <sect1><title>On the Possibility of Going Home</title> <para> ... </para> </sect1> <bibliography> ... </bibliography> </article> Juanjo Amor An introduction to Docbook
  16. 16. Introduction Starting with Docbook Advanced usage Typical article contents Authorship: <article lang=quot;esquot;> <articleinfo> <title>My article</title> <date>April 2005</date> <authorgroup> <author> <firstname>Juan J.</firstname> <surname>Amor Iglesias</surname> </author> <author> <firstname>Gregorio</firstname> <surname>Robles Mart&iacute;nez</surname> </author> </authorgroup> </articleinfo> ... </article> Juanjo Amor An introduction to Docbook
  17. 17. Introduction Starting with Docbook Advanced usage Typical article contents Nested sections: ... </articleinfo> <section> <title>Main section</title> <para> Paragraph in main section </para> <para>...</para> <section> <title>A subsection</title> <para>...</para><para>...</para><para>...</para> </section> </section> ... Juanjo Amor An introduction to Docbook
  18. 18. Introduction Starting with Docbook Advanced usage Typical article contents Sections: <sect1>, <sect2>, <sect3>... Other: <appendix>, <glossary>, <bibliography>... See: http://www.docbook.org/tdg/en/html/article.html Exercise: Look to the previous URL. See the accepted elements as children and parents. See the examples. Juanjo Amor An introduction to Docbook
  19. 19. Introduction Starting with Docbook Advanced usage Simple lists Simple list: <itemizedlist> <listitem><para>First element</para></listitem> <listitem><para>Second element</para></listitem> </itemizedlist> Ordered list: <orderededlist> <listitem><para>First element</para></listitem> <listitem><para>Second element</para></listitem> </orderededlist> Juanjo Amor An introduction to Docbook
  20. 20. Introduction Starting with Docbook Advanced usage Descriptions <variablelist> <listitem> <term>Potato</term> <para>An edible tuber native to South America.</para> </listitem> <listitem> <term>Tomato</term> <para>Mildly acid red or yellow pulpy fruit eaten as a vegetable.</para> </listitem> </variablelist> Juanjo Amor An introduction to Docbook
  21. 21. Introduction Starting with Docbook Advanced usage Other block elements Listings: programlisting, screen, literallayout. Warns: caution, important, note, tip, warning. Comments: remark. blockquote, procedure, qandaset... Footnotes: footnote. Exercise: See each element into the reference. Look to the parent and children elements. Look to the examples. Juanjo Amor An introduction to Docbook
  22. 22. Introduction Starting with Docbook Advanced usage Elements within a line Emphasis: emphasis, literal, quote. Commands: filename, command, option, parameter. Internal references: For more information, please see <xref linkend=quot;more1quot;/> ... <section id=quot;more1quot;> <title>The other section</title> <para> ..... External (URI) references: <ulink url=quot;http://curso-sobre.berlios.dequot;>FLOSS course</ulink> Juanjo Amor An introduction to Docbook
  23. 23. Introduction Starting with Docbook Advanced usage Tables <informaltable> <tgroup cols=quot;3quot;> <colspec align=quot;leftquot; colnum=quot;1quot; colwidth=quot;2*quot;/> <colspec align=quot;leftquot; colnum=quot;2quot; colwidth=quot;1*quot;/> <colspec align=quot;justifyquot; colnum=quot;3quot; colwidth=quot;4*quot;/> <thead> <row> <entry>Concept</entry> <entry>Hours</entry> <entry>Content</entry> </row> </thead> <tbody> <row> <entry>Introduction</entry> <entry>20</entry> <entry> Introduction to <emphasis>Software Engineering</emphasis>, blah blah </entry> </row> ... </tbody> <tgroup> </informaltable> Juanjo Amor An introduction to Docbook
  24. 24. Introduction Starting with Docbook Advanced usage Figures <mediaobject> <imageobject> <imagedata scale=quot;80quot; fileref=quot;figures/ccby.pngquot; format=quot;EPSquot; /> </imageobject> </mediaobject> Juanjo Amor An introduction to Docbook
  25. 25. Introduction Starting with Docbook Advanced usage Formal figures and tables <figure id=quot;img1quot;> <title>Figure caption</title> <mediaobject> <imageobject><imagedata fileref=quot;img.pngquot;/></imageobject> </mediaobject> </figure> <table id=quot;tbl1quot;> <title>Table caption</title> <tgroup cols=quot;2quot;> <tbody> <row><entry>xxx</entry><entry>yyy</entry></row> <row><entry>zzz</entry><entry>ttt</entry></row> </tbody> </tgroup> </table> Juanjo Amor An introduction to Docbook
  26. 26. Introduction Starting with Docbook Advanced usage Bibliography ... IP telephony<citation>HGP2003</citation> ... <bibliography> <title>Bibliography</title> <biblioentry><abbrev>HGP2000</abbrev> <title>IP Telephony. Packet-based multimedia communications systems.</title> <authorgroup> <author><firstname>Olivier</firstname><surname>Hersen</surname></author> <author><firstname>David</firstname><surname>Gurle</surname></author> <author><firstname>Jean-Pierre</firstname><surname>Petit</surname></author> </authorgroup> <pubdate>2000</pubdate> <publisher><publishername>Addison Wesley</publishername></publisher> </biblioentry> ... </biblography> Juanjo Amor An introduction to Docbook
  27. 27. Introduction Starting with Docbook Advanced usage Entities Entities allow you to assign a name to some chunk of data, and use that name to refer to that data. Two main types: General and Parameter entities. Parameter entities are most often used in the DTD. General entities: Internal general entities: <!ENTITY ora quot;O’Reilly &amp; Associatesquot;> External general entities: <!ENTITY ch01 SYSTEM quot;ch01.sgmquot;> One can refer to a general entity using a character reference in the text. For example: &ora; and &ch01;. The effect of referring to an internal entity is the expansion of its value. The effect of referring to an external entity is the file inclusion. Other uses of character entities: national characters: Espa&ntilde;a. Juanjo Amor An introduction to Docbook
  28. 28. Introduction Starting with Docbook Advanced usage Exercise Using the editor, you should write a Docbook document (article) including all elements seen in the paper. Elements to include: Authorship data. The abstract. The sections. Use for the text, as many elements as possible (ex: itemized lists, references, etc). Compile, and control the errors. Produce an HTML output and a PDF. See the results. Juanjo Amor An introduction to Docbook
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×