مساء الخير
كواحد من مطوري مشروع
Embox مفتوح المصدر ، كثيرا ما سمعت (في كثير من الأحيان في الآونة الأخيرة) أن المشروع مثير للاهتمام ، ولكن بما أنه لا توجد وثائق ، لا يمكن استخدامه. أجبنا أنه كان هناك نوع من الوثائق ، يمكننا دائمًا الإجابة على الأسئلة ، وأنه في الحالات القصوى ، يمكنك محاولة تحديد ذلك بمفردك ، لأن المشروع مفتوح ، لكن كل هذا لم يكن مناسبًا. اضطررت للتعامل مع هذا الموضوع غير سارة للغاية للمطورين. لكن بطبيعة الحال ، لا يتعلق المقال بحقيقة أن الوثائق "غير سارة"! وحول كيفية جعلنا عملية تطوير الوثائق أكثر راحة. في الواقع ، في أي مشروع كبير أو أقل ، تنشأ بالضرورة المسائل المتعلقة بالوثائق.
بالنسبة لأولئك الذين هم كسولون جدًا في القراءة ، سأقول على الفور أننا في النهاية وصلنا إلى تطوير الوثائق بتنسيق تخفيض السعر. حسنًا ، بالنسبة لأولئك المهتمين بالتفاصيل ، وأسباب تخفيض السعر ، وما هي إيجابيات وسلبيات هذا النهج ، أطلب القط.
سأبدأ بتبرير أهمية الموضوع. ليس فقط Embox لديه مشاكل الوثائق. على سبيل المثال ، أعلنت Google عن نسخة تماثلية لبرنامج Google Summer Of Code (GSOC) للكتاب التقنيين
Season of Docs . شركة كاسبرسكي لاب تعقد
مؤتمرات للكتاب التقنيين . وتقوم شركة Parallels بنشر
مقالات حول المحور حول كيفية كتابة الوثائق . كل هذا يشير إلى أن الموضوع مهم وربما حرم من الاهتمام بشكل غير مستحق.
تتفهم سلسلة المقالات المذكورة أعلاه المحتويات الصحيحة للوثائق ، لكنني أريد التركيز على عملية تطوير الوثائق والتكنولوجيا ، إذا كنت تريد ذلك. في الواقع ، بالنسبة لمشروع مفتوح المصدر ، السمة المميزة هي الانفتاح كخاصية لعملية التطوير. وأردنا إنشاء عملية تلبي متطلبات مشروعنا.
استنباط قصير في تاريخ عمليات تطوير الوثائق الخاصة بنا.
بمجرد أن يقع المشروع على
googlecode . كان لدينا ويكي لائق ، حتى أن الكثير منهم يتذكرونه ، اسأل عن مكان العثور عليه واطلب نقله إلى جيثب ، حيث يقع المشروع الآن (أو في مكان آخر يمكن الوصول إليه). كان googlecode ويكي مفيدًا جدًا. كان متعدد اللغات وكان ، في رأيي ، ميزات أكثر من الويكي على جيثب. لكن ما حدث هو أنه ، إلى جانب googlecode نفسه ، غرق في غياهب النسيان. تؤدي الويكي الحالية على github بشكل جيد الوظيفة المنوطة بها المتمثلة في تقديم معلومات تشغيلية حول المشروع ، ولكن من الصعب للغاية إنشاء وثائق كاملة على هذا النظام الأساسي.
بالطبع ، بالنسبة لأي مشروع مفتوح المصدر ، فأنت بحاجة إلى كل من الوثائق عبر الإنترنت (يمكن الوصول إليها بسرعة) عبر الإنترنت ، والتي يؤدي دورها بواسطة الويكي ، والوثائق الكاملة المتاحة دون اتصال بالإنترنت ، لأنه من الأسهل بكثير فهم جوهر وأيديولوجية المشروع. بالإضافة إلى ذلك ، فإن إجراء البحث في وضع عدم الاتصال على مستند واحد ، بدلاً من الصفحات المتباينة في الويكي ، أسهل أيضًا.
ربما كان أفضل خيار أعرفه هو
وثائق ARM . وهذا هو ، الوثائق عبر الإنترنت ، حيث يوجد بحث في جميع الأقسام ، ولكن هناك وثيقة محددة متاحة للتنزيل بتنسيق pdf. لسوء الحظ ، لم تصل Embox إلى مستوى ARM من حيث القدرات. لذلك ، كان علينا أن نفعل الإصدار غير المتصل بشكل منفصل. لهذا ، استخدمنا خدمة
محرّر مستندات Google . إنه مناسب لأنه: يسمح لك بتنزيل البيانات بتنسيقات مختلفة والتعاون ولديه نظام تحكم في إصدار مضمن. لقد قمنا بنقل بعض المعلومات من الويكي ، وقمنا بتعيين الهيكل ، لأن الهدف من تطوير الإصدار غير المتصل بالشبكة هو إنشاء وثائق شاملة ، وبدأنا في تطوير عدة مستندات. ولكن بسرعة كافية ، واجهنا مشاكل. كانت المعلومات قديمة ، ولم تتطابق بيانات ويكي مع البيانات من الوثائق غير المتصلة بالإنترنت ، والأهم من ذلك أننا لم نتمكن من إنشاء وثائق كاملة. كان هناك هيكل ، ولكن نظرًا لأنه لم يكن من الممكن الحصول على تعليقات لائقة من المستخدمين ، فقد تبين أن منشئي المحتوى هم فقط الذين يمكنهم فهم الوثائق. هذه بالتأكيد ليست مشكلة في الخدمة ، ولكن الحقيقة ، كما يقولون ، واضحة. كان علينا أن نبحث عن نهج مختلف لهذه المشكلة.
ثم حاولنا فقط نقل البيانات من الويكي القديم إلى جيثب الويكي ، لكن حتى ذلك الحين واجهنا مشاكل بسرعة. لقد وجدنا أن جزءًا من المعلومات قديم ، ولم تتم إضافة جزء منه ، ولم يكن جزءًا واضحًا حول كيفية تقديمه في نموذج سهل الاستخدام. مواصلة البحث عن حل للمشكلة ، في مرحلة ما ، فكرنا في تطوير الوثائق في TeX باستخدام مستودع git ، لكن سرعان ما أدركنا أن هذا كان بالفعل أكثر من اللازم. على الرغم من أن هذه الفكرة كان لها تأثير.
قررنا صياغة ما نريد من الوثائق ، وهذا يعني من عملية تطوير الوثائق ، نترك المحتويات خارج الأقواس:
- يجب الاحتفاظ بالوثائق بتنسيق نصي حيث كان من المفترض أن تستخدم git كنظام للتحكم في الإصدار
- يجب أن يكون للوثائق إصدار عبر الإنترنت (wiki) وغير متصل (مستندات منفصلة ، على سبيل المثال ، بتنسيق pdf)
- يجب أن تكون المستندات عبر الإنترنت وغير المتصلة قادرة على المزامنة بسهولة.
- يجب أن تتكون الوثائق من أقسام (فصول) يمكن تطويرها أو دراستها بشكل منفصل ، ولكن يمكنك إنشاء وثائق كاملة منها
لا تتناقض أي من النقاط مع استخدام تخفيض السعر ، وكان مثيرًا للاهتمام لأنه مستخدم بالفعل على الويكي. يمكنك ، بالطبع ، استخدام تنسيق مختلف وتحويله إلى تخفيض السعر. ولكن بعد تجميع قائمة أخرى من المتطلبات ، هذه المرة إلى القدرة على إضافة أنواع مختلفة من المحتوى (الصور ، النص ، التنسيق) ، توصلنا إلى استنتاج مفاده أن تخفيض السعر يلبي جميع احتياجاتنا الحالية بشكل كاف. وأظهرت جوجل الأولى حول موضوع "تخفيض السعر إلى قوات الدفاع الشعبي" أن الخيارات المتاحة لتحويل تخفيض السعر إلى تنسيقات أخرى موجودة وتحظى بشعبية كبيرة.
هناك العديد من الخيارات لتحويل تخفيض السعر إلى ملف pdf ، لكن
pandoc هو الأكثر شعبية
إلى حد بعيد . يمكن لهذه الأداة المساعدة تحويل أي تنسيق نصي إلى أي تنسيق نصي. بالإضافة إلى ذلك ، هو ناتئ. لذلك ، فهي ليست مألوفة لدينا فقط ، ولكن يمكن أيضًا تضمينها في برامج نصية لإنشاء وثائق بتنسيقات مختلفة.
لقد قررنا الأداة المساعدة وبدأنا في التفكير في السؤال الصغير التالي الذي كان علينا حله ، وهو كيفية إنشاء مستند واحد ، وليس الكثير من ملفات pdf مع فصول مختلفة تم الحصول عليها من ملفات تخفيض سعر منفصلة. كانت الرغبة الأولى ببساطة هي "حفظ" الملفات (لدمج النص من ملفات مختلفة) في التسلسل المطلوب ، ولكن اتضح أن الأمر أكثر بساطة ، وباندوك نفسه قادر تمامًا على العمل مع قائمة الملفات. هذا سمح لنا أيضًا بحل المشكلة جزئيًا التي نحتاج إليها من مستندات متعددة والتي قد يتقاطع فيها المحتوى. على سبيل المثال ، نقوم بإنشاء ثلاث مستندات وتحتوي جميعها على قسم وصف موجز. نحن ببساطة إدراج هذا الملف في قائمة pandoc لجميع الوثائق.
نحن نطبق مبدأ مشابهًا على صفحات الغلاف التي يحتوي عليها عنوان المستند وما إلى ذلك. لقد أنشأنا للتو ملفات برؤوس لكل وثيقة وقمنا بإدراجها كملفات أولية في القائمة المصدر لبرنامج pandoc.
كما يحتمل أنك خمنت ، فهذه (قائمة من الملفات المختلفة) تحل مشكلة التعددية اللغوية ، فنحن فقط نحدد الملفات باللغة المطلوبة.
دعونا نتحدث عن الروسية أكثر من ذلك بقليل. عند إنشاء pdf ، يستخدم pandoc مادة اللاتكس كواجهة خلفية للتقديم والتدقيق الإملائي وما إلى ذلك. بشكل افتراضي ، لا يتم عرض السيريلية ولا يتم عرض خطأ حول شخصية غير معروفة. يتم حل هذا ببساطة شديدة ، فقط حدد "بابل الروسية".
--- ... header-includes: - \usepackage[russian]{babel} ---
تجدر الإشارة إلى أنه أكثر صحة للإشارة
--- ... header-includes: - \usepackage[russian, english]{babel} ---
واستخدم أوامر اللاتكس في النص
\selectlanguage{russian} \foreignlanguage{english}{ English text }
أو
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
ولكن نظرًا لأننا أردنا الحفاظ على تخفيض "نظيف" لإمكانية نقله إلى الويكي ، واتضح أن توجيه بابل كان كافياً لأغراضنا ، فقد قررنا عدم تعقيده وتركه كما هو.
بالطبع ، أردنا ألا يكون هناك أي مستندات منسقة بأي شكل من الأشكال ، ولكن على الأقل تبدو موحدة. وهنا ساعدنا المطاط مرة أخرى. الحقيقة هي أنه بما أن pandoc يستخدم اللاتكس ، يمكنك تحديد قوالب اللاتكس لذلك. يتم ذلك ببساطة باستخدام خيار - قالب
pandoc --template=embox_pandoc.latex ...
بعد قيامك بتجميع قالب وتحديده عند إنشاء جميع المستندات ، تحصل على مستندات بأسلوب موحد أكثر أو أقل. "أكثر أو أقل" - لأن هناك العديد من المشكلات التي لم نتمكن من حلها. على سبيل المثال ، تشكيل كتلة واحدة من التعليمات البرمجية. في عملية التخفيض ، من الممكن تحديد كتلة واحدة من التعليمات البرمجية بحيث لا يتم تنسيقها ومن المحتمل أن يكون تمييز بناء الجملة قيد التشغيل. لكننا تمكنا من صنع كتل سطر واحد فقط. تحول هذا بعد النظر في كود اللاتكس الذي تم إنشاؤه.
وهذا هو ، كانت هناك حالات عندما تم وضع نفس الكتلة على وثائق مختلفة بشكل مختلف قليلا.
هناك نقطة أخرى تتعلق بالحروف الأبجدية السيريلية ، وهي استخدام اللغة الروسية. كما ذكر أعلاه ، لاستخدام اللغة الروسية ، اتضح أنها كافية لتحديد بابل الروسية في الرأس. ولكن واجهنا بعض الشذوذ ، على سبيل المثال ، لم يكن هناك تسليط الضوء الغامق ، وغيرها من الشذوذ التنسيق. في البداية ، أخطأنا في حقيقة أن اللغة الروسية محددة بأحرف كبيرة وليس في قالب. بدأوا في دراسة المشكلة. اتضح أنه بطريقة جيدة لا تحتاج إلى استخدام فقط
\usepackage[russian, english]{babel}
ولكن أيضا
تعيين الخطوط \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
ولكن حتى بعد القيام بذلك ، لم يكن من الممكن تصحيح الوضع. اتضح أن مجموعات الخطوط لا تحتوي على جميع خيارات التجسيد ، خاصةً مجموعاتنا لا تحتوي على تنسيقات غامق أو مائل وما إلى ذلك. نظرًا لعدم وجود حل بسيط للمشكلة ، فكرنا في المشكلة وأجلناها إلى أن تتحسن الظروف. حسنًا ، بما أننا كنا نرغب في استخدام تخفيض سعر نظيف (أي دون تحديد أوامر اللاتكس) ، فقد صنعنا قالبًا مشتركًا لكلتا اللغتين ، وتم وضع إشارة حول اللغة الروسية في الرأس.
فقط بضع كلمات سأقولها عن واجهة التطبيق نفسه. نظرًا لأنني ، كما قلت ، تعد تطبيقات وحدة التحكم مألوفة جدًا بالنسبة لنا ويمكن تعبئتها بسهولة في البرامج النصية. في الواقع ، الواجهة بسيطة ، بالطبع يمكنك تعيين العديد من الخيارات ، لكن لأغراضنا ، يكفي تحديد قالب وقائمة ملفات الإدخال وملف الإخراج.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
على الإنترنت ، يمكنك إيجاد pdf (أو أي تنسيق إخراج آخر) تحتاج إلى نوع معالج باستخدام الخيار --pdf-engine = xelatex ، لكن افتراضيًا يتم استخدامه إذا كان ملف الإخراج يحتوي على امتداد pdf. لذلك ، لم نكن بحاجة إلى هذا أيضًا.
قمنا بتعبئة البرامج النصية لتجميع الوثائق في Makefile ، بحيث تصبح مألوفة تمامًا. والآن ، للحصول على الوثائق ، يمكنك ضبط البيئة اللازمة ، ما عليك سوى الاتصال
make [en][ru]
في الختام ، بضع كلمات حول نظام التحكم في الإصدار. المبدأ هو عدم تعقيد (الحفاظ على بساطة) حاولنا الالتزام بكل شيء. وبما أن الحل الأبسط كان استخدام مستودع منفصل على جيثب ،
فعلنا ذلك . نأمل أن يؤدي استخدام github إلى تحسين تعليقات المستخدمين. بعد كل شيء ، كما تعلمون على جيثب ، هناك قضايا يمكنك من خلالها مناقشة أوجه القصور وتقديم أفكارك والاتجاهات.
تم إطلاق هذه العملية مؤخرًا ، بناءً على طلب العديد من العمال! لقد نجحنا في عمل الصيغتين
الإنجليزية والروسية لـ "البداية السريعة" ، بالإضافة إلى
الإصدار الأول من دليل المستخدم الروسي . بدت العملية نفسها أكثر ملاءمة لنا ، وهذا هو السبب في أننا نشاركها مع الجمهور.