Markdown Doc Generation

markdown فرمت مورد علاقه تولید محتوای این روزهای من

اینم یه تجربه پراکنده دیگه!

من معمولا محتواهای زیادی تولید می‌کنم. یعنی گزارش پروژه، مستند‌سازی و … انجام میدم. معمولا قبلا برای این‌کار از word و office استفاده می‌کردم. بزرگترین مشکلی که با این سیستم داشتم این بود که به علت اینکه سیستم عامل اصلیم لینوکسه مجبور بودم توی یک ماشین مجازی کار کنم که به علت سرعت کم هارد دیسک لپ تاپم معمولا اذیتم می‌کرد. اما اخیرا یه مستند تقریبا ۷۰ صفحه‌ای با استفاده از markdown نوشتم که من رو به این نتیجه رسوند که الان وقت مهاجرت از ورد رسیده

قبلا نوشته بودم که چطور میشه یه متن رو یه بار نوشت و به فرمت‌های مختلف اون رو داشت. حالا من به کمک pandoc و markdown و latex و xepersian تونستم یه مجموعه ابزار کامل برای تبدیل متن با سر و شکل قابل قبول و قابل ارائه ایجاد کنم. حالا تصمیم گرفتم که این کار رو ادامه بدم و مشکلاتی که ممکنه بر بخورم رو اینجا مستند کنم.

همین!

چرا لینوکس را دوست دارم: داشتن نسخه latex و html مستندات

اینم یه تجربه پراکنده دیگه!

من به شخصه مدت‌هاست علاقه مندم که مستنداتی که تولید میکنم رو با نرم افزار latex بنویسم اما به هزاران دلیل، که مهم‌ترین عدم توانایی به اشتراک گذاری این فایل‌ها با دیگران(اکثر آدم‌هایی که من باهاشون کار میکنم) نتونستم این ایده رو اجرایی کنم. اما همیشه این علاقه در من وجود داشته و داره. به همین خاطر علمم رو در این زمینه زیاد میکنم. همچنین از وقتی که وبلاگ مینویسم به پست‌های وبلاگم به شکل یک مستند نگاه میکنم و دوست دارم اونها در فرمت لاتک داشته باشم.پس به این نتیجه رسیدم که بگردم و ببینم آیا روشی وجود داره که من مستندات رو به یه فرمت خاص بنویسم و بعدش به html و  فرمت لاتک تبدیل کنم؟

در ابتدای کار شواهدی پیدا کردم که احتمالا این روش وجود داره. اگه با روش مستند سازی doxygen آشنا باشید، مستندات با استفاده از فرمت خاص doxyegen نوشته میشن و این نرم افزار میتونه نتیجه رو به فرمت لاتک و html تبدیل کنه. پس کار امکان پذیره. همچنین یکی دیگه از نیازمندی‌های این راه‌حل برای تبدیل آسون بودنه تا مهاجرت و استفاده از راه حل کم هزینه باشه. همچنین به نظر من نوشتن به فرمت لاتک و html سخته و خیلی «تو دل برو» یا همون user friendly نیست. پس باید این نکته رو هم در پیدا کردن راه حل در نظر بگیرم.

خب حالا برم سراغ راه حلی که برای این مساله پیدا کردم. من از قبل با دو روش ساده نوشتن html که عبارتند از makrdown و reStructuredText بصورت محدودی آشنا بودم و میدونستم که تبدیل این فرمت‌های به html مثل آب خوردن انجام میشه پس نصف مساله حل بود. از اونجایی که من با markdown بیشتر آشنا بودم این زبان ساده شده رو انتخاب کردم. حالا میمونه تبدیل markdown به لاتک که بعد از یه ذره گشتن رسیدم به این دوتا پست(لینک، لینک) و با استفاده از اونها تونستم markdown رو به کمک ابزاری به نام pandoc به لاتک تبدیل کنم و با استفاده از زیپرشین اون رو تبدیل کنم به pdf. حالا مراحل انجام این کار رو اینجا مینویسم

  1. نوشتن مستند به فرمت markdown مثلا
  2. تبدیل این متن به فرمت xelatex با دستور زیر
  3. متن نتیجه شده به شکل زیره که اضافاتی داره
  4. حذف این اضافات با دستورارت زیر
  5. که نتیجه میشه این
  6. این متن به تنهایی توسط لاتک کامپایل نمیشه و باید یه سری تگ‌های استاندارد لاتک بهش اضافه بشه تا بگه فرمت مستند چیه فونتا چین و از این دست چیزا. بهترین راه برای انجام اینکار داشتن یه فایل دیگه برای اون تگ‌های و include کردن این فایل در اون فایل هست. یه نمونه از اون فایل به این صورته:
  7. و با این دستور لاتک رو کامپایل میکنیم
  8. و نتیجه توی اینجا قابل مشاهده است.

همین!