• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
An introduction to Docbook
 

An introduction to Docbook

on

  • 3,807 views

 

Statistics

Views

Total Views
3,807
Views on SlideShare
3,802
Embed Views
5

Actions

Likes
3
Downloads
53
Comments
0

1 Embed 5

http://www.slideshare.net 5

Accessibility

Upload Details

Uploaded via as Adobe PDF

Usage Rights

CC Attribution-ShareAlike LicenseCC Attribution-ShareAlike License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    An introduction to Docbook An introduction to Docbook Presentation Transcript

    • 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
    • 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
    • Introduction Starting with Docbook Advanced usage Summary Introduction. Starting with Docbook. “Advanced” usage. Juanjo Amor An introduction to Docbook
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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