AAF: AAOBloggers

:)

Documenting your projects with DOCBOOK

with 5 comments

click on three links bellow then click around:
bash
secure programming
Docbook

if you did click around, you would have probably noticed something; all the documents are presented in a consistent way even though they where written by deferent people, living in deferent places.
if you were adventurous, and went up a few directories you might have noticed that each document had a pdf version, and that each pdf of the three was organized in the same way as the other.
can it be that each writer thinks in the exact same way? i think not.. at least i hope not.
the tool behind producing these online/offline documents is ether Docbook or LaTex. this article discusses Docbook, an schema (XML or SGML) developed to facilitate documenting software or hardware. However, it is not limited to these two fields. in fact, it can be used to document anything.
Docbook focuses on content structure rather then appearance. this – in my opinion – is what makes Docbook so great. instead of using open office and constantly indenting, changing fonts, spacing paragraphs, and so on, i can focus on what is more important: what i’m actually writing!
the following docbook code:

<book>
<bookinfo>
<title>My software is the COOLEST</title>
<authorgroup>
<author>
<firstname>Sulaiman</firstname>
<othername>A.</othername>
<surname>Mustafa</surname>
</author>
</authorgroup>
</bookinfo>
<chapter id="Introduction">
<title>Introduction: Installing and Starting</title>
<para>
This program is written in python and requires a python iterpitor along
with the standared module library to run. the version used is 2.6.1, and
other versions might not be compatable. to istall simply copy the archive to the desired directory. to start the program, you have two
options; first, you can start the script directly by issuing the following command:
(while in the same directory)
<example>
<title> Starting the program </title>
<programlisting>
./ConfParse.py
</programlisting>
</example>
of course youm may also start it by suppling it as an agument to a pthon interptor.
<warning><para>This software was written with python 2.6.1, using ether older versions or newer ones might <emphasis>break</emphasis> the program!</para></warning>
</para>
</chapter>
</book>

should give:

screenshot1

note that docbook can save in many deferent styles and formats. for more information, you may want to look at this.

SIGTERMer

Advertisements

Written by seininn

April 13, 2009 at 6:52 am

5 Responses

Subscribe to comments with RSS.

  1. u just had to right a half page post and send my post to the other half page….u just had to,right?

    bone-crusher

    April 13, 2009 at 11:06 am

  2. oh my.. you actually figured out my plan!!!

    sigtermer

    April 13, 2009 at 11:19 am

  3. dude I know u so much that I’ll figured out everything ur planning to do. so don’t try anything stupid OK 🙂

    bone-crusher

    April 14, 2009 at 12:40 pm

  4. after i finished reading this post I remembered you saying “you might have noticed that each document had a pdf version, and that each pdf of the three was organized in the same way as the other.” and never mentioned how PDFs are made all alike. So do you mean we can make then using Docbook then convert them into PDFs or what? How are they made?

    Anxious Nut

    April 16, 2009 at 2:05 pm

  5. read my friend.. read 🙂
    docbook is “an schema (XML or SGML) developed to facilitate documenting software or hardware”. this means that it is a way to describe your document.

    @ Anxious: “how PDFs are made all alike”
    docbooks are generated by using XSL stylesheets. these style sheets are what makes each generated document (be it pdf or html) look and behave in a consistent way.

    the finished products are generated by passing your docbook source file to tools that use the stylesheets to produce the foo (pdfs) or html code.

    if that’s not enough for you, you can.. read! after all i’m new comer to docbook, just like you.

    sigtermer

    April 16, 2009 at 5:38 pm


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: