كتابة وثائق docbook

رغم الشبه الكبير بين docbook والكثير من منافسيها مثل html إلا أن الأولى تصف المحتوى ولا تصف المظهر. أي أن الكاتب يركز على المحتوى وعلى شرح أفكاره دون أن يهتم كيف سيتم تنسيقها أو عرضها. يعني إذا كنت تريد إخراج المستند على ورق أو ليكون ملف مساعدة آنية أو موقع على الويب لا فرق المهم أنك تصف المحتوى.

هيئة docbook تعتمد على xml وتستفيد من كل مزاياها حيث هناك العديد من الأدوات العامة يمكن استخدامها في التحقق من سلامة الوثيقة validate أو في إخراج الوثيقة إلى هيئة عرض presentation format مثل html أو odt أو fo وبالتالي PDF

هناك العديد من الأدوات لكننا سنركز على

• xsltproc - وهو برنامج يقوم بتحويل ملف xml إلى أي هيئة أخرى عبر xsl tansformation
• حزمة docbook-style-xsl وهي تحتوي على ملفات xsl التي يستعملها البرنامج السابق لتحويل docbook إلى أي هيئة أخرى. الإصدارات القديمة لا تدعم ثنائية الاتجاه اللازمة للغة العربية لذا إما أن تستعمل هذه الحزمة من أعجوبة لينكس 2 أو أن تحصل عليها من http://docbook.sourceforge.net/snapshots/docbook-xsl-snapshot.zip
• xmllint - برنامج يعمل على التحقق من سلامة ملف xml
• ملفات rng أو DTD التي يستخدمها البرنامج السابق (اسم الحزمة docbook-dtds)
• وللترجمة تحتاج برنامج xml2po من حزمة gnome-doc-utils وأوامر التعامل مع ملفات po من حزمة gettext

يبدأ ملف xml هكذا

<?xml version="1.0" encoding="UTF-8" standalone="no"?> 

وبعدها نحدد نوع الوثيقة مثلا الإصدار 4.4 من docbook هكذا

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

ثم نبدأ بوضع راقمات tags الوثيقة كأن نحدد أننا نكتب كتاب book أو مقالة article هكذا

<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="myarticle" lang="ar_JO">
<!--//  إلى آخر المقالة  //-->
</article>

كل راقمة تأتي بين علامتي أصغر وأكبر وتحتاج إلى إغلاق عند انتهاء محتوياتها.

لاحظ تحديد اللغة بأنها العربية وهذا ضروري حتى يتم التنسيق من اليمين إلى اليسار.

يفضل إعطاء الراقمات الأساسية للأبواب والفصول معرفات id

تستطيع عمل الفصول عبر section وإعطائها عنوان title ثم يلحق بها عدد من الفقرات

<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="myarticle" lang="ar_JO">
  <section id="mysection1">
    <title>عنوان الفصل الأول</title>
    <para>هذه هي الفقرة الأولى</para>
    <para>هذه هي الفقرة الثانية</para>
  </section>
  <section id="mysection2">
    <title>عنوان الفصل الثاني</title>
    <para>هذه هي الفقرة الأولى</para>
    <para>هذه هي الفقرة الثانية</para>
    <section id="mysubsection1">
      <title>عنوان فصل فرعي</title>
      <para>هذه الفقرة هي جزء من فصل فرعي داخل الفصل الثاني</para>
      <para>
        لمزيد من التفاصيل انظر 
        <xref linkend="mysection1"/>
      </para>
    </section>
  </section>
</article>

لاحظ طريقة عمل رابط للفصل الأول عبر xref وطريقة إغلاق الراقمة دون محتويات

قم بحفظ الملف باسم docbook-test.xml ثم اكتب

 xsltproc /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl docbook-test.xml > docbook-test.html

طبعا ضع المسار المناسب مكان /usr/share/sgml/docbook/xsl-stylesheets/

تستقبل xsl معاملات تسمى param (إذا كانت رقمية) أو stringparam (إذا كانت نصية) وتجد مرجعا كاملا بهذه المعاملات عبر الرابط http://docbook.sourceforge.net/release/xsl/current/doc/param.html وسنركز الآن على المعاملات الخاصة بتنسيق هيئة html في المرجع السابق http://docbook.sourceforge.net/release/xsl/current/doc/html/

من أهم تلك المعاملات

• html.cleanup تنظيف ملف html
• html.stylesheet تحدد ملف css الذي يعمل على تنسيق ملف html
• html.stylesheet.type نوع الملف السابق وطبعا يكون text/css
• formal.title.placement مكان ظهور العنوان أهو قبل أم بعد لكل من figure و example و equation و table و procedure
• admon.graphics تفعيل صور التحذيرات والتلميحات …
• admon.graphics.path المسار الذي تسبق به الصور السابقة

 xsltproc --xinclude \
  --param html.cleanup 1  \
  --stringparam html.stylesheet ojuba-rtl.css  --stringparam html.stylesheet.type text/css  \
  --stringparam formal.title.placement "figure after\nexample after\nequation afer\ntable after\nprocedure after"  \
  --param admon.graphics 1 --stringparam admon.graphics.path img/  \
  /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl  \
  docbook-test.xml > docbook-test.html

الخيار xinclude تم إضافته حتى يتم تفعيل هذه الميزة إن كانت مستخدمة في ملف xml

أولا يتم توليد قالب الترجمة pot عبر xml2po بالأمر

xml2po -e -o book.pot book.xml

وإذا كان هناك أكثر من ملف xml يحتوي كل واحد على فصل يجب تمريرها كلها إلى الأمر السابق ويمكن عمل ذلك باستعمال ‎ *.xml

وبعدها نحفظ ملف pot بامتداد po مثلا ar.po أو book.po في مجلد ar. ثم نقوم بترجمة الملف. وعند تحديث الملف الأصلي نعمل على تحديث الترجمة كما نفعل عند ترجمة البرامج عبر الأمر

msgmerge book.po book.pot

ولتوليد ملف xml مترجم

for i in *.xml; do xml2po -p ar.po -o "../ar/$i" "$i"; done

ولإخراج ملف xml المترجم إلى html مثلا نستخدم الطريقة السابقة عبر xsltproc

• http://xml.farsquare.com/
• http://www.itwadi.com/what_do_you_know_about_dockbook
• http://www.docbook.org/tdg/en/html/docbook.html
• http://nwalsh.com/docs/tutorials/xsl/xsl/slides.html
• http://www.sagehill.net/docbookxsl/index.html
• http://www.redhat.com/magazine/016feb06/features/docbook_xml/
• http://www.redhat.com/magazine/017mar06/features/docbook_xml/