groff(1)

الاسم
groff - واجهة لنظام GNU roff لتنسيق المستندات

موجز
groff [-abcCeEgGijklNpRsStUVXzZ] [-d نص_م] [-d سلسلة=نص] [-D ترميز-احتياطي] [-f عائلة-الخط] [-F دليل-الخطوط] [-I دليل-الاشتمال] [-K ترميز-المدخلات] [-L معطى-المجدول] [-m حزمة-ماكرو] [-M دليل-الماكرو] [-n رقم-الصفحة] [-o قائمة-الصفحات] [-P معطى-المعالج-البعدي] [-r تعبير-عددي-ج] [-r سجل=تعبير-عددي] [-T جهاز-المخرجات] [-w فئة-التحذير] [-W فئة-التحذير] [ملف ...]

groff -h
groff --help

groff -v [خيار ...] [ملف ...]
groff --version [خيار ...] [ملف ...]

الوصف
يعد groff الواجهة الرئيسة لنظام GNU roff لتنسيق المستندات. نظام GNU roff هو نظام لصف الحروف يقرأ مدخلات نصية بسيطة تتضمن أوامر تنسيق لإنتاج مخرجات بتنسيقات PostScript أو PDF أو HTML أو تنسيقات أخرى، أو لعرضها على الطرفية. يمكن أن تكون أوامر التنسيق هي أوليات صف حروف منخفضة المستوى، أو وحدات ماكرو من حزمة مرفقة، أو وحدات ماكرو يعرفها المستخدم. يمكن الجمع بين النُهج الثلاثة جميعاً. إذا لم تُحدد معاملات ملف، أو إذا كان الـ ملف هو “-”، فإن groff يقرأ من دفق الدخل القياسي.

كإعادة تنفيذ وتوسيع لبرنامج troff وبرامج أخرى من AT&T Unix، يتوفر groff على نطاق واسع في أنظمة POSIX وغيرها نظراً لارتباطه الطويل بأدلة Unix، بما في ذلك صفحات الدليل (man pages). أنتج هو وسلفه العديد من نصوص هندسة البرمجيات الأكثر مبيعاً. يستطيع groff إنشاء مستندات متطورة طباعياً مع استهلاك الحد الأدنى من موارد النظام.

مثل سلفه “troff”، يتيح المصطلح “groff” نطقين شائعين: كمقطع لفظي واحد (مثل اللقب)، على وزن “trough”، أو كـ “jee-roff”، تشبيهاً بنطق مختبرات بيل لـ “tee-roff”. لا يوجد خطر كبير من حدوث ارتباك؛ استخدم أيهما يناسبك.

ينظم الأمر groff تنفيذ المعالجات المسبقة، وتحويل مستندات المدخلات إلى لغة وصف صفحات مستقلة عن الجهاز، وإنتاج المخرجات من تلك اللغة.

الخيارات
يعرض الخياران -h و --help رسالة الاستخدام ثم يخرجان.

نظراً لأن groff يهدف إلى استيعاب معظم عمليات الاستدعاء المباشرة للمستخدمين لمنسق troff(1) ، فإن البرنامجين يشتركان في مجموعة من الخيارات. ومع ذلك، يمتلك groff بعض الخيارات التي لا يشاركه فيها troff، وأخرى يفسرها groff بشكل مختلف. وفي الوقت ذاته، لا يمكن إعطاء جميع خيارات troff الصالحة إلى groff.

  خيارات خاصة بـ groff
الخيارات التالية إما أنها غير موجودة في GNU troff أو يفسرها groff بشكل مختلف.

-D ترميز
    استخدم ترميز كترميز مدخلات احتياطي لـ preconv(1)'s ؛ يستلزم الخيار -k.

-e  شغّل المعالج المسبق eqn(1)

-g  شغّل المعالج المسبق grn(1)

-G  شغّل المعالج المسبق grap(1) ؛ يستلزم الخيار -p.

-I دليل
    يعمل كخيار troff (انظر أدناه)، لكنه يستلزم أيضاً الخيارين -g و -s. يمرر groff خيارات -I ومعطياتها إلى soelim(1), و troff(1), ومشغلات المخرجات؛ ومع تغيير حرف الخيار إلى -M، فإنه يمرر نفس المعطيات إلى grn(1).

-j  شغّل المعالج المسبق chem(1) ؛ يستلزم الخيار -p.

-k  شغّل المعالج المسبق preconv(1) ارجع إلى صفحة دليله لمعرفة سلوكه في حال لم يُحدد أي من خياري groff الـ -K أو -D أيضاً.

-K ترميز
    اضبط ترميز المدخلات المستخدم بواسطة preconv(1) إلى ترميز؛ يستلزم الخيار -k.

-l  أرسل المخرجات إلى برنامج مجدول للطباعة. يحدد توجيه “print” في ملف وصف الجهاز الأمر المبدئي المراد استخدامه؛ انظر groff_font(5). إذا لم يوجد مثل هذا التوجيه لجهاز المخرجات، this option is ignored. انظر الخيارين -L و -X.

-L معطى
    مرر الـ معطى إلى مجدول الطباعة. إذا لزم استخدام عدة معطيات، فمرر كل واحد منها بخيار -L منفصل. لا يضع groff شرطة خيار سابقة للـ معطى قبل تمريره إلى المجدول.

-M  يعمل كخيار troff (انظر أدناه)، ولكنه يُمرر أيضاً إلى eqn(1), و grap(1), و grn(1).

-N  احظر أسطراً جديدة بين محددات eqn: مرر -N إلى eqn(1).

-p  شغّل المعالج المسبق pic(1)

-P معطى
    مرر الـ معطى إلى المعالج البعدي. إذا لزم استخدام عدة معطيات، فمرر كل واحد منها بخيار -P منفصل. لا يضع groff شرطة خيار سابقة للـ معطى قبل تمريره إلى المعالج البعدي.

-R  شغّل المعالج المسبق refer(1) لا تتوفر آلية لتمرير معطيات إليه؛ تتوفر لمعظم خيارات refer عناصر لغة مكافئة يمكن تحديدها داخل المستند.

-s  شغّل المعالج المسبق soelim(1)

-S  مكّن الوضع الآمن وتجاهل أي خيار -U لاحق. يمرر groff الخيار -S إلى pic(1) و troff(1).

-t  شغّل المعالج المسبق tbl(1)

-T جهاز
    جهّز المخرجات للجهاز جهاز. يمرر groff الخيار -T ومعطاه إلى troff، ثم (ما لم يُستخدم الخيار -Z) يشغل مشغل مخرجات لتحويل مخرجات troff إلى شكل مناسب للجهاز جهاز؛ انظر القسم الفرعي “أجهزة المخرجات” أدناه.

-U  اعمل في الوضع غير الآمن. يمرر groff الخيار -U إلى pic(1) و troff(1).

--version
-v
    اكتب معلومات الإصدار لـ groff وجميع البرامج التي يشغلها إلى دفق الخرج القياسي؛ أي أن سطر الأوامر المعطى يُعالج بالطريقة المعتادة، مع تمرير -v إلى المنسق وأي معالجات مسبقة أو بعدية مستدعاة.

-V  أخرج خط الأنابيب الذي قد يشغله groff إلى دفق الخرج القياسي ثم اخرج. إذا أُعطي أكثر من مرة، فإن groff يكتب خط الأنابيب إلى دفق الخطأ القياسي ويشغله أيضاً.

-X  استخدم gxditview(1) بدلاً من المعالج البعدي المعتاد لـ (معاينة) مستند على شاشة X11. يؤدي دمج هذا الخيار مع “-T ps” إلى استخدام مقاييس خطوط جهاز PostScript، بينما تستخدم خيارات “-T X75” و “-T X75-12” و “-T X100” و “-T X100-12” مقاييس خطوط X11.

-Z  عطّل المعالجة البعدية. تظهر مخرجات troff على دفق الخرج القياسي (ما لم تُكتم باستخدام -z)؛ انظر groff_out(5) لوصف هذا التنسيق.

  خيارات شفافة
تُمرر الخيارات التالية كما هي إلى برنامج التنسيق troff(1) وتُشرح بمزيد من التفصيل في صفحة دليله.

-a  وَلِّد تقريباً نصياً بسيطاً للمخرجات المصفوفة.

-b  اكتب تتبعاً خلفياً (backtrace) إلى مجرى الخطأ القياسي عند كل خطأ أو تحذير.

-c  ابدأ بإخراج ملون معطل.

-C  مكّن وضع توافق AT&T troff؛ يتضمن -c.

-d ctext
-d string=text
    عرّف السلسلة.

-E  ثبّط رسائل خطأ troff؛ يتضمن -Ww.

-f fam
    اضبط عائلة الخط المبدئية.

-F dir
    ابحث في الدليل dir عن دليل جهاز الإخراج المختار لملفات وصف الجهاز والخط.

-i  عالج المدخل القياسي بعد ملفات المدخلات المحددة.

-I دليل
    ابحث في dir عن ملفات المدخلات.

-m mac
    اقرأ حزمة الماكرو mac قبل المدخلات. يمرر groff خيارات -m ومعطياتها إلى eqn(1), و grap(1), و grn(1).

-M dir
    ابحث في الدليل dir عن ملفات الماكرو. يمرر groff خيارات -M ومعطياتها إلى eqn(1), و grap(1), و grn(1).

-n num
    ابدأ ترقيم الصفحات عند num.

-o list
    أخرج فقط الصفحات الموجودة في list.

-r cnumeric-expression
-r register=numeric-expression
    عرّف المسجل.

-S  مكّن الوضع الآمن وتجاهل أي خيار -U لاحق.

-U  اعمل في الوضع غير الآمن.

-w cat
-W cat
    مكّن وثبّط، على التوالي، التحذيرات في الفئة cat.

-z  اكتم إخراج troff المنسق والمستقل عن الجهاز.

الاستخدام
تتبع بنية نظام GNU roff بنية تطبيقات roff الأخرى المستقلة عن الجهاز، وتتكون من معالجات مسبقة، وحزم ماكرو، وبرامج قيادة الإخراج (أو “المعالجات اللاحقة”)، ومجموعة من الأدوات المساعدة، مع وجود برنامج المنسق troff(1) في قلبه. انظر roff(7) لمسح شامل حول كيفية عمل نظام roff.

تجعل برامج الواجهة الأمامية المتوفرة في نظام GNU roff استخدامه أسهل من أنظمة roff التقليدية التي كانت تتطلب بناء أنابيب (pipelines) أو استخدام ملفات مؤقتة لنقل مستند المصدر من شكل قابل للصيانة إلى إخراج جاهز للجهاز. يلخص النقاش أدناه الأجزاء المكونة لنظام GNU roff. إنه يكمل roff(7) بمعلومات خاصة ببرنامج groff.

  البدء
أولئك الذين يفضلون التعلم بالتجربة أو يرغبون في الحصول على رد فعل سريع من النظام قد يرغبون في البدء بمستند “Hello, world!”.

    $ echo "Hello, world!" | groff -Tascii | sed '/^$/d'
    Hello, world!

استُخدم أمر sed(1) فقط لإزالة 65 سطراً فارغاً كانت ستغرق شاشة الطرفية لولا ذلك. (طُوّرت أنظمة roff في أيام الطرفيات الورقية التي كانت تحتوي على 66 سطراً في الصفحة الواحدة.)

قد يفضل مستخدمو اليوم الإخراج إلى طرفية قادرة على عرض ترميز UTF-8.

    $ echo "Hello, world!" | groff -Tutf8 | sed '/^$/d'

إن إنتاج ملفات PDF أو HTML أو DVI الخاص بـ TeX هو أمر بسيط أيضاً. قد يكون الجزء الصعب هو اختيار برنامج عرض للمخرجات.

    $ echo "Hello, world!" | groff -Tpdf > hello.pdf
    $ evince hello.pdf
    $ echo "Hello, world!" | groff -Thtml > hello.html
    $ firefox hello.html
    $ echo "Hello, world!" | groff -Tdvi > hello.dvi
    $ xdvi hello.dvi

  استخدام groff كـ REPL
أولئك الذين يميلون للبرمجة قد يسرهم معرفة أنه يمكنهم استخدام groff في حلقة القراءة-التقييم-الطباعة (REPL). القيام بذلك يمكن أن يكون مفيداً للتحقق من فهم الشخص لسلوك المنسق و/أو الصيغة التي يقبلها. يمكن أن يساعد تفعيل جميع التحذيرات باستخدام -ww في تحقيق هذا الهدف.

    $ groff -ww -Tutf8
    \# هذا تعليق. لنعرّف مسجلاً.
    .nr a 1
    \# قم بإجراء عمليات حسابية صحيحة مع تقييم العوامل من اليسار إلى اليمين.
    .nr b \n[a]+5/2
    \# لنحصل على النتيجة في مجرى الخطأ القياسي.
    .tm \n[b]
    3
    \# الآن سنعرف سلسلة نصية.
    .ds name Leslie\" هذا شكل آخر من أشكال التعليقات.
    .nr b (\n[a] + (7/2))
    \# وسط سطري نص المدخلات القادمين.
    .ce 2
    Hi, \*[name].
    Your secret number is \n[b].
    \# سنرى أن القسمة قُرّبت نحو الصفر.
    It is
    \# إليك بنية تحكم if-else.
    .ie (\n[b] % 2) odd.
    .el even.
    \# تضبط هذه الخدعة طول الصفحة عند الموضع العمودي
    \# الحالي، حتى لا تندفع الأسطر الفارغة عند الانتهاء.
    .pl \n[nl]u
    <Control-D>
                               Hi, Leslie.
                        Your secret number is 4.
    It is even.

  تنسيق الورق
يقرأ المنسق ملف وصف الجهاز DESC لجهاز الإخراج المحدد عند البدء؛ وتُستخدم أبعاد الصفحة المصرح عنها هناك إن وُجدت. تضبط عملية بناء groff تنسيق صفحة مبدئي وتكتبه في ملفات DESC الخاصة بالمنضدات. هذا التثبيت يضبط مبدئياً على “A4”. إذا كان ملف DESC يفتقر إلى هذه المعلومات، يستخدم المنسق وبرنامج قيادة الإخراج طول صفحة قدره “11i” (أحد عشر بوصة) للتوافق مع AT&T troff. انظر groff_font(5).

في المنسق، يغير طلب pl طول الصفحة، لكن حزم الماكرو غالباً لا تدعم تغيير تنسيق الورق داخل المستند. قد يرغب المرء، على سبيل المثال، في التبديل بين الاتجاهين الطولي والعرضي. تفتقر حزم الماكرو إلى نهج متسق لضبط المعاملات التي تعتمد على تنسيق الورق؛ فبعضها، مثل ms، يستفيد من ديباجة في المستند تسبق أول استدعاء للماكرو، بينما تتطلب حزم أخرى، مثل mm، بدلاً من ذلك تحديد المسجلات في سطر الأوامر، أو قبل تفسير ملف الماكرو الخاص بها، لضبط أبعاد الصفحة.

تتعرف برامج قيادة الإخراج للمنضدات أيضاً على خيارات سطر الأوامر -p لتجاوز أبعاد الصفحة المبدئية و -l لاستخدام الاتجاه العرضي. قد تكون صفحة دليل برنامج قيادة الإخراج، مثل grops(1), مفيدة.

يُعد خيار سطر الأوامر “-d paper” في groff وسيلة مريحة لضبط تنسيق الورق؛ انظر groff_tmac(5). اجمعه مع خيارات -P المناسبة لبرنامج قيادة الإخراج، متجاوزاً إعداداته المبدئية. يقوم الأمر التالي بالتنسيق لـ PostScript على ورق A4 بالاتجاه العرضي.

        $ groff -T ps -d paper=a4l -P -pa4 -P -l -ms my.ms >my.ps

  الواجهة الأمامية
يغلف برنامج groff الأداة troff(1), مما يسمح للشخص بتحديد المعالجات المسبقة عبر خيارات سطر الأوامر وتشغيل برنامج قيادة الإخراج المناسب لجهاز الإخراج المختار. تتجنب هذه الميزة البناء اليدوي للأنابيب أو إدارة الملفات المؤقتة التي كانت مطلوبة من مستخدمي أنظمة roff(7) التقليدية. استخدم grog(1) لاستنتاج سطر أوامر groff مناسب لتنسيق مستند.

  اللغة
تكون المدخلات إلى نظام roff في شكل نص مجرد تتخلله خطوط تحكم وتسلسلات هروب. يشكل هذا المزيج مستنداً بإحدى لغات العائلة التي نسميها أيضاً roff؛ انظر roff(7) للاطلاع على الخلفية. يمكن العثور على نظرة عامة على بناء جملة لغة GNU roff وميزاتها، بما في ذلك قوائم بجميع تسلسلات الهروب والطلبات والمسجلات المحددة مسبقاً المدعومة، في groff(7). فُصّلت امتدادات GNU roff للغة AT&T troff، وهي مجموعة فرعية مشتركة من لهجات roff الموجودة اليوم، في groff_diff(7).

  المعالجات المسبقة
يفسر المعالج المسبق لغة خاصة بمجال معين تنتج مخرجات بلغة roff. غالباً ما يقتصر مثل هذا المدخل على أقسام أو مناطق من مدخلات roff (محصورة باستدعاءات ماكرو خاصة بكل معالج مسبق)، والتي يقوم باستبدالها. لذلك، غالباً ما تفسر المعالجات المسبقة مجموعة فرعية من بناء جملة roff جنباً إلى جنب مع لغتها الخاصة. يوفر GNU roff إعادة تطبيق لمعظم المعالجات المسبقة المألوفة لمستخدمي AT&T troff؛ وعادة ما تحتوي هذه على ميزات ممتدة و/أو تتطلب GNU troff لتنسيق مخرجاتها.

    tbl | ينسق الجداول؛
    eqn | ينضد الرياضيات؛
    pic | يرسم الرسوم البيانية؛
    refer | يعالج المراجع البيبليوغرافية؛
    soelim | يعالج مسبقاً ملفات المدخلات “المصدرية”؛
    grn | يصيّر الرسوم البيانية؛
    chem | يرسم الصيغ البنائية الكيميائية باستخدام pic؛
    gperl | يملاً سجلات وسلاسل groff باستخدام
    glilypond | يضمن نوتة LilyPond الموسيقية؛ و
    gpinyin | يسهل إدخال لغة الماندرين الصينية باستخدام هانيو بينيين.

يعد preconv(1), معالجًا قبليًا فريدًا لـ GNU roff، حيث يحول ترميزات المدخلات المختلفة إلى شيء يمكن لـ GNU troff فهمه. عند استخدامه، يُشغّل قبل أي معالجات قبلية أخرى.

تُدرج معظم المعالجات القبلية المحتوى بين زوج من العلامات المميزة. يجب أن تظهر هذه العلامة في بداية سطر المدخلات وتستخدم محرف التحكم بالنقطة. يجب ألا تتبع المسافات وعلامات الجدولة محرف التحكم أو تسبق نهاية سطر المدخلات. يؤدي الانحراف عن هذه القواعد إلى إفشال تعرف المعالج القبلي على العلامة. تُحفظ العلامات عمومًا في مخرجات المعالج القبلي وتُفسر لاحقًا كاستدعاءات ماكرو بواسطة troff. المعالج القبلي ideal ليس متاحًا بعد في groff.

المعالج القبلي | علامة البداية | علامة النهاية
chem | .cstart | .cend
eqn | .EQ | .EN
grap | .G1 | .G2
grn | .GS | .GE
ideal | .IS | .IE
 |  | .IF
pic | .PS | .PE
 |  | .PF
 |  | .PY
refer | .R1 | .R2
tbl | .TS | .TE
glilypond | .lilypond start | .lilypond stop
gperl | .Perl start | .Perl stop
gpinyin | .pinyin start | .pinyin stop

  حزم الماكرو
ملفات الماكرو هي ملفات مدخلات roff صُممت بحيث لا تنتج مخرجات بنفسها ولكنها تسهل إعداد مستندات roff الأخرى. عندما يُثبت ملف ماكرو في موقع قياسي ويكون مناسبًا للاستخدام من قبل جمهور عام، فإنه يُسمى حزمة ماكرو.

يُحمل الخيار -m حزمة ماكرو قبل أي مستندات مدخلات roff، وبعد إجراء أي تعيينات للسلاسل والسجلات التي توجهها الخيارات -d و -r. ينفذ نظام GNU roff معظم حزم الماكرو المعروفة لـ AT&T troff بطريقة متوافقة ويوسعها. تمتلك هذه الحزم أسماء من حرف أو حرفين ناتجة عن ممارسات الاقتصاد المكثف في التسمية في ثقافة يونكس المبكرة، وهو نهج مقتضب أدى إلى تحديد العديد من الحزم في الاستخدام العام من خلال حرف خيار nroff و troff المستخدم لاستدعائها، وأحيانًا مع تأثير التورية، كما هو الحال مع “man” (اختصار لـ “manual”)، وحتى مع واصلة الخيار، كما في حالة حزمة s، المعروفة بشكل أفضل باسم ms أو حتى -ms.

تخدم حزم الماكرو مجموعة متنوعة من الأغراض. بعضها حزم “كاملة الخدمة”، حيث تتولى مسؤولية تخطيط الصفحة بين المهام الأساسية الأخرى، وتحدد معجمها الخاص من الماكرو لتكوين المستندات؛ كل حزمة من هذا القبيل تقف بمفردها ويمكن لمستند معين استخدام حزمة واحدة على الأكثر.

an  تُستخدم لتكوين صفحات الدليل بالتنسيق الذي نشأ في الإصدار 7 من يونكس (1979)؛ انظر groff_man(7). يمكن تحديدها على سطر الأوامر كـ -man.

doc تُستخدم لتكوين صفحات الدليل بالتنسيق الذي نشأ في 4.3BSD-Reno (1990)؛ انظر groff_mdoc(7). يمكن تحديدها على سطر الأوامر كـ -mdoc.

e   هي مجموعة ماكرو بيركلي للأغراض العامة، طُورت كبديل لـ s من AT&T؛ انظر groff_me(7). يمكن تحديدها على سطر الأوامر كـ -me.

m   تنفذ التنسيق المستخدم من قبل الجيل الثاني من مجموعة ماكرو AT&T للمستندات العامة، وهي خليفة لـ s؛ انظر groff_mm(7). يمكن تحديدها على سطر الأوامر كـ -mm.

om  (تُسمى دائمًا “mom”) هي حزمة حديثة كتبها بيتر شافتر خصيصًا لـ GNU roff. راجع دليل HTML الخاص بـ mom في file:///usr/share/doc/groff-1.24.1/html/mom/toc.html للحصول على توثيق مكثف. هي—حيث تأخذ mom ضمير المؤنث—يمكن تحديدها على سطر الأوامر كـ -mom.

s   هو تنسيق مستندات AT&T الأصلي للأغراض العامة؛ انظر groff_ms(7). يمكن تحديده على سطر الأوامر كـ -ms.

أما الحزم الأخرى فهي تكميلية. على سبيل المثال، andoc هي حزمة تغليف خاصة بـ GNU roff تتعرف على ما إذا كان المستند يستخدم تنسيق man أو mdoc وتُحمل حزمة الماكرو المقابلة. يمكن تحديدها على سطر الأوامر كـ -mandoc. قد يستخدم أمين مكتبة man(1) ملف الماكرو هذا لتفويض تحميل حزمة الماكرو الصحيحة؛ وبالتالي ليس من الضروري لـ man نفسه فحص محتويات المستند لاتخاذ القرار.

تعزز العديد من ملفات الماكرو وظيفة الحزم كاملة الخدمة، أو مستندات roff التي لا تستخدم مثل هذه الحزمة—وهذه الأخيرة تُوصف أحيانًا بأنها “خام”. تُوصَف هذه الحزم المساعدة، بالإضافة إلى تفاصيل تسمية ملفات الماكرو ومكانها، في groff_tmac(5).

  المنسقات
المنسق، وهو البرنامج الذي يفسر مدخلات لغة roff، هو troff(1). يوفر ميزات برنامجي AT&T troff و nroff بالإضافة إلى العديد من التوسعات. ينقل خيار سطر الأوامر -C برنامج troff إلى وضع التوافق، الذي يحاول محاكاة AT&T troff قدر الإمكان عمليًا لتمكين تنسيق المستندات المكتوبة للنظام القديم.

يحاكي نص صدفة، nroff(1), سلوك AT&T nroff. يحاول ترميز المخرجات بشكل صحيح بناءً على المحلية، مما يريح المستخدم من الحاجة إلى تحديد جهاز إخراج باستخدام الخيار -T، وبالتالي فهو ملائم للاستخدام مع أجهزة إخراج الطرفية، الموصوفة في القسم الفرعي التالي.

يولد GNU troff مخرجات بلغة وصف صفحة مستقلة عن الجهاز، ولكنها ليست منعزلة عنه، وهي مفصلة في groff_out(5).

  أجهزة الإخراج
تُنسق مخرجات troff لـ جهاز إخراج معين، يُحدد عادةً بواسطة الخيار -T للمنسق أو الواجهة الأمامية. إذا لم يُستخدم هذا الخيار ولا متغير البيئة GROFF_TYPESETTER، فإن جهاز الإخراج المبدئي هو ps. يمكن أن يكون جهاز الإخراج أيًا مما يلي.

ascii
    للطرفيات التي تستخدم مجموعة محارف وترميز ISO 646 1991:IRV، المعروفة أيضًا باسم US-ASCII.

dvi لتنسيق TeX DVI.

html
xhtml
    لمخرجات HTML و XHTML، على التوالي.

latin1
    للطرفيات التي تستخدم مجموعة محارف وترميز ISO Latin-1 (8859-1).

lbp لطابعات Canon CaPSL (طابعات الليزر من سلسلتي LBP-4 و LBP-8).

lj4 للطابعات المتوافقة مع HP LaserJet4 (أو غيرها من الطابعات المتوافقة مع PCL5).

pdf لمخرجات PDF.

ps  لمخرجات PostScript.

utf8
    للطرفيات التي تستخدم مجموعة محارف ISO 10646 (“يونيكود”) بترميز UTF-8.

X75 للمعاينة باستخدام gxditview بدقة 75 نقطة في البوصة وحجم خط رئيس قدره 10 نقاط.

X75-12
    للمعاينة باستخدام gxditview بدقة 75 نقطة في البوصة وحجم خط رئيس قدره 12 نقطة.

X100
    للمعاينة باستخدام gxditview بدقة 100 نقطة في البوصة وحجم خط رئيس قدره 10 نقاط.

X100-12
    للمعاينة باستخدام gxditview بدقة 100 نقطة في البوصة وحجم خط رئيس قدره 12 نقطة.

  المعالجات اللاحقة
أي برنامج يفسر مخرجات GNU troff هو معالج لاحق. المعالجات اللاحقة التي يوفرها GNU roff هي سواقات مخرجات، والتي تجهز المستند للمعاينة أو الطباعة. من المتصور وجود معالجات لاحقة لأغراض أخرى، مثل إعادة تسلسل الصفحات أو القياس الإحصائي للمستند.

تدعم سواقة المخرجات جهاز إخراج واحدًا أو أكثر، ولكل منها ملف وصف الجهاز الخاص به. يحدد الجهاز معالجه اللاحق عبر توجيه postpro في ملف وصف الجهاز الخاص به؛ انظر groff_font(5). يتجاوز الخيار -X هذا الاختيار، مما يجعل gxditview يعمل كسواقة للمخرجات.

grodvi(1)
يوفر dvi.

    grohtml(1)
يوفر html و xhtml.

    grolbp(1)
يوفر lbp.

    grolj4(1)
يوفر lj4.

    gropdf(1)
يوفر pdf.

    grops(1)
يوفر ps.

    grotty(1)
يوفر ascii، و latin1، و utf8.

    gxditview(1)
يوفر X75، و X75-12، و X100، و X100-12، ويمكنه بالإضافة إلى ذلك
    معاينة ps.

  أدوات مساعدة
يتضمن GNU roff مجموعة من الأدوات المساعدة.

gdiffmk(1)
يحدد الفروق بين زوج من ملفات مدخلات roff.

    grog(1)
يستنتج أمر groff الذي يتطلبه المستند.

تقوم عدة أدوات مساعدة بتجهيز أوصاف الخطوط، مما يُمكّن المنسق من استخدامها عند إنتاج مخرجات لجهاز معين.

addftinfo(1)
يضيف معلومات إلى ملفات وصف خطوط AT&T troff لتمكين استخدامها مع GNU
    troff.

    afmtodit(1)
ينشئ ملفات وصف الخطوط لخطوط PostScript Type 1.

    pfbtops(1)
يترجم خط PostScript Type 1 من تنسيق PFB (خط طابعة ثنائي) إلى PFA (خط طابعة
    أسكي)، والذي يمكن بعد ذلك تفسيره بواسطة afmtodit.

    hpftodit(1)
ينشئ ملفات وصف الخطوط لعائلة طابعات HP LaserJet 4.

    tfmtodit(1)
ينشئ ملفات وصف الخطوط لجهاز TeX DVI.

    xtotroff(1)
ينشئ ملفات وصف الخطوط لخطوط نظام نوافذ X الأساسية.

تحول ثلاثية من الأدوات المواد التي صُنعت باستخدام لغات المعالجة المسبقة roff إلى ملفات صور رسومية.

eqn2graph(1)
يحول معادلة eqn إلى صورة مقصوصة.

    grap2graph(1)
يحول مخطط grap إلى صورة مقصوصة.

    pic2graph(1)
يحول مخطط pic إلى صورة مقصوصة.

تعمل مجموعة أخرى من البرامج مع ملفات البيانات البيبليوغرافية التي يستخدمها المعالج المسبق refer(1)

indxbib(1)
ينشئ فهارس مقلوبة لقواعد البيانات البيبليوغرافية، مما يسرع عمليات البحث
    فيها.

    lkbib(1)
يبحث في قواعد البيانات.

    lookbib(1)
يبحث في قواعد البيانات بشكل تفاعلي.

حالة الخروج
يخرج groff بنجاح (بالحالة 0) إذا حُدد أي من الخيارين -h أو --help، وبالحالة 2 إذا لم يتمكن البرنامج من تفسير وسائط سطر الأوامر الخاصة به، وبالحالة 1 إذا واجه خطأ أثناء التشغيل. خلاف ذلك، يشغل groff خط أنابيب لمعالجة مدخلاته؛ وإذا خرجت جميع الأوامر داخل خط الأنابيب بنجاح، يفعل groff الشيء نفسه. وإلا، فإن حالة خروج groff ترمّز ملخصًا للمشكلات التي تمت مواجهتها، حيث تضبط البت 2 إذا خرج أمر بحالة فشل، والبت 3 إذا أُنهي أمر بإشارة، والبت 4 إذا تعذر تنفيذ أمر. (بالتالي، إذا حلت المصائب الثلاث بخط الأنابيب، يخرج groff بالحالة 2^2 + 2^3 + 2^4 = 4+8+16 = 28.) لتنقيح مشكلات خط الأنابيب، أعِد تشغيل أمر groff بالخيار -V وقسّم خط الأنابيب المُبلغ عنه إلى مراحل منفصلة، مع فحص حالة الخروج والرسائل التشخيصية الصادرة عن كل أمر.

البيئة
تؤثر متغيرات البيئة في النظام المضيف على سلوك البرامج التي يوفرها groff على النحو التالي. عادةً ما يكون فاصل المسارات في متغيرات البيئة التي تنتهي بـ PATH هو النقطتان الرأسيتان؛ وقد يختلف هذا حسب نظام التشغيل. على سبيل المثال، يستخدم ويندوز الفاصلة المنقوطة بدلاً من ذلك.

GROFF_BIN_PATH
    تحديد موقع أوامر groff في هذه الأدلة، تليها تلك الموجودة في PATH. إذا لم يكن مضبوطًا، يتم البحث في دليل تثبيت ملفات GNU roff التنفيذية، /usr/bin، قبل PATH.

GROFF_COMMAND_PREFIX
    تطبيق بادئة على أوامر GNU roff معينة. يمكن ضبط groff عند وقت التصريف لتطبيق بادئة على أسماء البرامج التي يوفرها والتي لها نظائر في AT&T troff، وذلك لتجنب تصادم الأسماء عند وقت التشغيل. البادئة المبدئية فارغة.

    عند استخدامها، تكون هذه البادئة تقليديًا هي الحرف “g”. على سبيل المثال، سيُثبت GNU troff كـ gtroff. إلى جانب troff، تنطبق البادئة على مغلف المنسق nroff؛ والمعالجات المسبقة eqn، و grn، و pic، و refer، و tbl، و soelim؛ والأدوات المساعدة indxbib و lookbib.

GROFF_ENCODING
    تحديد ترميز المحارف المفترض للمدخلات. يمرر groff قيمته كوسيط لخيار -e الخاص بالمعالج المسبق preconv(1). وجود هذا المتغير يقتضي استخدام خيار groff‏ -k. إذا ضُبط وكان فارغًا، يُشغل groff البرنامج preconv بدون الخيار -e. خيار groff‏ -K يتخطى GROFF_ENCODING.

GROFF_FONT_PATH
    ابحث عن دليل ملفات وصف الجهاز والخطوط لجهاز الإخراج المحدد في قائمة الأدلة هذه. انظر troff(1) و groff_font(5).

GROFF_TMAC_PATH
    ابحث عن حزم الماكرو في قائمة الأدلة هذه. انظر troff(1) و groff_tmac(5).

GROFF_TMPDIR
    تُنشأ الملفات المؤقتة في هذا الدليل. إذا لم يُضبط، وكان TMPDIR مضبوطًا، فيُستخدم الأخير بدلاً منه. في أنظمة ويندوز، إذا لم يُضبط أي مما سبق، تُفحص متغيرات البيئة TMP و TEMP (بهذا الترتيب) أيضًا. خلاف ذلك، تُنشأ الملفات المؤقتة في /tmp. تستخدم الأوامر refer(1), و grohtml(1), و grops(1) ملفات مؤقتة.

GROFF_TYPESETTER
    اضبط جهاز الإخراج المبدئي. إذا كان فارغًا أو غير مضبوط، يُستخدم ps. خيار -T يتخطى GROFF_TYPESETTER.

SOURCE_DATE_EPOCH
    أعلن عن طابع زمني (مُعبر عنه بالثواني منذ حقبة يونكس) لاستخدامه كطابع زمني لإنشاء المخرجات بدلاً من الوقت الحالي. يُحول الوقت إلى صيغة مقروءة بشريًا باستخدام gmtime(3) و asctime(3) عند بدء تشغيل المنسق ويُخزن في مسجلات قابلة للاستخدام بواسطة المستندات وحزم الماكرو.

TZ  أعلن عن المنطقة الزمنية لاستخدامها عند تحويل الوقت الحالي إلى صيغة مقروءة بشريًا؛ انظر tzset(3). إذا استخدم SOURCE_DATE_EPOCH، فسيُحول دائمًا إلى صيغة مقروءة بشريًا باستخدام التوقيت العالمي المنسق (UTC).

أمثلة
تشتهر أنظمة roff بتنسيق صفحات الدليل. برنامج أمين مكتبة man(1) ، بعد تحديد مكان الصفحة، قد يُصيرها باستخدام أمر groff.
        groff -t -man -Tutf8 /usr/share/man/man1/groff.1
سيقوم أمين المكتبة أيضًا بتمرير المخرجات عبر برنامج عرض (pager)، والذي قد لا يفسر تسلسلات هروب الطرفية التي يصدرها groff للخط العريض، أو التسطير، أو الخط المائل، أو الروابط التشعبية؛ انظر قسم “القيود” أدناه.

لمعالجة ملف إدخال roff باستخدام المعالجات المسبقة tbl و pic وحزمة الماكرو me بالطريقة التي اعتاد عليها مستخدمو AT&T troff، يكتب المرء (أو يبرمج) أنبوب أوامر.

        pic foo.me | tbl | troff -me -Tutf8 | grotty

اختصر أنبوب الأوامر هذا إلى أمر مكافئ باستخدام groff.

        groff -p -t -me -T utf8 foo.me

هناك طريقة أسهل للقيام بذلك وهي استخدام grog(1) لتخمين خيارات المعالج المسبق والماكرو وتنفيذ النتيجة باستخدام ميزة استبدال الأوامر في الـ صدفة.

        $(grog -Tutf8 foo.me)

يجب تحديد كل خيار سطر أوامر لمعالج لاحق مع أي شرطات بادئة مطلوبة “-” لأن groff يمرر الوسائط كما هي إلى المعالج اللاحق؛ وهذا يسمح بنقل وسائط عشوائية. على سبيل المثال، لتمرير عنوان إلى المعالج اللاحق gxditview، فإن أوامر الـ صدفة
        groff -X -P -title -P 'trial run' mydoc.t
و
        groff -X -Z mydoc.t | gxditview -title 'trial run' -
متكافئان.

القيود
عند عرض المخرجات لصفحة لأجهزة ascii و latin1 و utf8، قد تتطلب برامج مثل more(1) و less(1) خيارات سطر أوامر للتعامل بشكل صحيح مع بعض تسلسلات هروب الطرفية؛ انظر grotty(1).

أدلة التثبيت
يثبت GNU roff الملفات في مواقع مختلفة اعتمادًا على تهيئة وقت التجميع. في هذا التثبيت، تُستخدم المواقع التالية.

/usr/lib/X11/app-defaults
    Application defaults directory for gxditview(1).

/usr/bin
    الدليل الذي يحتوي على أوامر groff التنفيذية.

/usr/share/groff/1.24.1/eign
    قائمة الكلمات الشائعة لـ indxbib(1).

/usr/share/groff/1.24.1
    دليل ملفات البيانات.

/usr/dict/papers/Ind
    الفهرس المبدئي لـ lkbib(1) و refer(1).

/usr/share/doc/groff-1.24.1
    دليل الوثائق.

/usr/share/doc/groff-1.24.1/examples
    دليل الأمثلة.

/usr/share/groff/1.24.1/font
    دليل الخطوط.

/usr/share/doc/groff-1.24.1/html
    دليل وثائق HTML.

/usr/lib/font
    دليل الخطوط القديم.

/usr/share/groff/site-font
    دليل الخطوط المحلي.

/usr/share/groff/site-tmac
    دليل حزم الماكرو المحلي (ملفات tmac).

/usr/share/groff/1.24.1/tmac
    دليل حزم الماكرو (ملفات tmac).

/usr/share/groff/1.24.1/oldfont
    دليل الخطوط للتوافق مع الإصدارات القديمة من groff؛ انظر grops(1).

/usr/share/doc/groff-1.24.1/pdf
    دليل وثائق PDF.

  دليل ماكرو groff
تُخزن معظم ملفات الماكرو المرفقة مع GNU roff في /usr/share/groff/1.24.1/tmac للتثبيت المقابل لهذا المستند. كقاعدة عامة، يُبحث في أدلة متعددة عن ملفات الماكرو؛ انظر troff(1). للحصول على فهرس لملفات الماكرو التي يوفرها GNU roff، انظر groff_tmac(5).

  دليل وصف الجهاز والخطوط لـ groff
تُخزن ملفات وصف الجهاز والخطوط المرفقة مع GNU roff في /usr/share/groff/1.24.1/font للتثبيت المقابل لهذا المستند. كقاعدة عامة، يُبحث في أدلة متعددة عن ملفات وصف الجهاز والخطوط؛ انظر troff(1). لصيغ هذه الملفات، انظر groff_font(5).

التوفر
يمكن الحصول على روابط إصدارات groff للتنزيل، ومستودع المصدر الخاص به، والقوائم البريدية للمناقشة، ومتتبع تذاكر الدعم، ومزيد من المعلومات من صفحة groff على موقع GNU الإلكتروني http://www.gnu.org/software/groff.

يمكن العثور على تنفيذ حر للمعالج المسبق grap، كتبه تيد فابر (faber@lunabase.org), في موقع grap الإلكتروني http://www.lunabase.org/~faber/Vault/software/grap/. يدعم groff هذا الـ grap فقط.

المؤلفون
كُتب groff (سواء أمر الواجهة الأمامية أو النظام ككل) بشكل رئيس بواسطة جيمس كلارك (jjc@jclark.com). المساهمون في هذا المستند يشملون كلارك، وتيرينت أ. فيشر، و فيرنر ليمبيرج (wl@gnu.org), و بيرند واركن (groff-bernd.warken-72@web.de), و ج. براندن روبنسون (g.branden.robinson@gmail.com).

انظر أيضاً
Groff: The GNU Implementation of troff، من تأليف Trent A. Fisher و Werner Lemberg، هو دليل groff الرئيس. يمكنك تصفحه تفاعليًا باستخدام “info groff”.

تلي ذلك قائمة بجميع صفحات دليل groff. سيكون عدد قليل منها (grohtml و gropdf و gxditview و xtotroff) غير متاح إذا عُطلت البرامج المقابلة لها أثناء التجميع.

مقدمة، وتاريخ، وقراءات إضافية:
    roff(7)

عارض لمستندات groff (و AT&T المستقلة عن الأجهزة troff):
    gxditview(1)

المعالجات المسبقة:
    chem(1), eqn(1), neqn(1), glilypond(1), grn(1), preconv(1), gperl(1), pic(1), gpinyin(1), refer(1), soelim(1), tbl(1)

حزم الماكرو:
    groff_hdtbl(7), groff_man(7), groff_man_style(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mmse(7), groff_mom(7), groff_ms(7), groff_rfc1345(7), groff_trace(7), groff_www(7)

أدوات إدارة قواعد البيانات البيبليوغرافية:
    indxbib(1), lkbib(1), lookbib(1)

اللغة، والاصطلاحات، وامتدادات جنو:
    groff(7), groff_char(7), groff_diff(7), groff_font(5), groff_tmac(5)

لغة وصف الصفحة المستقلة عن الجهاز:
    groff_out(5)

برنامج المنسق:
    troff(1)

مغلفات المنسق:
    nroff(1), mmroff(1), pdfmom(1)

معالجات بعدية لأجهزة الإخراج:
    grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1)

أدوات دعم الخطوط:
    addftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1)

أدوات تحويل الرسوميات:
    eqn2graph(1), grap2graph(1), pic2graph(1)

أداة وسم الاختلافات:
    gdiffmk(1)

أداة “تخمين جروف”:
    grog(1)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.