.\" Copyright (c) Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate$ .Dt LOWDOWN-DIFF 1 .Os .Sh "نام (NAME)" .Nm lowdown-diff .Nd محاسبه و نمایش تفاوت‌های دو سند مارک‌داون .Sh "خلاصه دستور (SYNOPSIS)" .Nm lowdown-diff .Op input_options .Op output_options .Op Fl s .Op Fl M Ar metadata .Op Fl m Ar metadata .Op Fl o Ar file .Op Fl t Ar mode .Ar oldfile .Op Ar newfile .Sh "توضیحات (DESCRIPTION)" تفاوت‌های میان اسناد .Xr lowdown 5 را به صورت خروجی قالب‌بندی‌شده نمایش می‌دهد. نتایج در خروجی استاندارد نوشته می‌شوند. .Pp آرگومان‌های کوتاه به شرح زیر هستند: .Bl -tag -width Ds .It Fl s تولید یک سند مستقل (مثلاً یک سند معتبر HTML شامل نوع سند، head و غیره) پیرامون محتوای قالب‌بندی‌شده. برای جزئیات به بخش .Sx Standalone documents مراجعه کنید. .It Fl M Ar metadata ارائه یک جفت کلید-مقدار متاداده منفرد. این مقدار می‌تواند با نحو معمولی یا به صورت جفت‌های جدا شده با علامت مساوی باشد، بسته به اینکه کدام نویسه (دونقطه یا علامت مساوی) زودتر ظاهر شود. اگر هیچ‌کدام ارائه نشود، برنامه با خطا خارج می‌شود. این گزینه بر .Fl m و آنچه از سند تجزیه شده برتری دارد (آن‌ها را بازنویسی می‌کند). به بخش .Sx Metadata . مراجعه کنید. .It Fl m Ar metadata مشابه .Fl M , اما توسط آنچه از سند تجزیه شده، و سپس توسط .Fl M بازنویسی می‌شود. .It Fl o Ar file ارسال خروجی به .Ar file مگر اینکه .Dq - باشد، که در این حالت خروجی پیش‌فرض استاندارد استفاده می‌شود. .It Fl t Ar mode , Fl T Ar mode حالت خروجی. می‌تواند شامل موارد زیر باشد: .Ar html برای خروجی HTML5، .Ar latex برای LaTeX، .Ar gemini برای قالب .Dq gemtext پروژه Gemini، .Ar ms برای خروجی roff با استفاده از بسته .Fl mspdf و نیازمند پشتیبانی از جدول، .Ar term برای خروجی ترمینال سازگار با ANSI و UTF-8، .Ar man برای خروجی roff با استفاده از بسته .Fl man , .Ar mdoc برای خروجی roff با استفاده از بسته .Fl mdoc , .Ar tree , برای نمایش درخت تجزیه سند ورودی، و .Ar null برای تجزیه سند بدون رندر کردن آن. به بخش .Sx Output media . مراجعه کنید. شکل .Fl T Ar mode برای سازگاری با گذشته حفظ شده است. .It Ar oldfile , newfile اسناد مارک‌داون مورد استفاده برای مقایسه. اگر .Ar newfile مشخص نشود یا .Dq - باشد، از ورودی استاندارد خوانده می‌شود. .El .Pp موارد زیر گزینه‌های طولانی برای تجزیه ورودی هستند. این گزینه‌ها بر درخت تجزیه ارائه‌شده به تمام خروجی‌ها تأثیر می‌گذارند. .Bl -tag -width Ds .It Fl -parse-hilite فعال‌سازی پشتیبانی از محدوده‌های هایلایت (برجسته‌سازی). این گزینه به‌طور پیش‌فرض غیرفعال است زیرا ممکن است به اشتباه به‌عنوان سرتیتر بخش‌ها تفسیر شود. .It Fl -parse-math شناسایی معادلات ریاضی. .It Fl -parse-maxdepth=depth حداکثر عمق عناصر تو در تو. پیش‌فرض آن 128 است که احتمالاً برای هر سند واقعی بیش از اندازه کافی است. اگر این حد نصاب فرارسد، سیستم طوری خارج می‌شود که گویی حافظه تمام شده است. تنظیم آن روی صفر به معنی عدم وجود محدودیت است. .It Fl -parse-no-autolink پیوندهای .Li http , .Li https , .Li ftp , .Li mailto , و پیوندهای نسبی یا قطعه‌های پیوند را تجزیه نکن. .It Fl -parse-no-cmark با محدودیت‌های CommonMark تجزیه نکن. این گزینه همچنین استفاده از اولین مقدار لیست مرتب‌شده به‌جای شروع همه لیست‌ها از یک را غیرفعال می‌کند. .It Fl -parse-no-codeindent محتوای دندانه‌دار را به عنوان بلوک‌های کد تجزیه نکن. .It Fl -parse-no-callouts کادرهای اطلاعاتی (callouts) مربوط به GFM/MDN .Pq Dq admonitions را تجزیه نکن. .It Fl -parse-no-deflists لیست‌های تعریفی PHP extra را تجزیه نکن. .It Fl -parse-no-ext-attrs ویژگی‌های توسعه‌یافته PHP extra را تجزیه نکن. .It Fl -parse-no-fenced بلوک‌های کد محصور (fenced) مخصوص زبان در GFM را تجزیه نکن. .It Fl -parse-no-footnotes پاورقی‌های MMD را تجزیه نکن. .It Fl -parse-no-img-ext منسوخ شده است. به .Fl -parse-no-ext-attrs . مراجعه کنید. .It Fl -parse-no-intraemph تأکید درون واژه‌ها و پیوندها را تجزیه نکن. .It Fl -parse-no-mantitle عنوان، بخش، منبع و جلد صفحه راهنما را از فراداده‌های عنوان Pandoc تجزیه نکن. عنوان صفحات راهنما با یک عنوان و سپس یک پرانتز باز، رقم به همراه نویسه‌های اختیاری و سپس پرانتز بسته مشخص می‌شود. .It Fl -parse-no-metadata متاداده‌ها را تجزیه نکن. این گزینه بر متاداده‌های ارائه‌شده در .Fl m یا .Fl M تأثیری ندارد. .It Fl -parse-no-strike خط‌خوردگی‌ها (strikethroughs) را تجزیه نکن. .It Fl -parse-no-super بالانویس‌ها یا زیرنویس‌ها را به هیچ وجه تجزیه نکن. .It Fl -parse-no-tables جدول‌های GFM را تجزیه نکن. .It Fl -parse-no-tasklists لیست‌های وظایف GFM را تجزیه نکن. .It Fl -parse-super-short اگر تجزیه بالانویس فعال باشد، از نحو سنتی غیر GFM به صورت .Dq short استفاده کن. .El .Pp گزینه‌های طولانی متعددی برای خروجی وجود دارد. موارد زیر میان تمام رسانه‌های خروجی مشترک هستند: .Bl -tag -width Ds .It Fl -out-standalone نام مستعار برای .Fl s . .It Fl -out-no-smarty از فیلتر تایپوگرافی هوشمند استفاده نکن. به‌طور پیش‌فرض، برخی توالی‌های نویسه‌ای به نشانه‌های گرافیکی (گلیف‌های) مخصوص خروجی تبدیل می‌شوند. .It Fl -template Ar template هنگام تولید خروجی مستقل .Fl s , از یک فایل الگو استفاده کن. به بخش .Sx Templates . مراجعه کنید. در حال حاضر تنها برای .Fl t Ns Ar gemini , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar ms , و .Fl t Ns Ar tree . .El .Pp در ادامه گزینه‌های طولانی اختصاصی هر خروجی آمده است. برای HTML با .Fl t Ns Ar html , این گزینه‌ها به شرح زیر هستند: .Bl -tag -width Ds .It Fl -html-callout-mdn , -html-callout-gfm خروجی دادن نحو کادرهای اطلاعاتی (callout) مربوط به MDN یا GFM یا هر دو. .It Fl -html-hardwrap شکستن سخت خطوط محتوای پاراگراف با قرار دادن شکستگی خط (line break) در جاهای لازم. .It Fl -html-no-escapehtml اگر .Fl -html-no-skiphtml مشخص شده باشد، باعث می‌شود HTML جاسازی‌شده اسکیپ نشود و در عوض عیناً در خروجی درج گردد. اگر .Fl -html-no-skiphtml مشخص نشده باشد، این گزینه هیچ تأثیری ندارد. .It Fl -html-no-head-ids ویژگی‌های .Li id را برای سرتیترها در خروجی درج نکن. .It Fl -html-no-num-ent موجودیت‌های HTML (در صورت امکان) به موجودیت‌های عددی نرمال‌سازی نشوند و در عوض از همان موجودیت‌های ارائه‌شده در ورودی استفاده شود. .It Fl -html-no-owasp از توصیه‌های OWASP برای اسکیپ کردن متن پیروی نکن، و تنها حداقل اسکیپ‌سازی را انجام بده تا مطمئن شوی محتوای معمولی به عنوان HTML تفسیر نمی‌شود. .It Fl -html-no-skiphtml HTML جاسازی‌شده را در خروجی درج کن. به‌طور پیش‌فرض، HTML جاسازی‌شده به هیچ وجه در خروجی درج نمی‌شود. به .Fl -html-no-escapehtml . مراجعه کنید. .It Fl -html-titleblock در صورت تجزیه شدن، اطلاعات عنوان (عنوان، نویسنده، تاریخ) را در قالب یک عنصر سرتیتر که در ابتدای سند ظاهر می‌شود قالب‌بندی کن. .El .Pp برای قالب‌های roff یعنی .Fl t Ns Ar man , .Fl t Ns Ar mdoc , و .Fl t Ns Ar ms .Pq مگر در مواردی که ذکر شده , گزینه‌های زیر اعمال می‌شوند: .Bl -tag -width Ds .It Fl -roff-code-font Ns = Ns Ar fonts جایگزین کردن فونت‌های پیش‌فرض با عرض ثابت با یک چندتایی (tuple) از گونه‌های عادی، بولد، ایتالیک و بولد-ایتالیک به همین ترتیب. به عنوان مثال، .Li B,B,BI,BI به جای عرض ثابت، از بولد .Pq Dq B استفاده می‌کند. عدم تعیین فونت یا تعیین نام فونت با طول صفر، از پیش‌فرض استفاده خواهد کرد. نام‌های مستعار .Li none , .Li bold , و .Li code به ترتیب هیچ فونت خاصی، فونت بولد و فونت پیش‌فرض عرض ثابت را تنظیم می‌کنند. .It Fl -roff-endnotes به تعویق انداختن چاپ پاورقی‌ها تا انتهای سند. تنها برای .Fl t Ns Ar ms کاربرد دارد، چرا که .Fl t Ns Ar man و .Fl t Ns Ar mdoc تنها از یادداشت‌های پایانی (endnotes) پشتیبانی می‌کنند. .It Fl -roff-manpage قالب‌بندی خروجی به صورت یک صفحه راهنما (manpage). این گزینه پاراگراف‌های ذیل بخش‌های .Li NAME , .Li SYNOPSIS , و .Li SEE ALSO را در قالب استاندارد مورد استفاده صفحات راهنما بازآرایی می‌کند. نحوه قالب‌بندی سند به متاداده بخش بستگی دارد: 1، 6 و 8 برای سبک برنامه‌ای؛ 2، 3 و 9 برای سبک تابعی. سبک برنامه‌ای فلگ‌ها و آرگومان‌ها را بازآرایی می‌کند، در حالی که سبک تابعی نام توابع، متغیرها و آرگومان‌ها را بازآرایی می‌کند. هرگونه محتوا در محدوده‌های فونت (مانند تأکید یا تأکید دوگانه) در سایر بخش‌ها، فونت آن‌ها حذف شده و به همان شیوه بازآرایی می‌شوند. تنها برای .Fl t Ns Ar man و .Fl t Ns Ar mdoc . اعمال می‌شود. .It Fl -roff-no-numbered سرتیترهای شماره‌دار را در خروجی درج نکن .Po .Li .NH NN .Pc . تنها برای .Fl t Ns Ar ms . اعمال می‌شود. .It Fl -roff-no-skiphtml HTML جاسازی‌شده را در خروجی درج کن. این کار معمولاً منطقی نیست زیرا HTML توسط خواننده خروجی تفسیر نخواهد شد. به‌طور پیش‌فرض، HTML حذف می‌شود. .It Fl -roff-no-links در صورت امکان، آدرس‌های اینترنتی (URL) را برای تصاویر و پیوندها نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه‌های .Fl -roff-short-links و .Fl -roff-no-rellinks . تقدم دارد. .It Fl -roff-no-rellinks در صورت امکان، آدرس‌های اینترنتی را برای پیوندهای نسبی نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه .Fl -roff-short-links . تقدم دارد. .It Fl -roff-short-links در صورت امکان، نشانی‌های وب برای تصاویر، پیوندها و پیوندهای خودکار را فقط به نام دامنه و مسیر نهایی کوتاه کن. .It Fl -roff-traditional خروجی سنتی .Fl ms .Pq نه Fl mspdf و .Fl man بدون افزونه‌ها تولید کن. به‌ویژه، از ماکروهای پیوند .Po .Li .pdfhref , .Li .UR , .Li .MT .Pc , جدول‌های چندصفحه‌ای .Po .Li .TS H , .Li .TH .Pc , نحو توالی یونیکد .Po .Li \e[uNNNN] .Pc , ماکروهای بلوک مثال .Po .Li .EX .Pc , سرتیترهای مدرن بخش‌ها .Po .Li .NH NN , .Li .SH NN , .Li .pdfhref O NN .Pc , یا پیوندهای درون‌سندی .Po .Li .pdfhref L .Pc استفاده نکن. خروجی با ابزار سنتی .Xr troff 1 سازگار خواهد بود. .El .Pp پیشوند آرگومان .Fl -nroff , مانند .Fl -nroff-traditional , به نفع .Fl -roff منسوخ شده است. .Pp خروجی .Fl t Ns Ar term دارای گزینه‌های زیر است: .Bl -tag -width Ds .It Fl -term-all-metadata اگر .Fl s مشخص شده باشد، به جای فقط عنوان، نویسنده و تاریخ، تمام متاداده‌ها را خروجی می‌دهد. .It Fl -term-columns=columns تعداد ستون‌ها در ترمینال. هنگام اجرا در یک لوله (pipe) مفید است. پیش‌فرض آن مقداری است که ترمینال گزارش می‌کند، یا 72 اگر در ترمینال نباشد. .It Fl -term-hmargin=margin تعداد نویسه‌های حاشیه چپ. پیش‌فرض صفر است. همچنین می‌تواند .Ar auto باشد تا حاشیه چپ را برابر با نصف باقیمانده .Fl -term-columns پس از کسر .Fl -term-width قرار دهد. .It Fl -term-hpadding=padding تعداد نویسه‌های فاصله‌گذاری (padding) چپ. پیش‌فرض چهار است. فاصله‌گذاری از مقدار .Fl -term-width کسر می‌شود. .It Fl -term-no-ansi سبک‌های ANSI را اصلاً نمایش نده. این گزینه متضمن .Fl -term-no-colour . است. .It Fl -term-no-colour رنگ‌های ANSI را نمایش نده. متن همچنان با زیرخط، بولد و ایتالیک آراسته می‌شود، اما هیچ کد رنگی ارسال نخواهد شد. .It Fl -term-no-links در صورت امکان، آدرس‌های اینترنتی را برای تصاویر و پیوندها نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه‌های .Fl -term-short-links و .Fl -term-no-rellinks . تقدم دارد. .It Fl -term-no-rellinks در صورت امکان، آدرس‌های اینترنتی را برای پیوندهای نسبی نمایش نده. محتوای پیوند همواره نمایش داده می‌شود. بر گزینه .Fl -term-short-links . تقدم دارد. .It Fl -term-short-links در صورت امکان، نشانی‌های وب برای تصاویر، پیوندها و پیوندهای خودکار را فقط به نام دامنه و مسیر نهایی کوتاه کن. .It Fl -term-vmargin=margin تعداد خطوط خالی حاشیه بالا و پایین. پیش‌فرض صفر است. .It Fl -term-width=width حد نرم برای تعداد نویسه‌ها در هر خط شامل .Pq Fl -term-hpadding . متن‌های دقیق (literal) ممکن است از این مقدار فراتر بروند. اگر صفر باشد یا تنظیم نشود، پیش‌فرض آن .Fl -term-columns یا حداکثر 80 است. بر روی .Fl -term-columns . برش می‌خورد. .El .Pp خروجی .Fl t Ns Ar gemini دارای چندین فلگ است که محل قرارگیری پیوندها را کنترل می‌کنند. به‌طور پیش‌فرض، پیوندها (تصاویر، پیوندهای خودکار و پیوندها) در صورت مشخص شدن درون‌خطی، در صف قرار می‌گیرند و سپس به صورت یک دنباله بلوکی پس از نزدیک‌ترین عنصر بلوکی درج می‌شوند. .Bl -tag -width Ds .It Fl -gemini-link-end صف پیوندها را به جای قرار دادن بعد از نزدیک‌ترین عنصر بلوکی، در انتهای سند درج کن. .It Fl -gemini-link-inline تمام پیوندها را درون جریان متن رندر کن. این کار در پیوندهای تو در تو مانند تصاویر داخل پیوندها، پیوندها در نقل‌قول‌های بلوکی و غیره موجب به‌هم‌ریختگی می‌شود. تنها در اسنادی که با دقت بالا تنظیم شده‌اند باید استفاده شود. .It Fl -gemini-link-noref برچسب‌های پیوند را قالب‌بندی نکن. بر گزینه .Fl -gemini-link-roman . تقدم دارد. .It Fl -gemini-link-roman هنگام قالب‌بندی برچسب‌های پیوند، به جای حالت پیش‌فرض سیستم ۲۶تایی با حروف کوچک انگلیسی (یعنی .Dq a , .Dq b , \&..., .Dq aa , .Dq ab , \&...) , از اعداد رومی با حروف کوچک استفاده کن. .It Fl -gemini-metadata چاپ متاداده به صورت کلید استانداردشده و به دنبال آن دونقطه و سپس مقدار، هر کدام در یک خط (خطوط جدید با فاصله جایگزین می‌شوند). بلوک متاداده با دو خط جدید پایان می‌یابد. اگر متاداده‌ای وجود نداشته باشد، این گزینه هیچ کاری انجام نمی‌دهد. .El .Pp خروجی .Fl t Ns Ar latex دارای گزینه‌های زیر است: .Bl -tag -width Ds .It Fl -latex-no-numbered بخش‌ها (و زیربخش‌ها و غیره) را شماره‌گذاری نکن. .It Fl -latex-no-skiphtml HTML جاسازی‌شده را در خروجی درج کن. این کار معمولاً منطقی نیست زیرا HTML توسط خواننده خروجی تفسیر نخواهد شد. به‌طور پیش‌فرض، HTML حذف می‌شود. .El .Pp خروجی .Fl t Ns Ar fodt دارای گزینه‌های زیر است: .Bl -tag -width Ds .It Fl -odt-no-skiphtml HTML جاسازی‌شده را در خروجی درج کن. این کار معمولاً منطقی نیست زیرا HTML توسط خواننده خروجی تفسیر نخواهد شد. به‌طور پیش‌فرض، HTML حذف می‌شود. .It Fl -odt-style Ns = Ns Ar file یک فایل سبک (style) مربوط به OpenDocument را مشخص می‌کند که باید حداقل شامل عناصر XML ریشه سند یعنی .Li , .Li , و .Li باشد. نحو این فایل به هیچ وجه بررسی اعتبار نمی‌شود. .El .Ss Output media رسانه خروجی با .Fl t مشخص می‌شود، که مقدار پیش‌فرض آن .Fl t Ns Ar html است. .Bl -tag -width Ds .It Fl t Ns Ar fodt خروجی .Dq Flat OpenDocument. سبک‌های خودکار (سبک‌های وابسته به وضعیت سند) به همراه خروجی تولید می‌شوند. کلاس‌های مشخص‌شده با مشخصه‌های توسعه‌یافته PHP از نظر وجود بررسی نمی‌شوند. .It Fl t Ns Ar gemini قالب .Dq gemtext جمینای (Gemini). .It Fl t Ns Ar html خروجی HTML5 با کدگذاری UTF-8. .It Fl t Ns Ar latex خروجی ساده LaTeX. بسته‌های زیر مورد نیاز هستند: .Li amsmath و .Li amssymb برای فرمول‌های ریاضی، .Li graphicx برای تصاویر، .Li inputenc Pq utf8 برای ورودی UTF-8، .Li frontend Pq T1 و .Li textcomp برای گلیف‌های خروجی، .Li lmodern برای قلم Latin modern، .Li xcolor برای خروجی موتور تفاوت‌ها و .Li hyperref برای پیوندها. .It Fl t Ns Ar man بسته ماکروی .Ar man مناسب برای خواندن توسط .Xr groff 1 , .Xr mandoc 1 , نسخه Heirloom از .Xr troff 1 , یا .Xr troff 1 سنتی. از معادلات و تصاویر پشتیبانی نمی‌کند. پشتیبانی از جدول توسط .Xr tbl 1 ارائه می‌شود. از آنجا که ممکن است مقادیر ورودی با کدگذاری UTF-8 ارسال شوند، ممکن است به استفاده از .Xr preconv 1 نیاز باشد. .It Fl t Ns Ar mdoc بسته ماکروی .Ar mdoc مناسب برای خواندن توسط .Xr groff 1 , .Xr mandoc 1 , نسخه Heirloom از .Xr troff 1 , یا (احتمالاً؟) .Xr troff 1 سنتی. از معادلات و تصاویر پشتیبانی نمی‌کند. پشتیبانی از جدول توسط .Xr tbl 1 ارائه می‌شود. از آنجا که ممکن است مقادیر ورودی با کدگذاری UTF-8 ارسال شوند، ممکن است به استفاده از .Xr preconv 1 نیاز باشد. .It Fl t Ns Ar ms بسته ماکروی .Ar ms مناسب برای خواندن توسط .Xr groff 1 یا .Xr troff 1 سنتی. از معادلات پشتیبانی نمی‌کند و پشتیبانی محدودی از تصاویر پست‌اسکریپت کپسوله‌شده (با پسوند PS و EPS) دارد. تصاویر همیشه به‌صورت بلوکی قالب‌بندی می‌شوند. ابعاد تصویر و مشخصه‌های توسعه‌یافته نادیده گرفته می‌شوند، اگرچه در صورتی که تصاویر از پهنای متن جاری بزرگ‌تر باشند، اندازه آن‌ها کوچک می‌شود. پشتیبانی از جدول توسط .Xr tbl 1 ارائه می‌شود. از آنجا که ممکن است مقادیر ورودی با کدگذاری UTF-8 ارسال شوند، ممکن است به استفاده از .Xr preconv 1 نیاز باشد. .It Fl t Ns Ar term خروجی UTF-8 با کدهای گریز ANSI مناسب برای خواندن در ترمینال. از تصاویر و معادلات پشتیبانی نمی‌شود. .It Fl t Ns Ar tree خروجی اشکال‌زدایی. برای استفاده برنامه‌نویسی مناسب نیست، زیرا ممکن است قالب آن بین نسخه‌ها تغییر کند. .El .Ss Differences تفاوت‌های میان سند قدیم و جدید به روش‌های زیر نشان داده می‌شوند: .Bl -tag -width Ds .It Fl t Ns Ar fodt .Dq Flat تفاوت‌ها با استفاده از ردیابی سند (document tracking) نمایش داده می‌شوند. .It Fl t Ns Ar gemini تفاوت‌ها رندر نمی‌شوند. .It Fl t Ns Ar latex تفاوت‌ها با رنگ‌آمیزی به آبی (درج) و قرمز (حذف) رندر می‌شوند (این قالب ثابت نیست). .It Fl t Ns Ar man , Fl t Ns Ar mdoc , Fl t Ns Ar ms تفاوت‌ها با رنگ‌آمیزی به آبی (درج) و قرمز (حذف) رندر می‌شوند (این قالب ثابت نیست). .It Fl t Ns Ar term تفاوت‌ها با تغییر رنگ پس‌زمینه به آبی (درج) و قرمز (حذف) رندر می‌شوند (این قالب ثابت نیست). .It Fl t Ns Ar tree تفاوت‌ها به‌صورت دستی در خروجی ساختار درختی نمایش داده می‌شوند. .El .Pp تفاوت‌ها در متاداده محتوا از این قاعده پیروی می‌کنند: جفت‌های کلید-مقدار متاداده حذف‌شده در خروجی پردازش نمی‌شوند، بنابراین تنها متاداده‌های درج‌شده یا نگه‌داشته‌شده پردازش می‌شوند. .Ss Standalone documents هنگامی که .Fl s مشخص شود، محتوای قالب‌بندی‌شده درون یک قالب سند خودکفا، طبق تعریف نوع خروجی، سریال‌سازی می‌شود. .Pp اگر به‌طور صریح با .Fl -template تنظیم نشده باشد، یک قالب پیش‌فرض به شرح زیر تولید می‌شود: .Bl -tag -width Ds .It Fl t Ns Ar fodt پوشش .Li و پیش‌درآمد .Li , .Li , و .Li . .It Fl t Ns Ar html اعلان doctype مربوط به HTML5 و به دنبال آن پوشش .Li همراه با زبان اختیاری، و سپس .Li . به ترتیب، .Li شامل عناصر .Li برای مجموعه نویسه (charset) و نمای نمایش (viewport)؛ عناصر اختیاری .Li از متاداده وابستگی سازمانی (پدیدآور)، نویسنده، حق نشر و تاریخ؛ منابع اختیاری CSS از متاداده؛ منابع اختیاری جاوااسکریپت از متاداده؛ عنصر .Li که احتمالاً خالی است؛ سپس محتوای دلخواه و اختیاری از سرآیند HTML متاداده می‌باشد. .It Fl t Ns Ar latex عبارت‌های پیش‌درآمد .Li documentclass و .Li usepackage , محتوای دلخواه و اختیاری از سرآیند LaTeX متاداده، سپس عبارت‌های احاطه‌کننده .Li begin{document} . .It Fl t Ns Ar man , Fl t Ns Ar mdoc , Fl t Ns Ar ms ماکروهای پیش‌درآمد. .It Fl t Ns Ar term خطوط پیش‌درآمد. .It Fl t Ns Ar tree متاداده و قالب تجزیه‌شده. .El .Pp برای مقادیر متاداده استفاده‌شده توسط قالب پیش‌فرض، به .Sx Metadata مراجعه کنید. .Ss Metadata کلیدهای متاداده به ترتیب زیر استانداردسازی و یکتا (حذف موارد تکراری) می‌شوند: .Fl m .Pq که با محتوای سند و Fl M بازنویسی می‌شود , پیش‌درآمد خود سند، و سپس .Fl M .Pq که بر محتوای سند و Fl m اولویت دارد و آن‌ها را بازنویسی می‌کند . .Pp پس از یکتا کردن، متاداده در متغیرهای سند و/یا خروجی سند مستقل .Fl s سریال‌سازی می‌شود. .Pp هنگامی که از .Fl -template استفاده نشود، کلیدهای متاداده زیر در قالب پیش‌فرض .Fl s استفاده می‌شوند: .Bl -tag -width Ds .It Li affiliation وابستگی سازمانی نویسنده (سازمان یا مؤسسه). وابستگی‌های سازمانی چندگانه را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد. مورد استفاده در .Fl t Ns Ar html , .Fl t Ns Ar latex , و .Fl t Ns Ar ms . .It Li author نویسنده سند. نویسندگان چندگانه را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد. توسط .Li rcsauthor بازنویسی می‌شود. مورد استفاده در .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar ms , و .Fl t Ns Ar term . .It Li baseheaderlevel به سطح هر عنوان اضافه می‌شود. منسوخ شده و به جای آن استفاده از .Li shiftheadinglevelby توصیه می‌شود. .It Li copyright حق نشر سند (بدون واژه .Dq Copyright ) , برای مثال، .Dq 2017, Kristaps Dzonsons . مورد استفاده در .Fl t Ns Ar ms و .Fl t Ns Ar html . .It Li css فایل CSS خروجی در head سند HTML به‌عنوان دستور .Li <link rel="stylesheet" href="..." /> . چندین فایل CSS (به ترتیب) را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد و به همان ترتیب داده‌شده در خروجی قرار می‌گیرند. تنها در .Fl t Ns Ar html استفاده می‌شود. .It Li date تاریخ سند در قالب ISO-8601 YYYY-MM-DD. توسط .Li rcsdate بازنویسی می‌شود. مورد استفاده در .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar mdoc , .Fl t Ns Ar ms , و .Fl t Ns Ar term . .It Li htmlheader محتوای دلخواه HTML خروجی در head سند HTML بلافاصله قبل از بسته شدن عنصر head. تنها در .Fl t Ns Ar html و همراه با .Fl s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود. .It Li javascript فایل جاوااسکریپت خروجی در head سند HTML به‌عنوان دستور .Li <script src="..."></script> . چندین فایل اسکریپت (به ترتیب) را می‌توان با دو یا چند فاصله (از جمله خط‌های جدید) از یکدیگر جدا کرد و به همان ترتیب داده‌شده در خروجی قرار می‌گیرند. تنها در .Fl t Ns Ar html استفاده می‌شود. .It Li lang زبان سند در قالب RFC 5646. تنها در .Fl t Ns Ar html استفاده می‌شود. .It Li latexheader محتوای دلخواه LaTeX خروجی در پیش‌درآمد سند بلافاصله قبل از .Li begin{document} . تنها در .Fl t Ns Ar latex و همراه با .Fl s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود. .It Li manheader محتوای دلخواه roff خروجی بلافاصله قبل از ماکروی .Li .TH . تنها در .Fl t Ns Ar man و همراه با .Fl s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود. .It Li msheader محتوای دلخواه roff خروجی بلافاصله قبل از ماکروی .Li .TL . تنها در .Fl t Ns Ar ms و همراه با .Fl s استفاده می‌شود. این متاداده پردازش نمی‌شود: بدون تغییر به خروجی منتقل می‌شود. .It Li rcsauthor مشابه .Li author , اما در قالب نویسنده RCS. بر .Li author اولویت دارد و آن را بازنویسی می‌کند. .It Li rcsdate مشابه .Li date , اما در قالب تاریخ RCS. بر .Li date اولویت دارد و آن را بازنویسی می‌کند. .It Li section بخش صفحه راهنما (man page)، با مقدار پیش‌فرض .Dq 7 . تنها در .Fl t Ns Ar man و .Fl t Ns Ar mdoc استفاده می‌شود. .It Li shiftheadinglevelby انتقال سطح تمام عنوان‌ها به اندازه مقدار داده‌شده. برای مثال، مقدار ۱ باعث می‌شود عنوان‌هایی که در اصل در سطح ۱ بودند .Pq Dq <h1> به سطح ۲ تبدیل شوند .Pq Dq <h2> , در حالی که مقدار \-1 سطح ۲ را به ۱ منتقل می‌کند. سطوح به کمتر از ۱ منتقل نخواهند شد. بر .Li baseheaderlevel اولویت دارد. اگر تنظیم نشده باشد یا یک عدد معتبر نباشد، پیش‌فرض آن صفر است. مورد استفاده در .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar mdoc , و .Fl t Ns Ar ms . .It Li source منبع صفحه راهنما (سازمان ارائه‌دهنده راهنما). تنها در .Fl t Ns Ar man و .Fl t Ns Ar mdoc استفاده می‌شود. .It Li volume جلد صفحه راهنما (توصیف‌کننده بخش صفحه راهنما). تنها در .Fl t Ns Ar man و .Fl t Ns Ar mdoc استفاده می‌شود. .It Li title عنوان سند. مورد استفاده در .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar mdoc , .Fl t Ns Ar ms , و .Fl t Ns Ar term . .El .Pp مقادیر پیش‌فرض، مانند .Dq 7 برای .Li section , به‌عنوان مقادیر متاداده تنظیم نمی‌شوند و در صورتی که کلید متاداده به‌عنوان متغیر استفاده شود، ظاهر نخواهند شد. .Ss Templates برخی رسانه‌های خروجی یک قالب .Pq Fl -template را برای سفارشی‌سازی خروجی مستقل .Pq Fl s می‌پذیرند. محتوای ورودی تجزیه‌شده از طریق دستورات کنترلی در قالب‌ها قرار می‌گیرد؛ این دستورات از شرط‌ها، حلقه‌ها و توالی‌های تبدیل متغیر پشتیبانی می‌کنند. .Pp دستورات کنترلی با .Cm $statement$ یا .Cm ${statement} محدود می‌شوند. فاصله‌های خالی دلخواه می‌توانند دستور غیرحساس به بزرگی و کوچکی حروف را میان جداکننده‌های منطبق احاطه کنند. دستورات بدون جداکننده پایانی به عنوان متن ساده در نظر گرفته می‌شوند. .Pp دستورات زیر در دسترس هستند: .Bl -tag -width Ds .It Cm $$ , ${} یک نویسه واقعی .Cm $ را در خروجی چاپ می‌کند. این عبارت می‌تواند شامل فاصله‌های خالی دلخواه باشد. .It Cm $ifdef(expression)$ دستور شرطی. نباید هیچ فاصله خالی میان .Cm ifdef و پرانتز باز وجود داشته باشد. بلوکی را آغاز می‌کند که با یک .Cm else , .Cm endif یا پایان فایل خاتمه می‌یابد. محتوای آن تنها در صورتی در خروجی قرار می‌گیرد که .Cm expression به یک رشته غیرخالی ارزیابی شود. .It Cm $else$ بلوکی را آغاز می‌کند که با یک .Cm endif یا پایان فایل خاتمه می‌یابد. محتوای آن تنها در صورتی در خروجی قرار می‌گیرد که شرط .Cm ifdef قبلی به یک رشته خالی ارزیابی شود. یک .Cm else بدون .Cm ifdef قبلی در خروجی درج نمی‌شود. .It Cm $endif$ بلوکی را که با .Cm ifdef یا .Cm else آغاز شده می‌بندد. اگر قبل از آن یکی از این دستورات نیامده باشد، بدون هشدار نادیده گرفته می‌شود. .It Cm $for(expression)$ دستور حلقه. نباید هیچ فاصله خالی میان .Cm for و پرانتز باز وجود داشته باشد. بلوکی را آغاز می‌کند که با یک .Cm endfor یا پایان فایل خاتمه می‌یابد. محتوای بلوک به ازای هر مورد از فهرست ارزیابی‌شده از .Cm expression به‌طور مکرر در خروجی چاپ می‌شود. کلیدواژه ارجاعی .Cm this می‌تواند برای دسترسی به عبارت حلقه جاری در داخل بلوک استفاده شود. .It Cm $expression$ با نتیجه ارزیابی عبارت قالب جایگزین می‌شود. .El .Pp اگر یک دستور کنترلی با دو خط تیره متوالی پیش از جداکننده پایانی تمام شود، ورودی تا و شامل خط جدید بعدی یا تا پایان فایل خوانده و مصرف می‌شود. این ویژگی به رسانه‌های خروجی حساس به خط اجازه می‌دهد از دستورات کنترلی بدون خطوط خالی اضافی استفاده کنند. .Pp عبارت‌ها از .Pp .Dl initial[([arg]*)]?[.transform[([arg]*)]?]* , .Pp یا یک مقدار اولیه که آرگومان‌های اختیاری را می‌پذیرد، به‌همراه یک سری تبدیل‌های اختیاری که آرگومان‌های اختیاری را می‌پذیرند، تشکیل شده‌اند. اگر فهرست آرگومان‌ها خالی باشد یا ارائه نشود، به یک فهرست خالی ارزیابی می‌شود. .Pp مقدار .Li initial یکی از موارد زیر است: .Bl -tag -width Ds .It Cm and(expression[,expression]*) یک فهرست غیرخالی حاوی مقدار .Li true در صورتی که تمام عبارت‌ها به فهرست‌های غیرخالی ارزیابی شوند؛ در غیر این صورت یک فهرست خالی. یک عبارت خالی به یک فهرست خالی ارزیابی می‌شود. .It Li \(dqliteral string\(dq به یک فهرست تک‌عضوی حاوی این رشته ارزیابی می‌شود. یک رشته خالی به یک فهرست خالی ارزیابی می‌شود. نویسه نقل‌قول دوگانه را می‌توان اسکیپ کرد، مانند .Li \(dqfoo\e\(dqbar\(dq . .It Cm body بدنه سند ورودی تجزیه‌شده. .It کلید متادیتای متعارف (canonicalised metadata key) مقدار کلید متادیتای داده‌شده در صورت پیدا شدن؛ در غیر این صورت یک فهرست خالی. .It Cm body بدنه سند ورودی تجزیه‌شده. .It Cm meta(key) مقدار متادیتا را برای کلید متادیتای متعارف .Cm key تولید می‌کند. این امکان را برای کلیدهایی فراهم می‌کند که خود کلیدواژه هستند، مانند .Li body یا .Li endif . .It Cm not(expression) یک فهرست غیرخالی حاوی مقدار .Li true در صورتی که عبارت به یک فهرست خالی ارزیابی شود؛ در غیر این صورت یک فهرست خالی. .It Cm or(expression[,expression]*) یک فهرست غیرخالی حاوی مقدار .Li true در صورتی که حداقل یک عبارت به یک فهرست غیرخالی ارزیابی شود؛ در غیر این صورت یک فهرست خالی. یک عبارت خالی به یک فهرست خالی ارزیابی می‌شود. .It Cm this مقدار یک زمینه حلقه جاری یا یک فهرست خالی. .El .Pp اگر یک کلید متادیتا در ورودی مشخص نشده باشد، یا اگر کلیدواژه ارجاعی .Cm this توسط یک زمینه حلقه مقداردهی اولیه نشده باشد، مقدار اولیه به یک فهرست خالی ارزیابی می‌شود. در غیر این صورت، این مقدار یک فهرست تک‌عضوی است. .Pp اگر تبدیل‌ها نامعتبر باشند، به یک فهرست خالی تبدیل خواهند شد. .Pp تبدیل‌های زیر در دسترس هستند: .Bl -tag -width Ds .It Cm escapegemini , escapegeminiline گریز دادن (escape) موارد فهرست برای جِمینای .Pq Fl t Ns Ar gemini , خواه برای چندین خط یا به‌صورت فشرده در یک خط واحد. .It Cm escapehtml , escapehtmlattr , escapehtmlurl گریز دادن موارد فهرست برای محتوای بدنه، مشخصه‌ها و مشخصه‌های نشانی وب در HTML .Pq Fl t Ns Ar html به ترتیب. .It Cm escapelatex گریز دادن موارد فهرست برای محتوای بدنه LaTeX .Pq Fl t Ns Ar latex . .It Cm escaperoff , escaperoffline گریز دادن موارد فهرست برای roff .Pq Fl t Ns Ar ms , Fl t Ns Ar man , Fl t Ns Ar mdoc , خواه برای چندین خط یا به‌صورت فشرده در یک خط واحد. .Cm escaperoff همچنین جداکننده‌های ابتدایی roff و جداکننده‌های پس از خطوط جدید را گریز می‌دهد. .It Cm join اتصال یک فهرست به یک فهرست تک‌عضوی با استفاده از دو فاصله به عنوان جداکننده اتصال. .It Cm lowercase تبدیل تمام موارد فهرست به حروف کوچک. .It Cm split تقسیم موارد فهرست بر اساس توالی دو یا چند نشانه فاصله خالی (فاصله، خط جدید، تب). این تبدیل معمولاً روی یک مقدار تک‌عضوی فراخوانی می‌شود، اما می‌تواند به‌طور مکرر روی فهرستی که از قبل تقسیم شده است نیز اجرا شود. پیش از اولین تقسیم، .Cm trim را فراخوانی می‌کند. فهرست حاصل هیچ عضوی که صرفاً فاصله خالی باشد نخواهد داشت. .It Cm trim حذف فاصله‌های خالی از ابتدا و انتهای تمام موارد فهرست. اگر موردی هیچ نویسه غیر فاصله خالی نداشته باشد، حذف می‌شود. .It Cm uppercase تبدیل تمام موارد فهرست به حروف بزرگ. .El .Sh "محیط (ENVIRONMENT)" .Bl -tag -width Ds .It Ev NO_COLOR عدم چاپ رنگ‌ها هنگام کار در حالت .Fl t Ns Ar term . مترادف با .Ev NO_COLOUR . مشابه با .Fl -term-nocolour . .El .Sh "فایل‌ها (FILES)" .Bl -tag -width Ds .It Pa share/html/default.html قالب پیش‌فرضی که در صورت مشخص نشدن .Fl -template برای .Fl t Ns Ar html استفاده می‌شود. .It Pa share/latex/default.latex قالب پیش‌فرضی که در صورت مشخص نشدن .Fl -template برای .Fl t Ns Ar latex استفاده می‌شود. .It Pa share/man/default.man قالب پیش‌فرضی که در صورت مشخص نشدن .Fl -template برای .Fl t Ns Ar man استفاده می‌شود. .It Pa share/man/default.ms قالب پیش‌فرضی که در صورت مشخص نشدن .Fl -template برای .Fl t Ns Ar ms استفاده می‌شود. .It Pa share/odt/styles.xml شیوه‌های پیش‌فرضی که هنگام تولید اسناد مستقل .Fl t Ns Ar fodt استفاده می‌شوند. قالب برای شیوه‌های .Fl -odt-style . .El .Sh "وضعیت خروج (EXIT STATUS)" .Ex -std .Sh "مثال‌ها (EXAMPLES)" برای مشاهده تفاوت‌های مارک‌داون در یک ترمینال سازگار با ANSI و UTF-8: .Pp .Dl lowdown-diff -tterm old.md new.md | less -R .Pp برای تولید یک سند مستقل HTML5: .Pp .Dl lowdown-diff -s old.md new.md > foo.html .Pp برای استفاده از .Xr groff 1 جهت قالب‌بندی به عنوان یک فایل PS: .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e groff -itk -mspdf > foo.ps .Ed .Pp یا با استفاده از LaTeX: .Bd -literal -offset indent lowdown-diff -stlatex old.md new.md > foo.latex pslatex foo.latex .Ed .Pp تولید PDF از منطق مشابهی پیروی می‌کند: .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e pdfroff -itk -mspdf > foo.pdf lowdown-diff -stlatex old.md new.md > foo.latex pdflatex foo.latex .Ed .Pp پشتیبانی از UTF-8 برای خروجی PDF یا PS در .Xr groff 1 نیازمند قلم‌های مناسب است، مانند قلم Unicode Times. این قلم و سایر قلم‌های یونیکد همیشه به‌طور پیش‌فرض نصب نیستند. این قلم‌ها برای خروجی PDF را می‌توان در مجموعه .Pa devpdf از پوشه قلم‌های .Xr groff 1 یافت که با پیشوند .Sq U مشخص شده‌اند. .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e pdfroff -itk -mspdf -FU-T > foo.pdf .Ed .Sh "همچنین ببینید (SEE ALSO)" .Xr lowdown 1 , .Xr lowdown 3 , .Xr lowdown 5 .Sh "نویسندگان (AUTHORS)" .Nm توسط .An Kristaps Dzonsons , .Mt kristaps@bsd.lv نوشته شده است. .Sh "هشدارها (CAVEATS)" هنگام مشاهده تفاوت‌های .Fl t Ns Ar man یا .Fl t Ns Ar mdoc با .Xr mandoc 1 , رنگ‌های نشانگر رندر نمی‌شوند. همچنین خروجی .Fl t Ns Ar gemini در حال حاضر روشی برای کدگذاری تفاوت‌ها ندارد.