انتقل إلى المحتوى الرئيسي

الفصل 18 · الجزء III · في التطبيق

سطر الأوامر: postext في الطرفية أو في برنامج نصي أو لدى وكيل

ملف تنفيذي واحد مكتفٍ بذاته لأنظمة macOS وLinux وWindows. يحوّل كتاب .postext أو مجلد كتاب أو ملفات Markdown منفردة إلى PDF وHTML وEPUB وصور للصفحات ومستند Word، وينشئ الحزم ويفحص الكتب، ويقدّم مخرجات JSON للبرامج النصية والوكلاء

آخر تحديث 2026-11-0613 دقيقةenescadefritptzhjaar

باختصار

هذه الصفحة لمن يريد أن يصنع كتبًا بـPostext من الطرفية بدلًا من الموقع. تنزّل ملفًا واحدًا يناسب حاسوبك وتشغّله، دون أن تثبّت أي شيء. تعطيه كتابك أو بضعة ملفات نصية، فيصنع منها ملف PDF أو صفحة ويب أو كتابًا إلكترونيًا أو صورًا للصفحات أو مستند Word. ويستطيع أيضًا أن يفحص الكتاب بحثًا عن المشكلات، وأن يجمع ملفاته في ملف واحد. وتستطيع البرامج والمساعدات الذكية استعماله أيضًا، لأنه يجيب بصيغة تقرؤها بسهولة.

ينضّد postext كتابك من الطرفية أو من برنامج نصي أو بيد وكيل.

Sandbox هو المكان الذي تكتب فيه الكتاب وتصمّمه وأنت تراه. أما سطر الأوامر فيأخذ الكتاب نفسه ويُنتج ملفاته دون متصفح: ملف PDF جاهزًا للطباعة، والصفحات بصيغة HTML، وملف EPUB، وصورة لصفحة واحدة أو لكل الصفحات، ومستند Word. ويحزم أيضًا حزم .postext ويفكّها، ويستورد مستندات Word، ويصف الكتاب ويفحصه بحثًا عن المشكلات.

وهو ملف تنفيذي واحد مكتفٍ بذاته لكل نظام. ففي داخله محرّك postext، وكاتبات PDF وEPUB وHTML وWord، ورسّام الصفحات (Skia)، وHarfBuzz للعربية وغيرها من أنظمة الكتابة المركّبة، وملفات تعريف ICC للطباعة، والخطوط الافتراضية (EB Garamond وOpen Sans). فلا بيئة تشغيل ولا حزمة ولا مكتبة تحتاج إلى تثبيتها، والإخراج هو إخراج Sandbox: يتوزّع الكتاب نفسه على الصفحات نفسها.

#الحصول عليه

باستخدام Homebrew على macOS أو Linux:

brew install drnachio/postext/postext

باستخدام Scoop على Windows:

scoop bucket add postext https://github.com/drnachio/scoop-postext
scoop install postext

كلاهما يثبّت الملف التنفيذي لأحدث إصدار أمرًا باسم postext بعد مطابقته مع مجموعه الاختباري، وbrew upgrade postext أو scoop update postext يجلب الإصدار التالي. ومن دون مدير حزم، نزّل الملف بنفسك.

ينشر كل إصدار من Postext الملفات التنفيذية في إصدار GitHub الخاص به، مع مجاميعها الاختبارية (SHA256SUMS) وملف readme.txt:

الملفالنظام
postext-macos-arm64macOS على معالجات Apple (M1 وما بعده)
postext-macos-x64macOS على معالجات Intel
postext-linux-x64Linux x86-64 مع glibc (Debian وUbuntu وFedora…)
postext-linux-arm64Linux ARM64 مع glibc (Raspberry Pi OS بنظام 64 بت، وخوادم ARM السحابية)
postext-linux-x64-muslLinux x86-64 مع musl (Alpine؛ شغّل apk add libstdc++ libgcc أولًا)
postext-windows-x64.exeWindows x64

يتراوح حجم كل ملف بين 115 و140 ميغابايت. والرابط https://github.com/drnachio/postext/releases/latest/download/<file> يعطي دائمًا أحدث نسخة.

في Linux أو macOS:

curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
chmod +x postext
./postext

انقله إلى مجلد في PATH لديك (/usr/local/bin أو ~/.local/bin) لتشغّله باسم postext من أي مكان. ويضع macOS علامة الحجر على كل ملف تنزّله بالمتصفح؛ أزِل هذه العلامة مرة واحدة:

xattr -d com.apple.quarantine postext-macos-arm64

في Windows، داخل PowerShell:

Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
.\postext.exe

وإن كان Node.js مثبّتًا، فإن npx postext-cli ينزّل من npm الملف التنفيذي المناسب لنظامك ويشغّله، وnpm install -g postext-cli يبقيه أمرًا باسم postext.

إذا شغّلت postext دون معاملات طبع نص المساعدة؛ وpostext help <command> يسرد خيارات أمر واحد.

#كتاب أول

ثلاثة ملفات Markdown في مجلد تكوّن كتابًا، كل ملف فصل، بترتيب الأسماء:

postext pdf chapters/ --name "Field notes" -o field-notes.pdf

تعطي البيانات التمهيدية (front matter) للفصل الأول الكتابَ عنوانه ومؤلفه، وتتولى القيم الافتراضية للمحرّك الباقي: عمودان، وشبكة خطوط الأساس، ونص مضبوط مقسَّمة كلماته بالواصلة، وترويسات. وأضف الإعدادات والصور حين تحتاج إليها:

postext pdf chapters/ --config design.json --resources pictures/ -o field-notes.pdf

والكتاب المصنوع في Sandbox (الكتب › تنزيل (.postext)) يعمل كما هو:

postext pdf my-book.postext -o my-book.pdf
postext image my-book.postext --page 1 -o cover.png

#ما الذي يمكن أن يكون كتابًا

كل أمر يقرأ كتابًا يقبل أيًّا مما يلي:

  • ملف .postext: الحزمة التي يصدّرها Sandbox ويفتحها (انظر الحزم).
  • مجلد كتاب: حزمة مفكوكة، فيها preset.json وفصولها ومواردها وخطوطها. وهذا ما تسلّمه مهارة الوكيل، وpostext unpack يكتب مجلدًا كهذا.
  • ملفات Markdown منفردة: ملف .md واحد أو أكثر، كل ملف فصل بالترتيب المعطى، أو مجلد تؤخذ ملفات .md فيه بحسب أسمائها (01-intro.md و02-method.md…). ومعها:
    • --config design.json: الإعدادات، إما كائن إعدادات مجرّد وإما ملف preset.json كامل؛
    • --resources pictures/: الصور، وكل صورة منها شكلٌ معرّفه اسم ملفها دون الامتداد (map.png هي ::resource{id="map"})؛ وإذا وُجد في المجلد ملف resources.json فهو الذي يصفها (المعرّفات، والأنواع، والتعليقات، والنص البديل)، بالصيغة نفسها التي تأخذها resources في ملف preset.json؛
    • --fonts fonts/: ملفات الخطوط التي يتضمّنها الكتاب (TTF وOTF وWOFF2)، وتُعرف باسم العائلة المذكور في جداولها؛
    • --name "Title": اسم الكتاب.

ويعمل --config أيضًا مع الحزمة أو المجلد: فيُدمج فوق إعدادات الكتاب نفسه. والحزمة متعددة اللغات تُقرأ بلغتها ما لم يطلب --locale لغة أخرى (--locale en).

#الأوامر

الأمرما الذي يفعله
pdfملف PDF، بإشارات مرجعية وروابط وخطوط مضمَّنة، وموسوم افتراضيًا لإتاحة الوصول (PDF/UA)؛ وPDF/X وCMYK للطباعة.
htmlالصفحات بصيغة HTML بنص حقيقي: ملف واحد مكتفٍ بذاته، أو مجلد فيه index.html وassets/.
epubكتاب EPUB 3، بصفحات ثابتة كما طُبعت أو بنص قابل لإعادة التدفق.
imageصفحة واحدة صورةً بصيغة PNG أو JPEG أو WebP.
imagesكل الصفحات، أو مدى منها، صورًا في مجلد.
docxالفصول مستندَ Word: دلاليًا (المحتوى وحده بأنماط Word بسيطة) أو منسَّقًا (النص نفسه القابل للتعديل بتصميم الكتاب) أو نسخةً طبق الأصل من الصفحات (كل سطر في مربع نص ثابت).
idmlالصفحات حزمةَ InDesign ‏(IDML)، لإتمامها في InDesign.
import-docxالتصحيحات التي أُجريت في ملف Word مصدَّر، عائدةً إلى الكتاب؛ وأي مستند Word آخر كتابًا جديدًا (مجلدًا أو ملف .postext).
packمجلد كتاب أو ملفات Markdown منفردة في ملف .postext واحد.
unpackملف .postext مجلدًا.
infoفصول الكتاب ولغاته وموارده وخطوطه، ومع --pages عدد صفحاته.
checkيُخرج الكتاب ويذكر كل مشكلة فيه؛ وفي الكتاب المُعدّ للطباعة، يُجري الفحص قبل الطباعة.
buildيُخرج الكتاب مرة واحدة ويكتب عدة مخرجات مما سبق؛ و--watch يبقيه يعمل ويعيد البناء عند كل حفظ.

يكتب كل أمر في المكان الذي تشغّله منه، باسم مأخوذ من المُدخل، ما لم يعطِ -o المسار (ويكتب images في pages/). و-o - يكتب ملفًا ناتجًا واحدًا إلى المخرج القياسي.

#pdf

postext pdf book.postext -o book.pdf
postext pdf book/ --pdfx x4 --profile fogra51 -o book-print.pdf
postext pdf book/ --color-space grayscale --no-outlines

يتبع ملف PDF إعدادات الكتاب نفسه (انظر إنتاج PDF و الإنتاج الطباعي)؛ وهذه الخيارات تغيّرها لتشغيل واحد:

  • --pdfx none|x1a|x4: معيار PDF/X الذي تطلبه المطبعة.
  • --profile NAME|FILE: ملف تعريف ICC للإخراج، باسمه (fogra39 وfogra51 وfogra52 وswop5 وgracol2006 وsnap2007 وifra26 وغيرها من ملفات تعريف إعدادات الطباعة) أو ملف .icc.
  • --color-space rgb|cmyk|grayscale.
  • --accessible / --no-accessible: البنية الموسومة لقارئات الشاشة.
  • --no-outlines: يحذف الإشارات المرجعية.
  • --page-negative: صفحات سالبة، لبعض مسارات العمل الطباعية.

#html

postext html book.postext -o book.html
postext html book.postext -o site/ --mode single

المسار الذي ينتهي بـ.html يأخذ ملفًا واحدًا فيه الصور والخطوط، يسهل إرساله. وأي مسار آخر مجلد: index.html بجانب assets/، الذي يضم الصور والخطوط ومقاطع الفيديو المستضافة ذاتيًا. ويختار --assets embed|folder أحد الطريقين لأي مسار. والصفحات هي إخراج الطباعة معروضًا بحجم الشاشة: جنبًا إلى جنب (--mode multi، وهو الافتراضي) أو واحدة تحت الأخرى (--mode single). والخطوط المعلَّمة بـredistributable: false تُذكر أسماؤها ولا تُنسخ. وإذا حدّدت العائلة عائلةً بديلة (fallback)، كُتبت أشكال تلك العائلة المفتوحة مكانها تحت اسم العائلة الأصلية (منذ postext 1.43).

#epub

postext epub book.postext -o book.epub
postext epub book.postext --layout reflowable --cover cover.jpg

--layout fixed (الافتراضي) يبقي كل صفحة كما طُبعت، بنص قابل للتحديد؛ و--layout reflowable يترك لنظام القراءة أن ينضّد النص من جديد لشاشته (انظر كتب EPUB). والغلاف هو الصورة المصغّرة للكتاب ما لم يعطِ --cover صورة. وتأتي البيانات الوصفية للحزمة (العنوان، والمؤلفون، واللغة، والمعرّف) من البيانات التمهيدية للفصل الأول، كما في Sandbox. والخطوط المعلَّمة بـredistributable: false لا تُنسخ؛ أما العائلة التي تحدّد عائلةً بديلة (fallback) فتُضمَّن مكانها أشكال تلك العائلة المفتوحة تحت اسمها هي (منذ postext 1.43).

#image وimages

postext image book.postext --page 12 -o page-12.png
postext image book.postext --page "#1" --dpi 300 -f jpeg -o cover.jpg
postext images book.postext -o pages/ --dpi 100
postext images book.postext --pages 1-10,iv -f webp --pattern "{chapter}-{label}"

تُسمّى الصفحات كما طُبعت (12 وiv ومدى مثل 7-9) أو بموضعها في الكتاب مع # (#1 هي الصفحة الأولى أيًّا كان الرقم المطبوع عليها، و#10-#20، و#30- حتى النهاية). ويقبل --pages قائمة مفصولة بفواصل. والرسّام هو عرض Canvas في Sandbox، فتُظهر الصورة الصفحة كما أُخرجت تمامًا، دون المرور بملف PDF.

  • --format png|jpeg|webp (أو امتداد -o)، و--quality 1-100 لصيغتي JPEG وWebP.
  • --dpi: الدقة، 150 افتراضيًا؛ ويكفي 72–100 لقراءة صفحة، و300 للطباعة.
  • --pattern: أسماء ملفات images، من {n} (الموضع، و{n:03} بثلاث خانات تُملأ بالأصفار) و{label} (الرقم المطبوع) و{chapter}؛ والافتراضي page-{n:03}.
  • --print-preview: الصفحة كما ستعيد المطبعة إنتاجها، عبر ملف تعريف الإخراج، مع رسم خط القص والنزف.
  • --jobs N: عدد الصور التي تُرمَّز في آن واحد (افتراضيًا بعدد معالجات الحاسوب).

#docx وimport-docx

postext docx book.postext -o book.docx
postext docx book/ --variant semantic -o words.docx
postext docx book/ --variant facsimile -o pages.docx
postext import-docx book.docx book/ --dry-run
postext import-docx book.docx book/
postext import-docx manuscript.docx -o manuscript/ --locale es --report

يكتب docx مستندات Word التي يصدّرها Sandbox (انظر Sandbox › مستندات Word)، ومستندًا ثالثًا. فالخيار الافتراضي --variant formatted يبني من Markdown مستندًا قابلًا للتعديل بعناوين Word وقوائمه وحواشيه السفلية وجداوله ومعادلاته وأقسامه، مصفوفًا بتصميم الكتاب بقدر ما يسمح Word ومع تضمين خطوط الكتاب (و--no-embed-fonts يكتفي بتسميتها)؛ وما لا بنية له في Word ينتقل مصدرًا في عناصر تحكم في المحتوى Postext Source. أما --variant semantic فيكتب النص نفسه محتوًى فقط: مستندًا بسيطًا (A4، عمود واحد، Arial) بأنماط Word تسمّي كل جزء، دون شيء من تصميم الصفحة ودون خطوط مضمَّنة. ولا يحتاج أيٌّ منهما إلى إخراج؛ ويُفتح كلاهما في Word وفي مستندات Google، ويعود كلاهما عبر import-docx. وأما --variant facsimile فيُخرج الكتاب كما يفعل pdf ويكتب كل صفحة قسمًا في Word، وكل سطر في مربع نص ثابت، مع تضمين الخطوط: ملف لمعاينة الإخراج في Word على سطح المكتب، لا للتعديل ولا لمستندات Google. والعائلة التي لا يحق للكتاب تمريرها (redistributable: false في customFonts) تُستبعد ويدخل بديلها المفتوح، كما في EPUB؛ والخط الذي يمنع ترخيصه التضمين، والخط ذو محيطات PostScript، والخط المتغير، يُبلَّغ عنها وتُسمّى فقط. وفي build يكتب --docx FILE الملف نفسه، مع --docx-variant و--no-docx-fonts. منذ postext 1.68؛ ولم يعد --template ينطبق على docx ولا build.

ومع كتاب بعد الملف، يعيد import-docx التصحيحات التي أُجريت في مستند صدّره docx من ذلك الكتاب. فيقرأ الخريطة التي يحملها الملف، ويقارن النص بنسخة الفصول المأخوذة عند التصدير، ويدمج كل تصحيح في الكتاب كما هو الآن: ملفات الفصول في مجلد أو ملف .postext أو Markdown مفرد، ونص الموارد (التعليقات التوضيحية، والحواشي، والنص البديل، وخلايا الجداول) في preset.json، أو في resources.json الخاص بـ--resources DIR مع Markdown المفرد. وفي كتاب بعدة لغات، يحدد --locale الطبعة التي صُدِّر منها الملف، ويذهب تصحيح نص المورد إلى كتلة localized لتلك الطبعة. ويُبلَّغ عن كل تصحيح في سطر خاص به:

  • applied، مع الملف والسطر اللذين ذهب إليهما؛
  • conflict: تغيّر النص في الكتاب أيضًا منذ التصدير، أو لم يعد الفصل أو المورد موجودًا، أو تداخل تصحيحان؛
  • rejected: نص يولّده الكتاب نفسه (أرقام، تسميات التعليقات التوضيحية)، أو تنسيق يعبر ترميز Postext.

وتُعامَل التغييرات المتعقَّبة على أنها مقبولة، وتُسرد تعليقات Word مع كاتبها وموضعها دون أن تُكتب. ورمز الخروج 3 حين لا يُطبَّق تصحيح ما. ويطبع --dry-run ‏(-n) التقرير وفرقًا موحّدًا (unified diff) لكل ملف سيتغير، ولا يكتب شيئًا. ويُكتب كل ملف بجانب هدفه ثم يُعاد تسميته فوقه، فلا يترك تشغيلٌ مقطوع نصفَ فصل أبدًا؛ وملف الفصل الذي تغيّر أثناء الاستيراد يُترك كما هو مع تحذير docx.fileChanged. ولا يُستعمل -o مع كتاب. ومع --json تحمل الإجابة variant وexportId وedits (لكل منها status وreason وkind وbefore وafter وat) وcomments وfiles، وdiff في التشغيل التجريبي.

ويعود كذلك الملف الذي عُدِّل في مستندات Google ونُزِّل بصيغة .docx. فمستندات Google لا تُبقي الخريطة ولا نسخة الفصول؛ فيكتب الاستيراد الخريطة من جديد من الكتاب، ويقول ذلك في التقرير. ولأن هذا الملف لا يحمل نسخة من النص المصدَّر، يُقارَن بالكتاب كما هو الآن. فإن تغيّر الكتاب منذ التصدير نبّه التقرير إلى ذلك، وقد يظهر تغيير أُجري في الكتاب في أثناء ذلك على أنه تعديل يلغيه. فاستورد ملف مستندات Google إلى الكتاب الذي صُدِّر منه، قبل أن تغيّر ذلك الكتاب؛ أما الملف الذي حفظه Word فيحتفظ بخريطته ويُدمج مع ما تغيّر في الكتاب بعد ذلك. وتحذف مستندات Google أيضًا العلامة المخفية للنص الذي يُستبدل كله (عنوان، خلية جدول، تعليق توضيحي، عنوان إطار، حاشية سفلية). ويجد الاستيراد هذا النص بموضعه بين جيرانه، فيبقى العنوان عنوانًا ويذهب التعليق التوضيحي إلى مورده. وحين يتعذر الحسم، كأن تُكتب فقرة بجانبه أيضًا ولا شيء يميّز أحدهما من الآخر، يعرض التقرير حذفًا وإضافة بدلًا من ذلك. واستيراد الملف نفسه مرة ثانية لا يأتي بشيء.

ودون كتاب، يحوّل import-docx أي مستند Word إلى كتاب جديد: فصل عند كل عنوان من المستوى الأول (و--no-split يبقيه فصلًا واحدًا)، والصور والجداول موارد، ويطبع --report تقرير الجودة الذي يعرضه Sandbox (الأنماط المستعملة، والتنسيق المباشر، والترقيم المكتوب يدويًا…). ويقبل --template قالب استيراد (ملف .json محفوظًا من Sandbox أو ملف .docx فيه قالب).

تباعد الحروف خاصية من خصائص النمط لا من النص، ولذلك لا يرد في Markdown. يكتب docx قيمة letterSpacing لأنماط الفقرات وأنماط العناوين ومستويات العناوين على أنها تباعد الحروف في نمط Word، ويقرؤها import-docx مرة أخرى بوحدة em نسبةً إلى حجم النمط: فيضبط letterSpacing في أنماط الكتاب التي لا تحدد تباعدًا (أنماط الفقرات والعناوين في ملف --config التي تقابلها أنماط Word، ومستويات العناوين)، ويترك كما هو أي تباعد يحدده الكتاب من قبل. ومع --json يسرد styleTracking ما طُبّق (applied) وما تُرك (skipped). منذ postext 1.39.

#idml

postext idml book/ -o book.idml
postext idml book.postext -o book.idml --images link
postext idml book/ -o out/book.idml --lines reflow --fonts

يُخرج idml الكتاب كما يفعل pdf ويكتب الصفحات حزمةَ InDesign Markup، لإتمام الكتاب في InDesign: الصفحات في صفحات متقابلة (spread) على جانبي الكعب في كتاب له هوامش صفحات متقابلة (وصفحة واحدة في كل spread في غيره)، والخطوط والمربعات والمسارات والصور عناصرَ صفحة، والجداول جداولَ InDesign، ونص كل إطار من إطارات الصفحة المركّبة إطارَ نص بقصة (story) خاصة به (والإطارات المتسلسلة بـnext تشترك في قصة واحدة)، وأنماط الإطارات أنماطَ فقرات، وألوان CMYK التي حدّدها المؤلف عيّناتِ ألوان (swatches). والشارات التي تحمل حقل نموذج تصير حقول نماذج في InDesign. وينهي --lines keep (الافتراضي) كل سطر حيث أنهاه Postext، فيعرض InDesign الأسطر نفسها التي في PDF؛ ويترك --lines reflow الفقرات لمنضِّد InDesign، وقد تختلف فواصل الأسطر. ويضع --images link الصور بجانب الملف في Links/ بدلًا من داخله. ويكتب --fonts ملفات الخطوط للأوجه المستعملة بجانب الحزمة في Document fonts/، حيث يجدها InDesign لذلك المستند؛ ويحتاج إلى أن يسمّي -o ملفًا، والعائلة التي لا يحق للكتاب إعادة توزيعها تُترك مع تحذير. وما لا تستطيع الحزمة حمله كما هو في الكتاب (النص العمودي، والإطار المستدير الزوايا لجدول) يُبلَّغ عنه بتحذير idml.*. والحزمة postext-idml هي التي تكتب الملف: انظر الاستخدام البرمجي › حزم InDesign. منذ postext 1.71؛ و--lines و--fonts منذ 1.76.

#pack وunpack

postext pack my-book/ -o my-book.postext
postext pack 01.md 02.md --name "Notes" --config design.json --resources img/ -o notes.postext
postext unpack my-book.postext -o my-book/

يضغط pack مجلد الكتاب كما هو، أو يبني حزمة من ملفات Markdown منفردة. والمُدخل نفسه يعطي دائمًا البايتات نفسها، فيمكن مقارنة الحزم أو حساب بصمتها. ومع ملفات Markdown المنفردة تضبط --id و--description و--thumbnail FILE (صورة غلاف) معرّف الحزمة ووصفها وصورتها المصغّرة؛ والمعرّف افتراضيًا صيغة مختصرة (slug) من الاسم. أما المجلد فيحتفظ بما يقوله ملف preset.json فيه. والكتاب الذي لا يحدّد غلافًا تصبح صفحته الأولى غلافه (thumbnail.jpg، بطول 1024 بكسل في ضلعه الأطول)، وهي الصورة التي يستطيع مدير الملفات أن يعرضها للملف؛ ويحذفها --no-auto-thumbnail. ويرفض unpack الكتابة في مجلد غير فارغ ما لم يُعطَ --force.

#info وcheck

postext info book.postext --pages
postext check book.postext
postext check chapters/ --strict --json

يسرد info الفصول (العنوان، والكلمات، والملف، ومع --pages صفحاتها)، والموارد، وكل عائلة خطوط مع مصدرها (الكتاب، أو مجلد، أو الملف التنفيذي، أو ذاكرة التنزيل المؤقتة، أو الخط البديل). وإذا حدّد الكتاب موضع بدايته (start في preset.json: مقتطف يبدأ من الصفحة 58، في الفصل الرابع) عرضه info أيضًا، وكل الأوامر تُخرج الكتاب من هناك.

ويُخرج check الكتاب ويذكر ما تعرضه لوحة الفحوص في Sandbox: Markdown غير مغلق، وموارد وتوجيهات وأنماط مجهولة، وإطارات اضطر الإخراج إلى فرضها، وخطوط مفقودة، وإعدادات اضطر المحرّك إلى استبدالها، وفي الكتاب المُعدّ للطباعة (أو مع --preflight) الفحص قبل الطباعة: صور منخفضة الدقة، وخطوط رفيعة، ونص صغير بعدة أحبار، وحبر فوق الحد، ونص قرب خط القص. ويسرد أيضًا النص الذي تصعب قراءته على خلفيته (contrast)، مرة واحدة لكل زوج من الألوان، مع النسبة على الشاشة، وللطباعة على ورق ملف تعريف الإخراج. وتذكر كل مشكلة ملف الفصل والسطر والصفحة. ويكون رمز الخروج 3 حين يُعثر على خطأ، أو على أي تحذير مع --strict.

ويذكر أيضًا نصوص التصميمات في الإعدادات التي تتضمّن نص الكتاب نفسه بدل العناصر النائبة (contentInConfig)، مرة لكل نمط عنوان أو ترويسة أو تصميم جزء، مع مسار كل نص: انقل ذلك النص إلى Markdown، أو أضف العنوان أو اسم الناشر إلى checks.contentInConfig.allow.

وفي الكتاب الذي له قوالب صفحات، يذكر check أيضًا النص الذي لا يتّسع له إطاره (frameOverflow، مع خطوات الملاءمة التي جُرّبت والتغييرات التي تجعله يتّسع)، والمقال الذي يتجاوز الصفحات التي يجوز للإطار إضافتها (frameContinuationLimit)، والقفز إلى صفحة لا تأتي بعده (continueTargetMissing)، وتسميات الأشكال التي لا يمكن رسمها أو التي تتصادم (labelAnchorUnknown وanchorUnlabelled وlabelOverflow وlabelOverlap)، والإطارات المختفية تحت إطارات أخرى أو التي تتجاوز حدّها (frameCovered وframeOutsideArea)، والبطاقات التي تزيد على ما تتسع له الشبكة (repeatOverflow)، والوحدات التي لا تستطيع الصفحة تنضيدها (moduleUnknown وmoduleAsPage وmoduleNested وmoduleNameRejected). وبعد التحذيرات يطبع سطر reflow لكل صفحة مركّبة فيها أحداث، وتتضمّن مخرجات --json الخطوات والمقترحات وسجلّ إعادة التوزيع بوصفها بيانات. انظر الصفحات المركّبة › التحذيرات وسجل إعادة التوزيع.

#build و--watch

postext build book/ --pdf out/book.pdf --html out/book.html --images out/pages --pages 1-4
postext build chapters/ --pdf book.pdf --watch

يُخرج build الكتاب مرة واحدة ويكتب كل مُخرج تذكره (--pdf و--html و--epub و--images و--docx)، بخيارات كل أمر. ويبقى --watch يعمل: حين يتغير فصل أو الإعدادات أو صورة، يُخرَج الكتاب من جديد والخطوط والمحرّك ما زالت محمّلة، وعادةً في جزء من الثانية للفصل الواحد، وتُعاد كتابة المخرجات. والحفظ الذي يُفسد الكتاب يطبع الخطأ ويحتفظ بآخر ملفات سليمة.

#خيارات لكل كتاب

الخيارما الذي يفعله
--locale TAGاللغة التي يُقرأ بها الكتاب متعدد اللغات (es وen وpt-BR…).
--chapters LISTيُخرج بعض الفصول فقط: 2 و1,3-5 و4-. أسرع في الكتاب الطويل؛ وتُرقَّم صفحاتها بدءًا من صفحتها الأولى.
--set PATH=VALUEيغيّر إعدادًا واحدًا لهذا التشغيل، بمسار تفصل النقاط بين أجزائه: --set page.dpi=150 و--set bodyText.fontFamily=Lora و--set headings.levels.0.italic=true. تُقرأ القيمة بصيغة JSON حين يمكن ذلك (الأعداد، وtrue وfalse، والكائنات)، وإلا فنصًا. يمكن تكراره.
--config FILEإعدادات (أو ملف preset.json) لملفات Markdown المنفردة، أو تُدمج فوق إعدادات الكتاب نفسه.
--resources DIR و--fonts DIR و--name TEXTالصور والخطوط والعنوان لملفات Markdown المنفردة.
--font-dir DIRمجلد يُبحث فيه عن الخطوط التي لا يتضمّنها الكتاب. يمكن تكراره.
--offlineلا ينزّل الخطوط أبدًا.
--cache-dir DIRمكان حفظ الخطوط المنزَّلة.

ولكل أمر: --json و--quiet (-q، الأخطاء فقط) و--verbose (التقدّم وكل تحذير) و--no-color و--help (-h) و--version (-v).

#الخطوط

الكتاب الذي يتضمّن خطوطه (حزمة، أو --fonts مع ملفات Markdown منفردة) يُنضَّد بها وحدها. ولكل عائلة تذكرها الإعدادات ولا يتضمّنها الكتاب، يبحث postext بهذا الترتيب:

  1. في المجلدات المعطاة بـ--font-dir؛
  2. بين الخطوط المضمَّنة في الملف التنفيذي: EB Garamond وOpen Sans، وهما الخطان الافتراضيان للمحرّك؛
  3. في ذاكرة التنزيل المؤقتة؛
  4. في Google Fonts، التي تعطي ملفات TrueType ثابتة كاملة، أو في Fontsource للعائلة التي ليست في Google Fonts (مثل Commit Mono وFiraGO)؛ وتُحفظ في الذاكرة المؤقتة، فلا تُنزَّل العائلة إلا مرة واحدة.

والوزن الذي لا يوجد في العائلة يُنضَّد بشكل الخط الذي يختاره المتصفح (مطابقة الخطوط في CSS: فوق 500 الأثقل أولًا، ودون 400 الأخف أولًا، فالوزن 600 في عائلة لها 400 و700 هو شكلها ذو الوزن 700، وكذلك 550)، والميل الذي لا يوجد فيها يُنضَّد بشكلها القائم. ويُستعمل كل منهما كما هو، في صور الصفحات كما في ملف PDF: فخط العناوين الذي ليس له إلا وزن واحد يحتفظ بحروفه نفسها في العريض، والعائلة التي ليس لها شكل مائل تبقى قائمة في المائل.

وتُجلب الأوزان التي تذكرها الإعدادات: العادي والعريض ومائلاهما لكل عائلة، وكل وزن آخر يحدده إعداد، ومنه وزن العريض (فالإعداد bodyText.boldFontWeight: 600 يطلب شكل الخط ذا الوزن 600). وإذا تعذّر تحميل وزن موجود في العائلة (بلا اتصال ولا ملف في الذاكرة المؤقتة، أو تنزيل فشل، أو مجلد خطوط ليس فيه الملف) نُضِّد النص بشكل العائلة الذي تختاره القاعدة نفسها بدلًا منه، وأصدر عنه postext check التحذير fontFallback: فقد تنكسر أسطره على غير ما تنكسر في Sandbox.

المحرف الذي ليس له شكل في خط يُرسم بخط آخر. يقرأ postext check جدول cmap من كل خط يحمّله، ويذكر تلك المحارف مرة واحدة لكل خط في الكتاب كله في تحذير glyphFallback؛ ومع --json يحمل data المحارف وعددها.

الذاكرة المؤقتة هي ~/.cache/postext (و%LOCALAPPDATA%\postext\cache في Windows)؛ وينقلها POSTEXT_CACHE_DIR أو --cache-dir. ويتخطى --offline التنزيل. والعائلة التي لا توجد في أي مكان تُنضَّد بخط EB Garamond تحت اسمها، فيبقى الإخراج وملف PDF متفقين، ويذكرها تحذير missingFont. ويعرض postext info مصدر كل عائلة.

ويجوز للحزمة التي لا تتضمّن ملفات عائلة مرخَّصة أن تحدّد بديلًا لها عائلةً مفتوحة بعرض مقارب (fallback في fonts داخل البيان، منذ postext 1.42). فيبحث postext عن تلك العائلة بالخطوات أعلاه، وينضّد أشكال الخط التي لا يتضمّنها الكتاب بأشكال تلك العائلة ذات الوزن نفسه والميل نفسه، تحت اسم العائلة المرخَّصة، فيقترب الإخراج مما يكون مع الملفات، ولا يُصدر postext check التحذير missingFont لها. والعائلة التي يتضمّن الكتاب بعض أشكالها فقط لا تأخذ من fallback إلا الميل الذي ليس لها شكل فيه. ويُضمّن ملف PDF شكل الخط المفتوح.

#للبرامج النصية والوكلاء

بُني سطر الأوامر لتقوده برامج أخرى، ومنها وكلاء البرمجة.

  • --json يطبع كائن JSON واحدًا على المخرج القياسي حين ينتهي الأمر؛ وتذهب كل رسالة إلى مخرج الأخطاء القياسي. ويسرد التقرير ما كُتب، والصفحات، وكل تحذير مع مصدره، والمدة التي استغرقتها كل خطوة (بالمللي ثانية):
{
  "ok": true,
  "command": "pdf",
  "version": "1.22.1",
  "book": { "name": "notes", "id": "notes", "locale": "en", "chapters": 2 },
  "pages": 3,
  "outputs": [{ "kind": "pdf", "path": "notes.pdf", "bytes": 29746, "pages": 3 }],
  "warnings": [
    {
      "kind": "unknownResourceId",
      "severity": "warning",
      "message": "Unknown resource id \"map\" in ::resource — nothing is embedded (offset 26)",
      "at": "notes/02-more.md:5"
    }
  ],
  "timings": { "read": 13, "fonts": 8.4, "math": 28.2, "layout": 51.6, "pdf": 132.1, "total": 1638 },
  "exitCode": 0
}
  • رموز الخروج: 0 تمّ، و1 فشل، و2 استعمال خاطئ (خيار مجهول، أو مُدخل مفقود)، و3 وجد check أخطاء (أو تحذيرات مع --strict)، أو ترك import-docx تصحيحًا من Word دون تطبيق.
  • بلا أسئلة. لا ينتظر أي إدخال أبدًا؛ والمجلد غير الفارغ يُرفض بدلًا من السؤال عنه.
  • المخرج القياسي: -o - يكتب إليه ملف PDF أو صورة أو حزمة، لتُمرَّر بأنبوب إلى ما بعده.
  • السرعة. يبدأ الملف التنفيذي في بضعة أجزاء من مئة من الثانية. ويصير الكتاب القصير ملف PDF أو صورة صفحة في أقل من ثانية بكثير؛ أما الطويل فيستغرق ما يستغرقه إخراجه (رواية مصوّرة من 140 صفحة، نحو عشر ثوانٍ). ولتنظر في بضع صفحات من كتاب طويل، اجمع --chapters مع image أو images --pages. ولتعمل على كتاب عبر تغييرات كثيرة، أبقِ postext build --watch يعمل واقرأ مخرجاته.

تستعمل مهارة الوكيل سطر الأوامر لترسم الصفحات التي تعمل عليها ولتفحص الكتاب الذي تنقله.

#Python

يجعل pip install postext سطرَ الأوامر مكتبةً في Python. الحزمة مكتوبة بـPython خالصة، بلا اعتماديات، ورقم إصدارها هو رقم إصدار postext. في أول مرة تنفّذ فيها أمرًا تنزّل الملف التنفيذي الخاص بنظامك من إصدار GitHub لذلك الرقم، وتتحقق منه بـSHA256SUMS، وتحفظه في ذاكرة التخزين المؤقتة المذكورة أعلاه، تحت bin/<الإصدار>/. وإذا أشار POSTEXT_BIN إلى ملف تنفيذي لديك أصلًا (من Homebrew أو Scoop أو من بنائك الخاص) فلا يُنزَّل شيء.

import postext
 
report = postext.pdf("book.postext", out="book.pdf", set={"page.dpi": 300}, locale="es")
print(report.output.pages)
for warning in report.warnings:
    print(warning.kind, warning.at, warning.message)
 
pdf = postext.pdf_bytes(open("book.postext", "rb").read())
  • دالة لكل أمر: pdf وhtml وepub وimage وimages وdocx وimport_docx وpack وunpack وinfo وcheck وbuild. تحتفظ الخيارات بأسمائها، بشرطات سفلية (color_space وfont_dirs وdry_run). يأخذ set قاموسًا، وconfig ملفًا أو قاموسًا، وchapters رقمًا أو قائمة أو range أو "1,3-5".
  • التقارير كائنات. تنفّذ كل دالة أمرها مع --json وتعيد التقرير: outputs وpages وtimings وwarnings، وكل تحذير فيه Diagnostic له kind وseverity وmessage وat وpage. ويضيف info الحقول chapters وresources وfonts، ويضيف check الحقول passed وerror_count وwarning_count.
  • الأخطاء استثناءات. الإخفاق يطلق PostextError، والخيار الخاطئ UsageError. وإذا وجد check أخطاء أطلق ProblemsFound، ويسردها report الخاص به؛ ومع raise_on_problems=False يعيد التقرير بدلًا من ذلك.
  • البايتات. يمكن تمرير الكتاب على هيئة بايتات حزمة .postext. ومع out="-" يعود الملف في report.content؛ وتعيده pdf_bytes وhtml_bytes وepub_bytes وimage_bytes وdocx_bytes وpack_bytes مباشرة.
  • يشغّل postext.Postext(binary, cwd=…, timeout=…) ملفًا تنفيذيًا محددًا، وpython -m postext … هو سطر الأوامر نفسه.

كل استدعاء يشغّل الملف التنفيذي من جديد. ويسرد README الخاص بالحزمة الخيارات كلها.

#كيف صُنع

سطر الأوامر هو الحزمة postext-cli في المستودع. يترجمه Bun، مع المحرّك وكاتباته، إلى ملف تنفيذي واحد لكل نظام، ويقيس Skia (عبر @napi-rs/canvas) النص ويرسمه، كما يفعل Canvas المتصفح داخل Sandbox. أما صورة SVG التي تتضمّن صورة نقطية (PNG أو JPEG مضمّنة على هيئة data URI، كما يكتب pdftocairo -svg الرسوم المقتطعة من ملف PDF) فيرسمها resvg، لأن عارض SVG في Skia يُسقط هذه الصور. وفي كل إصدار تُبنى الملفات التنفيذية، وتُشغَّل على Linux وAlpine وmacOS وWindows، وتُرفق بإصدار GitHub؛ ويتلقى npm الحزمة postext-cli وحزمة postext-cli-<system> لكل ملف تنفيذي.

لتشغيله من نسخة من المستودع:

pnpm install
pnpm --filter postext-cli start pdf book.postext
pnpm --filter postext-cli build:bin --current

الأمر الأول يشغّله من مصادره؛ والثاني يكتب الملف التنفيذي الخاص بهذا الحاسوب في packages/postext-cli/bin/.

#الفروق عن Sandbox

  • HTML هو إخراج الطباعة معروضًا بحجم الشاشة. أما تبويب HTML في Sandbox فينضّد النص من جديد بحسب النافذة.
  • --chapters يُخرج الفصول كلًّا على حدة: تبدأ أرقام صفحاتها من جديد، في حين يواصل Sandbox ترقيم الكتاب.
  • الخطوط تأتي من الكتاب، أو من مجلداتك، أو من الملف التنفيذي، أو من Google Fonts، أو من Fontsource (للعائلة التي ليست في Google Fonts)، ولا تأتي أبدًا من الخطوط المثبّتة على الحاسوب، فيخرج الكتاب نفسه على كل جهاز.
  • لغة النص في المتصفح هي لغة المستند نفسه (bodyText.shapingLanguage: 'document'، وهي القيمة الافتراضية منذ postext 1.30). أما Canvas في Skia فيقبل لغة لكنه يشكّل النص من دونها، فيقيس سطر الأوامر أشكال اللغة الافتراضية لكل خط ويُخرج كتبه دائمًا بـshapingLanguage: 'host'، أيًّا كان ما تقوله الإعدادات؛ ويرسم ملف PDF وصور الصفحات هذه الأشكال نفسها. والكتاب الذي في خطه أشكال للغة ما (l·l الكتالونية، وfi التركية، وأرقام خط صيني في كتاب إنجليزي) يُنضَّد هنا بالأشكال الافتراضية. وما تقيسه 'document' على نحو آخر (جزءا الكلمة المقطوعة في آخر السطر، والكلمة المكتوبة من اليمين إلى اليسار، ونص التصميم) يُقاس هنا كما تقيسه 'host'، فقد ينكسر السطر عند كلمة غير التي ينكسر عندها في Sandbox.