نام (NAME)

lowdown-diff — محاسبه و نمایش تفاوت‌های دو سند مارک‌داون

خلاصه دستور (SYNOPSIS)

lowdown-diff [input_options] [output_options] [-s] [-M metadata] [-m metadata] [-o file] [-t mode] oldfile [newfile]

توضیحات (DESCRIPTION)

تفاوت‌های میان اسناد lowdown(5) را به صورت خروجی قالب‌بندی‌شده نمایش می‌دهد. نتایج در خروجی استاندارد نوشته می‌شوند.

آرگومان‌های کوتاه به شرح زیر هستند:

-s: تولید یک سند مستقل (مثلاً یک سند معتبر HTML شامل نوع سند، head و غیره) پیرامون محتوای قالب‌بندی‌شده. برای جزئیات به بخش Standalone documents مراجعه کنید.
-M metadata: ارائه یک جفت کلید-مقدار متاداده منفرد. این مقدار می‌تواند با نحو معمولی یا به صورت جفت‌های جدا شده با علامت مساوی باشد، بسته به اینکه کدام نویسه (دونقطه یا علامت مساوی) زودتر ظاهر شود. اگر هیچ‌کدام ارائه نشود، برنامه با خطا خارج می‌شود. این گزینه بر -m و آنچه از سند تجزیه شده برتری دارد (آن‌ها را بازنویسی می‌کند). به بخش Metadata. مراجعه کنید.
-m metadata: مشابه -M, اما توسط آنچه از سند تجزیه شده، و سپس توسط -M بازنویسی می‌شود.
-o file: ارسال خروجی به file مگر اینکه “-” باشد، که در این حالت خروجی پیش‌فرض استاندارد استفاده می‌شود.
-t mode, -T mode: حالت خروجی. می‌تواند شامل موارد زیر باشد: html برای خروجی HTML5، latex برای LaTeX، gemini برای قالب “gemtext” پروژه Gemini، ms برای خروجی roff با استفاده از بسته -mspdf و نیازمند پشتیبانی از جدول، term برای خروجی ترمینال سازگار با ANSI و UTF-8، man برای خروجی roff با استفاده از بسته -man, mdoc برای خروجی roff با استفاده از بسته -mdoc, tree, برای نمایش درخت تجزیه سند ورودی، و null برای تجزیه سند بدون رندر کردن آن. به بخش Output media. مراجعه کنید. شکل -T mode برای سازگاری با گذشته حفظ شده است.
oldfile, newfile: اسناد مارک‌داون مورد استفاده برای مقایسه. اگر newfile مشخص نشود یا “-” باشد، از ورودی استاندارد خوانده می‌شود.

موارد زیر گزینه‌های طولانی برای تجزیه ورودی هستند. این گزینه‌ها بر درخت تجزیه ارائه‌شده به تمام خروجی‌ها تأثیر می‌گذارند.

--parse-hilite: فعال‌سازی پشتیبانی از محدوده‌های هایلایت (برجسته‌سازی). این گزینه به‌طور پیش‌فرض غیرفعال است زیرا ممکن است به اشتباه به‌عنوان سرتیتر بخش‌ها تفسیر شود.
--parse-math: شناسایی معادلات ریاضی.
--parse-maxdepth=depth: حداکثر عمق عناصر تو در تو. پیش‌فرض آن 128 است که احتمالاً برای هر سند واقعی بیش از اندازه کافی است. اگر این حد نصاب فرارسد، سیستم طوری خارج می‌شود که گویی حافظه تمام شده است. تنظیم آن روی صفر به معنی عدم وجود محدودیت است.
--parse-no-autolink: پیوندهای http, https, ftp, mailto, و پیوندهای نسبی یا قطعه‌های پیوند را تجزیه نکن.
--parse-no-cmark: با محدودیت‌های CommonMark تجزیه نکن. این گزینه همچنین استفاده از اولین مقدار لیست مرتب‌شده به‌جای شروع همه لیست‌ها از یک را غیرفعال می‌کند.
--parse-no-codeindent: محتوای دندانه‌دار را به عنوان بلوک‌های کد تجزیه نکن.
--parse-no-callouts: کادرهای اطلاعاتی (callouts) مربوط به GFM/MDN (“admonitions”) را تجزیه نکن.
--parse-no-deflists: لیست‌های تعریفی PHP extra را تجزیه نکن.
--parse-no-ext-attrs: ویژگی‌های توسعه‌یافته PHP extra را تجزیه نکن.
--parse-no-fenced: بلوک‌های کد محصور (fenced) مخصوص زبان در GFM را تجزیه نکن.
--parse-no-footnotes: پاورقی‌های MMD را تجزیه نکن.
--parse-no-img-ext: منسوخ شده است. به --parse-no-ext-attrs. مراجعه کنید.
--parse-no-intraemph: تأکید درون واژه‌ها و پیوندها را تجزیه نکن.
--parse-no-mantitle: عنوان، بخش، منبع و جلد صفحه راهنما را از فراداده‌های عنوان Pandoc تجزیه نکن. عنوان صفحات راهنما با یک عنوان و سپس یک پرانتز باز، رقم به همراه نویسه‌های اختیاری و سپس پرانتز بسته مشخص می‌شود.
--parse-no-metadata: متاداده‌ها را تجزیه نکن. این گزینه بر متاداده‌های ارائه‌شده در -m یا -M تأثیری ندارد.
--parse-no-strike: خط‌خوردگی‌ها (strikethroughs) را تجزیه نکن.
--parse-no-super: بالانویس‌ها یا زیرنویس‌ها را به هیچ وجه تجزیه نکن.
--parse-no-tables: جدول‌های GFM را تجزیه نکن.
--parse-no-tasklists: لیست‌های وظایف GFM را تجزیه نکن.
--parse-super-short: اگر تجزیه بالانویس فعال باشد، از نحو سنتی غیر GFM به صورت “short” استفاده کن.

گزینه‌های طولانی متعددی برای خروجی وجود دارد. موارد زیر میان تمام رسانه‌های خروجی مشترک هستند:

--out-standalone: نام مستعار برای -s.
--out-no-smarty: از فیلتر تایپوگرافی هوشمند استفاده نکن. به‌طور پیش‌فرض، برخی توالی‌های نویسه‌ای به نشانه‌های گرافیکی (گلیف‌های) مخصوص خروجی تبدیل می‌شوند.
--template template: هنگام تولید خروجی مستقل -s, از یک فایل الگو استفاده کن. به بخش Templates. مراجعه کنید. در حال حاضر تنها برای -tgemini, -thtml, -tlatex, -tman, -tms, و -ttree.

در ادامه گزینه‌های طولانی اختصاصی هر خروجی آمده است. برای HTML با -thtml, این گزینه‌ها به شرح زیر هستند:

--html-callout-mdn, --html-callout-gfm: خروجی دادن نحو کادرهای اطلاعاتی (callout) مربوط به MDN یا GFM یا هر دو.
--html-hardwrap: شکستن سخت خطوط محتوای پاراگراف با قرار دادن شکستگی خط (line break) در جاهای لازم.
--html-no-escapehtml: اگر --html-no-skiphtml مشخص شده باشد، باعث می‌شود HTML جاسازی‌شده اسکیپ نشود و در عوض عیناً در خروجی درج گردد. اگر --html-no-skiphtml مشخص نشده باشد، این گزینه هیچ تأثیری ندارد.
--html-no-head-ids: ویژگی‌های id را برای سرتیترها در خروجی درج نکن.
--html-no-num-ent: موجودیت‌های HTML (در صورت امکان) به موجودیت‌های عددی نرمال‌سازی نشوند و در عوض از همان موجودیت‌های ارائه‌شده در ورودی استفاده شود.
--html-no-owasp: از توصیه‌های OWASP برای اسکیپ کردن متن پیروی نکن، و تنها حداقل اسکیپ‌سازی را انجام بده تا مطمئن شوی محتوای معمولی به عنوان HTML تفسیر نمی‌شود.
--html-no-skiphtml: HTML جاسازی‌شده را در خروجی درج کن. به‌طور پیش‌فرض، HTML جاسازی‌شده به هیچ وجه در خروجی درج نمی‌شود. به --html-no-escapehtml. مراجعه کنید.
--html-titleblock: در صورت تجزیه شدن، اطلاعات عنوان (عنوان، نویسنده، تاریخ) را در قالب یک عنصر سرتیتر که در ابتدای سند ظاهر می‌شود قالب‌بندی کن.

برای قالب‌های roff یعنی -tman, -tmdoc, و -tms (مگر در مواردی که ذکر شده), گزینه‌های زیر اعمال می‌شوند:

--roff-code-font=fonts: جایگزین کردن فونت‌های پیش‌فرض با عرض ثابت با یک چندتایی (tuple) از گونه‌های عادی، بولد، ایتالیک و بولد-ایتالیک به همین ترتیب. به عنوان مثال، B,B,BI,BI به جای عرض ثابت، از بولد (“B”) استفاده می‌کند. عدم تعیین فونت یا تعیین نام فونت با طول صفر، از پیش‌فرض استفاده خواهد کرد. نام‌های مستعار none, bold, و code به ترتیب هیچ فونت خاصی، فونت بولد و فونت پیش‌فرض عرض ثابت را تنظیم می‌کنند.
--roff-endnotes: به تعویق انداختن چاپ پاورقی‌ها تا انتهای سند. تنها برای -tms کاربرد دارد، چرا که -tman و -tmdoc تنها از یادداشت‌های پایانی (endnotes) پشتیبانی می‌کنند.
--roff-manpage: قالب‌بندی خروجی به صورت یک صفحه راهنما (manpage). این گزینه پاراگراف‌های ذیل بخش‌های NAME, SYNOPSIS, و SEE ALSO را در قالب استاندارد مورد استفاده صفحات راهنما بازآرایی می‌کند. نحوه قالب‌بندی سند به متاداده بخش بستگی دارد: 1، 6 و 8 برای سبک برنامه‌ای؛ 2، 3 و 9 برای سبک تابعی. سبک برنامه‌ای فلگ‌ها و آرگومان‌ها را بازآرایی می‌کند، در حالی که سبک تابعی نام توابع، متغیرها و آرگومان‌ها را بازآرایی می‌کند. هرگونه محتوا در محدوده‌های فونت (مانند تأکید یا تأکید دوگانه) در سایر بخش‌ها، فونت آن‌ها حذف شده و به همان شیوه بازآرایی می‌شوند. تنها برای -tman و -tmdoc. اعمال می‌شود.
--roff-no-numbered: سرتیترهای شماره‌دار را در خروجی درج نکن (.NH NN). تنها برای -tms. اعمال می‌شود.
--roff-no-skiphtml: HTML جاسازی‌شده را در خروجی درج کن. این کار معمولاً منطقی نیست زیرا HTML توسط خواننده خروجی تفسیر نخواهد شد. به‌طور پیش‌فرض، HTML حذف می‌شود.
--roff-no-links: در صورت امکان، آدرس‌های اینترنتی (URL) را برای تصاویر و پیوندها نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه‌های --roff-short-links و --roff-no-rellinks. تقدم دارد.
--roff-no-rellinks: در صورت امکان، آدرس‌های اینترنتی را برای پیوندهای نسبی نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه --roff-short-links. تقدم دارد.
--roff-short-links: در صورت امکان، نشانی‌های وب برای تصاویر، پیوندها و پیوندهای خودکار را فقط به نام دامنه و مسیر نهایی کوتاه کن.
--roff-traditional: خروجی سنتی -ms (نه -mspdf) و -man بدون افزونه‌ها تولید کن. به‌ویژه، از ماکروهای پیوند (.pdfhref, .UR, .MT), جدول‌های چندصفحه‌ای (.TS H, .TH), نحو توالی یونیکد (\[uNNNN]), ماکروهای بلوک مثال (.EX), سرتیترهای مدرن بخش‌ها (.NH NN, .SH NN, .pdfhref O NN), یا پیوندهای درون‌سندی (.pdfhref L) استفاده نکن. خروجی با ابزار سنتی troff(1) سازگار خواهد بود.

پیشوند آرگومان --nroff, مانند --nroff-traditional, به نفع --roff منسوخ شده است.

خروجی -tterm دارای گزینه‌های زیر است:

--term-all-metadata: اگر -s مشخص شده باشد، به جای فقط عنوان، نویسنده و تاریخ، تمام متاداده‌ها را خروجی می‌دهد.
--term-columns=columns: تعداد ستون‌ها در ترمینال. هنگام اجرا در یک لوله (pipe) مفید است. پیش‌فرض آن مقداری است که ترمینال گزارش می‌کند، یا 72 اگر در ترمینال نباشد.
--term-hmargin=margin: تعداد نویسه‌های حاشیه چپ. پیش‌فرض صفر است. همچنین می‌تواند auto باشد تا حاشیه چپ را برابر با نصف باقیمانده --term-columns پس از کسر --term-width قرار دهد.
--term-hpadding=padding: تعداد نویسه‌های فاصله‌گذاری (padding) چپ. پیش‌فرض چهار است. فاصله‌گذاری از مقدار --term-width کسر می‌شود.
--term-no-ansi: سبک‌های ANSI را اصلاً نمایش نده. این گزینه متضمن --term-no-colour. است.
--term-no-colour: رنگ‌های ANSI را نمایش نده. متن همچنان با زیرخط، بولد و ایتالیک آراسته می‌شود، اما هیچ کد رنگی ارسال نخواهد شد.
--term-no-links: در صورت امکان، آدرس‌های اینترنتی را برای تصاویر و پیوندها نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه‌های --term-short-links و --term-no-rellinks. تقدم دارد.
--term-no-rellinks: در صورت امکان، آدرس‌های اینترنتی را برای پیوندهای نسبی نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه --term-short-links. تقدم دارد.
--term-short-links: در صورت امکان، نشانی‌های وب برای تصاویر، پیوندها و پیوندهای خودکار را فقط به نام دامنه و مسیر نهایی کوتاه کن.
--term-vmargin=margin: تعداد خطوط خالی حاشیه بالا و پایین. پیش‌فرض صفر است.
--term-width=width: حد نرم برای تعداد نویسه‌ها در هر خط شامل (--term-hpadding). متن‌های دقیق (literal) ممکن است از این مقدار فراتر بروند. اگر صفر باشد یا تنظیم نشود، پیش‌فرض آن --term-columns یا حداکثر 80 است. بر روی --term-columns. برش می‌خورد.

خروجی -tgemini دارای چندین فلگ است که محل قرارگیری پیوندها را کنترل می‌کنند. به‌طور پیش‌فرض، پیوندها (تصاویر، پیوندهای خودکار و پیوندها) در صورت مشخص شدن درون‌خطی، در صف قرار می‌گیرند و سپس به صورت یک دنباله بلوکی پس از نزدیک‌ترین عنصر بلوکی درج می‌شوند.

--gemini-link-end: صف پیوندها را به جای قرار دادن بعد از نزدیک‌ترین عنصر بلوکی، در انتهای سند درج کن.
--gemini-link-inline: تمام پیوندها را درون جریان متن رندر کن. این کار در پیوندهای تو در تو مانند تصاویر داخل پیوندها، پیوندها در نقل‌قول‌های بلوکی و غیره موجب به‌هم‌ریختگی می‌شود. تنها در اسنادی که با دقت بالا تنظیم شده‌اند باید استفاده شود.
--gemini-link-noref: برچسب‌های پیوند را قالب‌بندی نکن. بر گزینه --gemini-link-roman. تقدم دارد.
--gemini-link-roman: هنگام قالب‌بندی برچسب‌های پیوند، به جای حالت پیش‌فرض سیستم ۲۶تایی با حروف کوچک انگلیسی (یعنی “a”, “b”, ..., “aa”, “ab”, ...) , از اعداد رومی با حروف کوچک استفاده کن.
--gemini-metadata: چاپ متاداده به صورت کلید استانداردشده و به دنبال آن دونقطه و سپس مقدار، هر کدام در یک خط (خطوط جدید با فاصله جایگزین می‌شوند). بلوک متاداده با دو خط جدید پایان می‌یابد. اگر متاداده‌ای وجود نداشته باشد، این گزینه هیچ کاری انجام نمی‌دهد.

خروجی -tlatex دارای گزینه‌های زیر است:

--latex-no-numbered: بخش‌ها (و زیربخش‌ها و غیره) را شماره‌گذاری نکن.
--latex-no-skiphtml: HTML جاسازی‌شده را در خروجی درج کن. این کار معمولاً منطقی نیست زیرا HTML توسط خواننده خروجی تفسیر نخواهد شد. به‌طور پیش‌فرض، HTML حذف می‌شود.

خروجی -tfodt دارای گزینه‌های زیر است:

--odt-no-skiphtml: HTML جاسازی‌شده را در خروجی درج کن. این کار معمولاً منطقی نیست زیرا HTML توسط خواننده خروجی تفسیر نخواهد شد. به‌طور پیش‌فرض، HTML حذف می‌شود.
--odt-style=file: یک فایل سبک (style) مربوط به OpenDocument را مشخص می‌کند که باید حداقل شامل عناصر XML ریشه سند یعنی <office:font-face-decls>, <office:scripts>, و <office:styles> باشد. نحو این فایل به هیچ وجه بررسی اعتبار نمی‌شود.

Output media

رسانه خروجی با -t مشخص می‌شود، که مقدار پیش‌فرض آن -thtml است.

-tfodt: خروجی “Flat” OpenDocument. سبک‌های خودکار (سبک‌های وابسته به وضعیت سند) به همراه خروجی تولید می‌شوند. کلاس‌های مشخص‌شده با مشخصه‌های توسعه‌یافته PHP از نظر وجود بررسی نمی‌شوند.
-tgemini: قالب “gemtext” جمینای (Gemini).
-thtml: خروجی HTML5 با کدگذاری UTF-8.
-tlatex: خروجی ساده LaTeX. بسته‌های زیر مورد نیاز هستند: amsmath و amssymb برای فرمول‌های ریاضی، graphicx برای تصاویر، inputenc (utf8) برای ورودی UTF-8، frontend (T1) و textcomp برای گلیف‌های خروجی، lmodern برای قلم Latin modern، xcolor برای خروجی موتور تفاوت‌ها و hyperref برای پیوندها.
-tman: بسته ماکروی man مناسب برای خواندن توسط groff(1), mandoc(1), نسخه Heirloom از troff(1), یا troff(1) سنتی. از معادلات و تصاویر پشتیبانی نمی‌کند. پشتیبانی از جدول توسط tbl(1) ارائه می‌شود. از آنجا که ممکن است مقادیر ورودی با کدگذاری UTF-8 ارسال شوند، ممکن است به استفاده از preconv(1) نیاز باشد.
-tmdoc: بسته ماکروی mdoc مناسب برای خواندن توسط groff(1), mandoc(1), نسخه Heirloom از troff(1), یا (احتمالاً؟) troff(1) سنتی. از معادلات و تصاویر پشتیبانی نمی‌کند. پشتیبانی از جدول توسط tbl(1) ارائه می‌شود. از آنجا که ممکن است مقادیر ورودی با کدگذاری UTF-8 ارسال شوند، ممکن است به استفاده از preconv(1) نیاز باشد.
-tms: بسته ماکروی ms مناسب برای خواندن توسط groff(1) یا troff(1) سنتی. از معادلات پشتیبانی نمی‌کند و پشتیبانی محدودی از تصاویر پست‌اسکریپت کپسوله‌شده (با پسوند PS و EPS) دارد. تصاویر همیشه به‌صورت بلوکی قالب‌بندی می‌شوند. ابعاد تصویر و مشخصه‌های توسعه‌یافته نادیده گرفته می‌شوند، اگرچه در صورتی که تصاویر از پهنای متن جاری بزرگ‌تر باشند، اندازه آن‌ها کوچک می‌شود. پشتیبانی از جدول توسط tbl(1) ارائه می‌شود. از آنجا که ممکن است مقادیر ورودی با کدگذاری UTF-8 ارسال شوند، ممکن است به استفاده از preconv(1) نیاز باشد.
-tterm: خروجی UTF-8 با کدهای گریز ANSI مناسب برای خواندن در ترمینال. از تصاویر و معادلات پشتیبانی نمی‌شود.
-ttree: خروجی اشکال‌زدایی. برای استفاده برنامه‌نویسی مناسب نیست، زیرا ممکن است قالب آن بین نسخه‌ها تغییر کند.

Differences

تفاوت‌های میان سند قدیم و جدید به روش‌های زیر نشان داده می‌شوند:

-tfodt: “Flat” تفاوت‌ها با استفاده از ردیابی سند (document tracking) نمایش داده می‌شوند.
-tgemini: تفاوت‌ها رندر نمی‌شوند.
-tlatex: تفاوت‌ها با رنگ‌آمیزی به آبی (درج) و قرمز (حذف) رندر می‌شوند (این قالب ثابت نیست).
-tman, -tmdoc, -tms: تفاوت‌ها با رنگ‌آمیزی به آبی (درج) و قرمز (حذف) رندر می‌شوند (این قالب ثابت نیست).
-tterm: تفاوت‌ها با تغییر رنگ پس‌زمینه به آبی (درج) و قرمز (حذف) رندر می‌شوند (این قالب ثابت نیست).
-ttree: تفاوت‌ها به‌صورت دستی در خروجی ساختار درختی نمایش داده می‌شوند.

تفاوت‌ها در متاداده محتوا از این قاعده پیروی می‌کنند: جفت‌های کلید-مقدار متاداده حذف‌شده در خروجی پردازش نمی‌شوند، بنابراین تنها متاداده‌های درج‌شده یا نگه‌داشته‌شده پردازش می‌شوند.

Standalone documents

هنگامی که -s مشخص شود، محتوای قالب‌بندی‌شده درون یک قالب سند خودکفا، طبق تعریف نوع خروجی، سریال‌سازی می‌شود.

اگر به‌طور صریح با --template تنظیم نشده باشد، یک قالب پیش‌فرض به شرح زیر تولید می‌شود:

-tfodt: پوشش <office:document> و پیش‌درآمد <office:automatic-styles>, <office:master-styles>, و <office:body>.
-thtml: اعلان doctype مربوط به HTML5 و به دنبال آن پوشش <html> همراه با زبان اختیاری، و سپس <head>. به ترتیب، <head> شامل عناصر <meta> برای مجموعه نویسه (charset) و نمای نمایش (viewport)؛ عناصر اختیاری <meta> از متاداده وابستگی سازمانی (پدیدآور)، نویسنده، حق نشر و تاریخ؛ منابع اختیاری CSS از متاداده؛ منابع اختیاری جاوااسکریپت از متاداده؛ عنصر <title> که احتمالاً خالی است؛ سپس محتوای دلخواه و اختیاری از سرآیند HTML متاداده می‌باشد.
-tlatex: عبارت‌های پیش‌درآمد documentclass و usepackage, محتوای دلخواه و اختیاری از سرآیند LaTeX متاداده، سپس عبارت‌های احاطه‌کننده begin{document}.
-tman, -tmdoc, -tms: ماکروهای پیش‌درآمد.
-tterm: خطوط پیش‌درآمد.
-ttree: متاداده و قالب تجزیه‌شده.

برای مقادیر متاداده استفاده‌شده توسط قالب پیش‌فرض، به Metadata مراجعه کنید.

Metadata

کلیدهای متاداده به ترتیب زیر استانداردسازی و یکتا (حذف موارد تکراری) می‌شوند: -m (که با محتوای سند و -M -بازنویسی -می‌شود), پیش‌درآمد خود سند، و سپس -M (که بر محتوای سند و -m -اولویت -دارد -و -آن‌ها -را -بازنویسی -می‌کند).

پس از یکتا کردن، متاداده در متغیرهای سند و/یا خروجی سند مستقل -s سریال‌سازی می‌شود.

هنگامی که از --template استفاده نشود، کلیدهای متاداده زیر در قالب پیش‌فرض -s استفاده می‌شوند:

affiliation: وابستگی سازمانی نویسنده (سازمان یا مؤسسه). وابستگی‌های سازمانی چندگانه را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد. مورد استفاده در -thtml, -tlatex, و -tms.
author: نویسنده سند. نویسندگان چندگانه را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد. توسط rcsauthor بازنویسی می‌شود. مورد استفاده در -tfodt, -thtml, -tlatex, -tms, و -tterm.
baseheaderlevel: به سطح هر عنوان اضافه می‌شود. منسوخ شده و به جای آن استفاده از shiftheadinglevelby توصیه می‌شود.
copyright: حق نشر سند (بدون واژه “Copyright”), برای مثال، “2017, Kristaps Dzonsons”. مورد استفاده در -tms و -thtml.
css: فایل CSS خروجی در head سند HTML به‌عنوان دستور <link rel="stylesheet" href="..." />. چندین فایل CSS (به ترتیب) را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد و به همان ترتیب داده‌شده در خروجی قرار می‌گیرند. تنها در -thtml استفاده می‌شود.
date: تاریخ سند در قالب ISO-8601 YYYY-MM-DD. توسط rcsdate بازنویسی می‌شود. مورد استفاده در -tfodt, -thtml, -tlatex, -tman, -tmdoc, -tms, و -tterm.
htmlheader: محتوای دلخواه HTML خروجی در head سند HTML بلافاصله قبل از بسته شدن عنصر head. تنها در -thtml و همراه با -s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود.
javascript: فایل جاوااسکریپت خروجی در head سند HTML به‌عنوان دستور <script src="..."></script>. چندین فایل اسکریپت (به ترتیب) را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد و به همان ترتیب داده‌شده در خروجی قرار می‌گیرند. تنها در -thtml استفاده می‌شود.
lang: زبان سند در قالب RFC 5646. تنها در -thtml استفاده می‌شود.
latexheader: محتوای دلخواه LaTeX خروجی در پیش‌درآمد سند بلافاصله قبل از begin{document}. تنها در -tlatex و همراه با -s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود.
manheader: محتوای دلخواه roff خروجی بلافاصله قبل از ماکروی .TH. تنها در -tman و همراه با -s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود.
msheader: محتوای دلخواه roff خروجی بلافاصله قبل از ماکروی .TL. تنها در -tms و همراه با -s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود.
rcsauthor: مشابه author, اما در قالب نویسنده RCS. بر author اولویت دارد و آن را بازنویسی می‌کند.
rcsdate: مشابه date, اما در قالب تاریخ RCS. بر date اولویت دارد و آن را بازنویسی می‌کند.
section: بخش صفحه راهنما (man page)، با مقدار پیش‌فرض “7”. تنها در -tman و -tmdoc استفاده می‌شود.
shiftheadinglevelby: انتقال سطح تمام عنوان‌ها به اندازه مقدار داده‌شده. برای مثال، مقدار ۱ باعث می‌شود عنوان‌هایی که در اصل در سطح ۱ بودند (“<h1>”) به سطح ۲ تبدیل شوند (“<h2>”), در حالی که مقدار -1 سطح ۲ را به ۱ منتقل می‌کند. سطوح به کمتر از ۱ منتقل نخواهند شد. بر baseheaderlevel اولویت دارد. اگر تنظیم نشده باشد یا یک عدد معتبر نباشد، پیش‌فرض آن صفر است. مورد استفاده در -tfodt, -thtml, -tlatex, -tman, -tmdoc, و -tms.
source: منبع صفحه راهنما (سازمان ارائه‌دهنده راهنما). تنها در -tman و -tmdoc استفاده می‌شود.
volume: جلد صفحه راهنما (توصیف‌کننده بخش صفحه راهنما). تنها در -tman و -tmdoc استفاده می‌شود.
title: عنوان سند. مورد استفاده در -tfodt, -thtml, -tlatex, -tman, -tmdoc, -tms, و -tterm.

مقادیر پیش‌فرض، مانند “7” برای section, به‌عنوان مقادیر متاداده تنظیم نمی‌شوند و در صورتی که کلید متاداده به‌عنوان متغیر استفاده شود، ظاهر نخواهند شد.

Templates

برخی رسانه‌های خروجی یک قالب (--template) را برای سفارشی‌سازی خروجی مستقل (-s) می‌پذیرند. محتوای ورودی تجزیه‌شده از طریق دستورات کنترلی در قالب‌ها قرار می‌گیرد؛ این دستورات از شرط‌ها، حلقه‌ها و توالی‌های تبدیل متغیر پشتیبانی می‌کنند.

دستورات کنترلی با $statement$ یا ${statement} محدود می‌شوند. فاصله‌های خالی دلخواه می‌توانند دستور غیرحساس به بزرگی و کوچکی حروف را میان جداکننده‌های منطبق احاطه کنند. دستورات بدون جداکننده پایانی به عنوان متن ساده در نظر گرفته می‌شوند.

دستورات زیر در دسترس هستند:

$$, ${}: یک نویسه واقعی $ را در خروجی چاپ می‌کند. این عبارت می‌تواند شامل فاصله‌های خالی دلخواه باشد.
$ifdef(expression)$: دستور شرطی. نباید هیچ فاصله خالی میان ifdef و پرانتز باز وجود داشته باشد. بلوکی را آغاز می‌کند که با یک else, endif یا پایان فایل خاتمه می‌یابد. محتوای آن تنها در صورتی در خروجی قرار می‌گیرد که expression به یک رشته غیرخالی ارزیابی شود.
$else$: بلوکی را آغاز می‌کند که با یک endif یا پایان فایل خاتمه می‌یابد. محتوای آن تنها در صورتی در خروجی قرار می‌گیرد که شرط ifdef قبلی به یک رشته خالی ارزیابی شود. یک else بدون ifdef قبلی در خروجی درج نمی‌شود.
$endif$: بلوکی را که با ifdef یا else آغاز شده می‌بندد. اگر قبل از آن یکی از این دستورات نیامده باشد، بدون هشدار نادیده گرفته می‌شود.
$for(expression)$: دستور حلقه. نباید هیچ فاصله خالی میان for و پرانتز باز وجود داشته باشد. بلوکی را آغاز می‌کند که با یک endfor یا پایان فایل خاتمه می‌یابد. محتوای بلوک به ازای هر مورد از فهرست ارزیابی‌شده از expression به‌طور مکرر در خروجی چاپ می‌شود. کلیدواژه ارجاعی this می‌تواند برای دسترسی به عبارت حلقه جاری در داخل بلوک استفاده شود.
$expression$: با نتیجه ارزیابی عبارت قالب جایگزین می‌شود.

اگر یک دستور کنترلی با دو خط تیره متوالی پیش از جداکننده پایانی تمام شود، ورودی تا و شامل خط جدید بعدی یا تا پایان فایل خوانده و مصرف می‌شود. این ویژگی به رسانه‌های خروجی حساس به خط اجازه می‌دهد از دستورات کنترلی بدون خطوط خالی اضافی استفاده کنند.

عبارت‌ها از

initial[([arg]*)]?[.transform[([arg]*)]?]*

,

یا یک مقدار اولیه که آرگومان‌های اختیاری را می‌پذیرد، به‌همراه یک سری تبدیل‌های اختیاری که آرگومان‌های اختیاری را می‌پذیرند، تشکیل شده‌اند. اگر فهرست آرگومان‌ها خالی باشد یا ارائه نشود، به یک فهرست خالی ارزیابی می‌شود.

مقدار initial یکی از موارد زیر است:

and(expression[,expression]*): یک فهرست غیرخالی حاوی مقدار true در صورتی که تمام عبارت‌ها به فهرست‌های غیرخالی ارزیابی شوند؛ در غیر این صورت یک فهرست خالی. یک عبارت خالی به یک فهرست خالی ارزیابی می‌شود.
"literal string": به یک فهرست تک‌عضوی حاوی این رشته ارزیابی می‌شود. یک رشته خالی به یک فهرست خالی ارزیابی می‌شود. نویسه نقل‌قول دوگانه را می‌توان اسکیپ کرد، مانند "foo\"bar".
body: بدنه سند ورودی تجزیه‌شده.
کلید متادیتای متعارف (canonicalised metadata key): مقدار کلید متادیتای داده‌شده در صورت پیدا شدن؛ در غیر این صورت یک فهرست خالی.
body: بدنه سند ورودی تجزیه‌شده.
meta(key): مقدار متادیتا را برای کلید متادیتای متعارف key تولید می‌کند. این امکان را برای کلیدهایی فراهم می‌کند که خود کلیدواژه هستند، مانند body یا endif.
not(expression): یک فهرست غیرخالی حاوی مقدار true در صورتی که عبارت به یک فهرست خالی ارزیابی شود؛ در غیر این صورت یک فهرست خالی.
or(expression[,expression]*): یک فهرست غیرخالی حاوی مقدار true در صورتی که حداقل یک عبارت به یک فهرست غیرخالی ارزیابی شود؛ در غیر این صورت یک فهرست خالی. یک عبارت خالی به یک فهرست خالی ارزیابی می‌شود.
this: مقدار یک زمینه حلقه جاری یا یک فهرست خالی.

اگر یک کلید متادیتا در ورودی مشخص نشده باشد، یا اگر کلیدواژه ارجاعی this توسط یک زمینه حلقه مقداردهی اولیه نشده باشد، مقدار اولیه به یک فهرست خالی ارزیابی می‌شود. در غیر این صورت، این مقدار یک فهرست تک‌عضوی است.

اگر تبدیل‌ها نامعتبر باشند، به یک فهرست خالی تبدیل خواهند شد.

تبدیل‌های زیر در دسترس هستند:

escapegemini, escapegeminiline: گریز دادن (escape) موارد فهرست برای جِمینای (-tgemini), خواه برای چندین خط یا به‌صورت فشرده در یک خط واحد.
escapehtml, escapehtmlattr, escapehtmlurl: گریز دادن موارد فهرست برای محتوای بدنه، مشخصه‌ها و مشخصه‌های نشانی وب در HTML (-thtml) به ترتیب.
escapelatex: گریز دادن موارد فهرست برای محتوای بدنه LaTeX (-tlatex).
escaperoff, escaperoffline: گریز دادن موارد فهرست برای roff (-tms, -tman, -tmdoc), خواه برای چندین خط یا به‌صورت فشرده در یک خط واحد. escaperoff همچنین جداکننده‌های ابتدایی roff و جداکننده‌های پس از خطوط جدید را گریز می‌دهد.
join: اتصال یک فهرست به یک فهرست تک‌عضوی با استفاده از دو فاصله به عنوان جداکننده اتصال.
lowercase: تبدیل تمام موارد فهرست به حروف کوچک.
split: تقسیم موارد فهرست بر اساس توالی دو یا چند نشانه فاصله خالی (فاصله، خط جدید، تب). این تبدیل معمولاً روی یک مقدار تک‌عضوی فراخوانی می‌شود، اما می‌تواند به‌طور مکرر روی فهرستی که از قبل تقسیم شده است نیز اجرا شود. پیش از اولین تقسیم، trim را فراخوانی می‌کند. فهرست حاصل هیچ عضوی که صرفاً فاصله خالی باشد نخواهد داشت.
trim: حذف فاصله‌های خالی از ابتدا و انتهای تمام موارد فهرست. اگر موردی هیچ نویسه غیر فاصله خالی نداشته باشد، حذف می‌شود.
uppercase: تبدیل تمام موارد فهرست به حروف بزرگ.

محیط (ENVIRONMENT)

NO_COLOR: عدم چاپ رنگ‌ها هنگام کار در حالت -tterm. مترادف با NO_COLOUR. مشابه با --term-nocolour.

فایل‌ها (FILES)

share/html/default.html: قالب پیش‌فرضی که در صورت مشخص نشدن --template برای -thtml استفاده می‌شود.
share/latex/default.latex: قالب پیش‌فرضی که در صورت مشخص نشدن --template برای -tlatex استفاده می‌شود.
share/man/default.man: قالب پیش‌فرضی که در صورت مشخص نشدن --template برای -tman استفاده می‌شود.
share/man/default.ms: قالب پیش‌فرضی که در صورت مشخص نشدن --template برای -tms استفاده می‌شود.
share/odt/styles.xml: شیوه‌های پیش‌فرضی که هنگام تولید اسناد مستقل -tfodt استفاده می‌شوند. قالب برای شیوه‌های --odt-style.

وضعیت خروج (EXIT STATUS)

The lowdown-diff utility exits 0 on success, and >0 if an error occurs.

مثال‌ها (EXAMPLES)

برای مشاهده تفاوت‌های مارک‌داون در یک ترمینال سازگار با ANSI و UTF-8:

lowdown-diff -tterm old.md new.md |
  less -R

برای تولید یک سند مستقل HTML5:

lowdown-diff -s old.md new.md >
  foo.html

برای استفاده از groff(1) جهت قالب‌بندی به عنوان یک فایل PS:

lowdown-diff -stms old.md new.md | \
  groff -itk -mspdf > foo.ps

یا با استفاده از LaTeX:

lowdown-diff -stlatex old.md new.md > foo.latex
pslatex foo.latex

تولید PDF از منطق مشابهی پیروی می‌کند:

lowdown-diff -stms old.md new.md | \
  pdfroff -itk -mspdf > foo.pdf
lowdown-diff -stlatex old.md new.md > foo.latex
pdflatex foo.latex

پشتیبانی از UTF-8 برای خروجی PDF یا PS در groff(1) نیازمند قلم‌های مناسب است، مانند قلم Unicode Times. این قلم و سایر قلم‌های یونیکد همیشه به‌طور پیش‌فرض نصب نیستند. این قلم‌ها برای خروجی PDF را می‌توان در مجموعه devpdf از پوشه قلم‌های groff(1) یافت که با پیشوند ‘U’ مشخص شده‌اند.

lowdown-diff -stms old.md new.md | \
  pdfroff -itk -mspdf -FU-T > foo.pdf

همچنین ببینید (SEE ALSO)

lowdown(1), lowdown(3), lowdown(5)

نویسندگان (AUTHORS)

lowdown-diff توسط Kristaps Dzonsons, kristaps@bsd.lv نوشته شده است.

هشدارها (CAVEATS)

هنگام مشاهده تفاوت‌های -tman یا -tmdoc با mandoc(1), رنگ‌های نشانگر رندر نمی‌شوند. همچنین خروجی -tgemini در حال حاضر روشی برای کدگذاری تفاوت‌ها ندارد.