اختلافات

عرض الاختلافات بين النسخة المختارة و النسخة الحالية من الصفحة.

--- docs:docbook [2009/02/19 22:23] – djilani
+++ docs:docbook [2015/04/23 03:19] (حالي) – تحرير خارجي 127.0.0.1
@@ سطر 1: / سطر 1: @@
+{{tag>مقالات توثيق docbook}}
+~~ODT~~
+====== كتابة وثائق docbook ======
+===== مقدمة =====
+==== لماذا 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 هكذا
+<code xml>
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+</code>
+وبعدها نحدد نوع الوثيقة مثلا الإصدار 4.4 من docbook هكذا
+<code xml>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+</code>
+ثم نبدأ بوضع راقمات tags الوثيقة كأن نحدد أننا نكتب كتاب book أو مقالة article هكذا
+<code xml>
+<?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>
+</code>
+كل راقمة تأتي بين علامتي أصغر وأكبر وتحتاج إلى إغلاق عند انتهاء محتوياتها.
+لاحظ تحديد اللغة بأنها العربية وهذا ضروري حتى يتم التنسيق من اليمين إلى اليسار.
+يفضل إعطاء الراقمات الأساسية للأبواب والفصول معرفات id
+تستطيع عمل الفصول عبر section وإعطائها عنوان title ثم يلحق بها عدد من الفقرات
+<code xml>
+<?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>
+</code>
+لاحظ طريقة عمل رابط للفصل الأول عبر xref وطريقة إغلاق الراقمة دون محتويات
+قم بحفظ الملف باسم docbook-test.xml ثم اكتب
+<code bash>
+ xsltproc /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl docbook-test.xml > docbook-test.html
+</code>
+طبعا ضع المسار المناسب مكان /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 المسار الذي تسبق به الصور السابقة
+<code bash>
+ 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
+</code>
+الخيار xinclude تم إضافته حتى يتم تفعيل هذه الميزة إن كانت مستخدمة في ملف xml
+===== ترجمة كتب docbook إلى العربية وإخراجها =====
+أولا يتم توليد قالب الترجمة pot عبر xml2po بالأمر
+<code bash>
+xml2po -e -o book.pot book.xml
+</code>
+وإذا كان هناك أكثر من ملف xml يحتوي كل واحد على فصل يجب تمريرها كلها إلى الأمر السابق ويمكن عمل ذلك باستعمال ‎ *.xml
+وبعدها نحفظ ملف pot بامتداد po مثلا ar.po أو book.po في مجلد ar.
+ثم نقوم بترجمة الملف. وعند تحديث الملف الأصلي نعمل على تحديث الترجمة كما نفعل عند ترجمة البرامج عبر الأمر
+<code bash>
+msgmerge book.po book.pot
+</code>
+ولتوليد ملف xml مترجم
+<code bash>
+for i in *.xml; do xml2po -p ar.po -o "../ar/$i" "$i"; done
+</code>
+ولإخراج ملف 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/