نام (NAME)

lowdown — مترجم ساده مارک‌داون

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

lowdown [input_options] [output_options] [-Ls] [-M metadata] [-m metadata] [-o file] [-t mode] [-X keyword] [file]

توضیحات (DESCRIPTION)

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

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

-L: فهرست کردن کلیدهای فراداده، هر کلید در یک خط. حالت -t نادیده گرفته می‌شود. فراداده به‌طور خودکار فعال می‌گردد. گزینه -X را لغو می‌کند.
-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 برای خروجی ترمینال UTF-8 سازگار با ANSI، man برای خروجی roff با استفاده از بسته -man, mdoc برای خروجی roff با استفاده از بسته -mdoc, tree, برای نمایش درخت تجزیه سند ورودی، و null برای تجزیه سند بدون انجام رندر. به رسانه‌های خروجی (Output media) مراجعه کنید. قالب -T mode برای سازگاری با گذشته حفظ شده است.
-X keyword: چاپ مقدار فراداده برای keyword یا یک رشته خالی در صورت پیدا نشدن آن. حالت -t نادیده گرفته می‌شود. فراداده به‌طور خودکار فعال می‌گردد. گزینه -L را لغو می‌کند.
file: سند ورودی مارک‌داون. اگر مشخص نشود یا اگر file برابر با “-” باشد، از ورودی استاندارد خوانده می‌شود.

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

--parse-hilite

فعال‌سازی پشتیبانی از برجسته‌سازی متن (highlight span). این ویژگی به‌طور پیش‌فرض غیرفعال است زیرا ممکن است به‌اشتباه به‌عنوان سرآیند بخش‌ها تفسیر شود.

--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 (“هشدارهای توصیه‌ای”) تجزیه نشوند.

--parse-no-deflists

فهرست‌های تعاریف اضافی PHP تجزیه نشوند.

--parse-no-ext-attrs

ویژگی‌های گسترش‌یافته اضافی PHP تجزیه نشوند.

--parse-no-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 “کوتاه” استفاده شود.

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

--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-custom-attributes: چاپ ویژگی‌های ناشناخته HTML برای پیوندها، تصویرها و سرآیندها.
--html-hardwrap: شکستن سخت خطوط (hard-wrap) در بندها با درج شکست‌های خط در صورت امکان.
--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: جایگزینی قلم‌های پیش‌فرض با عرض ثابت با یک چندتایی از متغیرهای عادی، پررنگ، مورب و پررنگ‌مورب به همان ترتیب. برای نمونه، B,B,BI,BI به‌جای قلم با عرض ثابت از قلم پررنگ (“B”) استفاده می‌کند. مشخص نکردن قلم یا تعیین نام قلم با طول صفر، از پیش‌فرض استفاده خواهد کرد. نام‌های مستعار none, bold و code به‌ترتیب بدون قلم ویژه، پررنگ، و قلم با عرض ثابت پیش‌فرض را تنظیم می‌کنند.
--roff-endnotes: به تأخیر انداختن چاپ پانویس‌ها تا انتهای سند. فقط برای -tms اعمال می‌شود، زیرا -tman و -tmdoc تنها از یادداشت‌های پایانی (endnotes) پشتیبانی می‌کنند.
--roff-manpage: قالب‌بندی خروجی به‌عنوان یک صفحه راهنما (manpage). این گزینه بندهای موجود در بخش‌های NAME, SYNOPSIS و SEE ALSO را به فرم استاندارد مورد استفاده در صفحات راهنما بازآرایی می‌کند. نحوه قالب‌بندی سند به فراداده بخش بستگی دارد: ۱، ۶ و ۸ برای سبک برنامه؛ ۲، ۳ و ۹ برای سبک توابع. سبک برنامه فلگ‌ها و آرگومان‌ها را بازآرایی می‌کند، در حالی که سبک توابع نام توابع، متغیرها و آرگومان‌ها را بازآرایی می‌نماید. هرگونه محتوا در گستره قلم‌ها (مانند تأکید یا تأکید دوگانه) در بخش‌های دیگر، از قلم مربوطه پاک شده و به همان شیوه بازآرایی می‌شود. تنها برای -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) کاربرد دارد. پیش‌فرض بر اساس گزارش ترمینال است یا ۷۲ در صورتی که در ترمینال نباشد.
--term-hmargin=margin: تعداد نویسه‌های حاشیه چپ. پیش‌فرض صفر است. همچنین می‌تواند auto باشد تا حاشیه چپ را پس از کم کردن --term-width, به نصف باقیمانده --term-columns تنظیم کند.
--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). این مقدار ممکن است توسط متن لفظی نقض شود. اگر صفر باشد یا تنظیم نشود، پیش‌فرض آن --term-columns یا حداکثر ۸۰ است. به مقدار --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: مشخص کردن یک فایل سبک OpenDocument که باید دست‌کم شامل عناصر XML <office:font-face-decls>, <office:scripts> و <office:styles> در ریشه سند باشد. صحت نحو این فایل به هیچ وجه بررسی نمی‌شود.

رسانه‌های خروجی (Output media)

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

-tfodt: خروجی OpenDocument “تخت (Flat)”. سبک‌های خودکار (سبک‌هایی که مشروط به وضعیت سند هستند) به همراه خروجی تولید می‌شوند. وجود کلاس‌های مشخص‌شده توسط ویژگی‌های گسترش‌یافته 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: خروجی اشکال‌زدایی. برای استفاده برنامه‌نویسی مناسب نیست زیرا ممکن است قالب آن بین نسخه‌ها تغییر کند.

اسناد مستقل (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> برگرفته از فراداده‌های وابستگی سازمانی (affiliation/سازنده)، نویسنده (author)، حق نشر (copyright) و تاریخ (date)؛ منابع اختیاری CSS برگرفته از فراداده؛ منابع اختیاری JavaScript برگرفته از فراداده؛ عنصر احتمالاً خالی <title> ؛ و سپس محتوای دلخواه اختیاری از فراداده HTML header است.
-tlatex: دستورهای دیباچه documentclass و usepackage, محتوای دلخواه اختیاری از فراداده LaTeX header، و سپس دستورهای احاطه‌کننده begin{document}.
-tman, -tmdoc, -tms: ماکروهای دیباچه.
-tterm: سطرهای دیباچه.
-ttree: فراداده و قالب تجزیه‌شده.

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

فراداده (Metadata)

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

پس از حذف موارد تکراری، فراداده یا به‌طور مستقیم با استفاده از -X یا -L قابل دسترسی است، یا در متغیرهای سند و/یا خروجی مستقل -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 که در سرآمد سند HTML دقیقاً پیش از بستن تگ head چاپ می‌شود. تنها در -thtml و همراه با -s استفاده می‌شود. این فراداده پردازش نمی‌شود: بدون تغییر در خروجی قرار می‌گیرد.
javascript: یک فایل جاوااسکریپت که در سرآمد سند 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: بخش صفحه راهنما، با مقدار پیش‌فرض “7”. تنها در -tman و -tmdoc استفاده می‌شود.
shiftheadinglevelby: تغییر سطح تمام سرآیندها به اندازه عدد داده‌شده. برای مثال، مقدار ۱ باعث می‌شود سرآیندهایی که در اصل در سطح ۱ (“<h1>”) بوده‌اند به سطح ۲ (“<h2>”) تبدیل شوند، در حالی که مقدار ۱- سطح ۲ را به ۱ منتقل می‌کند. سطوح به کمتر از ۱ تغییر نخواهند کرد. بر 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: اسکیپ کردن آیتم‌های فهرست برای gemini (-tgemini), برای چندین خط یا فشرده‌شده در یک خط منفرد.
escapehtml, escapehtmlattr, escapehtmlurl: اسکیپ کردن آیتم‌های فهرست برای HTML (-thtml) به‌ترتیب برای محتوای بدنه، ویژگی‌ها و ویژگی‌های URL.
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/ms/default.ms: قالب پیش‌فرضی که در صورت مشخص نشدن --template برای -tms استفاده می‌شود.
share/odt/styles.xml: سبک‌های پیش‌فرض مورد استفاده هنگام تولید اسناد مستقل -tfodt. قالب برای سبک‌های --odt-style.

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

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

در صورت استفاده از فلگ -X, اگر کلیدواژه داده‌شده یافت نشود، lowdown با خطا خارج می‌شود.

مثال‌ها (EXAMPLES)

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

lowdown -tterm foo.md | less
  -R

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

lowdown -s foo.md >
  foo.html

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

lowdown -stms foo.md | groff -itk -mspdf > foo.ps

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

lowdown -stlatex foo.md > foo.latex
pslatex foo.latex

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

lowdown -stms foo.md | pdfroff -itk -mspdf > foo.pdf
lowdown -stlatex foo.md > foo.latex
pdflatex foo.latex

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

lowdown -stms foo.md | pdfroff -itk -mspdf -FU-T > foo.pdf

صفحات راهنما را می‌توان با استفاده از groff(1) یا mandoc(1) تبدیل کرده و در ترمینال مشاهده نمود:

lowdown -stmdoc foo.md | mandoc | less
lowdown -stman foo.md | groff -itk -man -Tutf8 | less -R

برای فهرست کردن تمام کلیدهای فراداده و سپس استخراج مقدار فراداده “title” از foo.md:

lowdown -L foo.md

lowdown -X title foo.md

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

lowdown-diff(1), lowdown(3), lowdown(5)

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

lowdown از پروژه hoedown توسط Kristaps Dzonsons, kristaps@bsd.lv فورک شده است. از آن زمان تاکنون تغییرات زیادی یافته است.