docs: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 هكذا

<?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

ترجمة كتب docbook إلى العربية وإخراجها

أولا يتم توليد قالب الترجمة 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

مراجع خارجية

نقاش

ورقة, 2009/02/14 07:01

ما الهدف الأساسي الذي يجعلنا نستخدم هذه الطريقة في كتابة الوثائق بدلا من الطرق الأخرى ؟

مؤيد السعدي, 2009/02/14 10:48

سأكتب عن ذلك قريبا لكن باختصار في هذه الهيئة أنت لا تقوم بالتنسيق يعني لا تقول هذا أسور وهذا رمادي وذاك عريض … بل تقول هذا اسم برنامج وذاك مفتاح وتلك معادلة وذاك أمر

يعني أنت لا تقوم بالتنسيق أنت فقط تركز على شرح أفكارك

djilani sm, 2009/02/19 20:32

هذا خارج عن الموضوع

ولكن أظن أن هذه الطريقة (أقصد استخدام ملفات xml لوصف المحتوى) هي المتبعة في موسوعة microsoft encarta. حيث تستعمل ملفات xml لتخزين البيانات وملفات xsl لعرض المحتوى.

Lina, 2011/11/02 03:06

Great stuff, you helepd me out so much!

Dyogenes, 2012/02/11 06:07

This info is the cat's pjaaams!

jzimanodbye, 2012/02/15 10:46

J8MvR7 , [url=http://rmxflvnkqmdf.com/]rmxflvnkqmdf[/url], [link=http://kvnycvygdsct.com/]kvnycvygdsct[/link], http://gjqvxoyheqpp.com/

Murat, 2012/03/06 09:04

I found just what I was needed, and it was enteartninig!

Blinda, 2012/07/30 04:13

This is just the prefcet answer for all of us

Tetris, 2012/08/27 02:29

You raelly saved my skin with this information. Thanks!

Vinny, 2012/09/04 01:50

Wow I must confess you make some very trechnant points.

Boss, 2012/09/11 22:34

Was totlaly stuck until I read this, now back up and running.

Lanette, 2012/09/28 03:52

Phenomenal breadkown of the topic, you should write for me too!

Abuzer, 2012/10/06 01:23

Lot of samtrs in that posting!

Jeslyn, 2012/11/13 05:06

If you're raendig this, you're all set, pardner!

Kelenna, 2012/11/13 08:20

This was so helpful and easy! Do you have any aritcles on rehab?

Caden, 2012/11/13 08:25

Hot damn, looking pretty usfuel buddy.

dbdmjj, 2012/11/14 04:42

iYXCMe , [url=http://ilhkuydqfgbi.com/]ilhkuydqfgbi[/url], [link=http://ttjtduqrueoz.com/]ttjtduqrueoz[/link], http://hzletarqbpee.com/

Sequoia, 2013/01/20 10:09

This article is a home run, pure and simlpe!

Miguel, 2013/01/29 18:32

That's an astute answer to a tricky quseiton

jjomsxefy, 2015/04/23 23:31

كتابة وثائق docbook [أعجوبة] jjomsxefy http://www.g0kyi2t968qz6cupot70x39z01ce9430s.org/ [url=http://www.g0kyi2t968qz6cupot70x39z01ce9430s.org/]ujjomsxefy[/url] <a href=“http://www.g0kyi2t968qz6cupot70x39z01ce9430s.org/”>ajjomsxefy</a>

趙明, 2015/04/25 03:59

hi it's good posting. 趙明 http://www.okgo001.com

Disney's World Family, 2015/04/25 04:01

hi that's good posting. Disney's World Family http://www.xyz11.info/xyz/EDU0727-70.html

xyz軟體, 2015/04/25 04:01

Is that true? Ill spread this information. Anyway, good posting. xyz軟體 http://104.copy-game.cc

命題光碟, 2015/04/25 04:01

Is that true? Ill spread this information. Anyway, nice posting. 命題光碟 http://104.xyz2016.info

高登, 2015/04/25 04:01

Is that true? Ill spread this information. Anyway, good posting. 高登 http://www.so-net.xyz

陳光數學, 2015/04/25 04:01

hi it's nice posting. 陳光數學 http://www.xyzdvd.net/xyz/SCHD0596-35.html

題庫光碟, 2015/04/25 04:01

Is that true? Ill spread this information. Anyway, good posting. 題庫光碟 http://104.gotodvd.tw

特招, 2015/04/25 04:01

Is that true? Ill spread this information. Anyway, nice posting. 特招 http://104.dbt.tw

數學科, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 數學科 http://104.xyz2013.info

102學年度, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 102學年度 http://gotodvd.tw

南一版, 2015/04/25 04:02

hello it's nice posting. 南一版 http://104.xyz2012.info

康熹版, 2015/04/25 04:02

hello it's good posting. 康熹版 http://www.seednet.info

103學年度, 2015/04/25 04:02

hi that's good posting. 103學年度 http://104.xyz11.info

翰林版, 2015/04/25 04:02

hello it's nice posting. 翰林版 http://104.xyz168.info

八字, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, good posting. 八字 http://104.copy-dvd.cc

數學, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 數學 http://104.xyz22.info

翰林, 2015/04/25 04:02

hi it's good posting. 翰林 http://www.dbt.xyz

翰林, 2015/04/25 04:02

hi it's nice posting. 翰林 http://104.xyzs.info

黃勝德, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 黃勝德 http://104.xyz2019.info

Android, 2015/04/25 04:02

hello that's nice posting. Android http://www.seednet.xyz

迪士尼美語世界, 2015/04/25 04:02

hello it's good posting. 迪士尼美語世界 http://www.gotodvd.tw/xyz/EDU0727-70.html

國小, 2015/04/25 04:02

hello it's nice posting. 國小 http://www.copy-dvd.cc

康軒, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, good posting. 康軒 http://104.xyz66.info

研究所, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, good posting. 研究所 http://104.xyz886.info

國家考試, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 國家考試 http://104.xyz168.net

國寰宇迪士尼美語世界, 2015/04/25 04:02

hi it's good posting. 國寰宇迪士尼美語世界 http://www.xyzs.info/xyz/EDU0727-70.html

南一版, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, good posting. 南一版 http://www.okgame.org

102學年度, 2015/04/25 04:02

hello that's nice posting. 102學年度 http://dbt.tw

姓名學, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 姓名學 http://104.dbt.xyz

國中, 2015/04/25 04:02

Is that true? Ill spread this information. Anyway, nice posting. 國中 http://ok.gotodvd.tw

翰林, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, nice posting. 翰林 http://104.xyz2009.tw

蘇捷魁老師, 2015/04/25 04:03

hello that's good posting. 蘇捷魁老師 http://104.xyz2020.info

特招, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, nice posting. 特招 http://www.xyz2009.com.tw/tag/TKB

林晟, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, good posting. 林晟 http://104.xyz2015.info

103學年度, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, nice posting. 103學年度 http://104.xyz2011.info

PDF電子書, 2015/04/25 04:03

hi that's nice posting. PDF電子書 http://104.xyz789.net

平面設計, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, nice posting. 平面設計 http://104.xyz2009.com.tw

dvd, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, good posting. dvd http://104.xyzdvd.net

國文科, 2015/04/25 04:03

Is that true? Ill spread this information. Anyway, nice posting. 國文科 http://104.xyz2017.info

翰林版, 2015/04/25 04:04

hello it's good posting. 翰林版 http://104.xyz2018.info

教學, 2015/04/25 04:04

Is that true? Ill spread this information. Anyway, good posting. 教學 http://104.xyz2010.info

翰林, 2015/04/25 04:04

hello it's nice posting. 翰林 http://104.xyz2014.info

أدخل تعليقك:
 
آخر تعديل:: 23 نيسان 2015 الساعة 00:19 (تحرير خارجي)