نام (NAME)

glilypond - یکپارچه‌سازی بخش‌های موسیقی LilyPond در اسناد groff

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

glilypond [-k] [{--ly2eps|--pdf2eps}] [-e directory] [-o output-file] [-p filename-prefix] [-t tdir] [{-v|-V}] [--] [file ...]

glilypond [{--ly2eps|--pdf2eps}] [--eps_dir directory] [--keep_all] [--output output-file] [--prefix filename-prefix] [--temp_dir tdir] [--verbose] [--] [file ...]

glilypond -?

glilypond -h

glilypond --help

glilypond --usage

glilypond -l

glilypond --license

glilypond --version

توضیحات (DESCRIPTION)

دستور glilypond یک پیش‌پردازنده groff(7) است که امکان گنجاندن پارتیتورهای موسیقی LilyPond را در اسناد groff فراهم می‌سازد. اگر هیچ عملوندی ارائه نشود، یا اگر file برابر با “-” باشد، glilypond جریان ورودی استاندارد را می‌خواند. یک آرگومان دوخط‌تیره (“--”) باعث می‌شود تمامی آرگومان‌های پس از آن، حتی اگر نام آن‌ها با خط تیره آغاز شود، به عنوان عملوندهای file تفسیر شوند.

دستور glilypond به ماژول پرل File::HomeDir نیاز دارد که از طریق CPAN در دسترس است.

کاربرد (USAGE)

در حال حاضر، glilypond با دستگاه‌های خروجی ps، dvi، html و xhtml در groff کار می‌کند. دستگاه‌های lbp و lj4 هنوز آزمایش نشده‌اند. متأسفانه، دستگاه pdf هنوز کار نمی‌کند.

بررسی اجمالی گزینه‌ها (OPTION OVERVIEW)

-?|-h|--help|--usage: نمایش اطلاعات نحوه استفاده و خروج.
--version: نمایش اطلاعات نسخه و خروج.
-l|--license: نمایش اطلاعات مجوز حق نشر و خروج.

گزینه‌های ساخت فایل‌های EPS

--ly2eps: هدایت lilypond(1) برای ایجاد فایل‌های PostScript کپسوله‌شده (EPS). این مقدار پیش‌فرض است.
--pdf2eps: برنامه glilypond با استفاده از lilypond یک فایل PDF تولید می‌کند. سپس فایل EPS توسط pdf2ps و ps2eps ایجاد می‌شود.

دایرکتوری‌ها و فایل‌ها

-e|--eps_dir directory_name: به‌طور معمول تمام فایل‌های EPS به دایرکتوری موقت ارسال می‌شوند. با استفاده از این گزینه، می‌توانید دایرکتوری دلخواه خود را بسازید که تمام فایل‌های مفید EPS به آن ارسال شوند. بدین ترتیب در پایان، دایرکتوری موقت می‌تواند حذف شود.
-p|--prefix begin_of_name: به‌طور معمول تمام فایل‌های موقت نام‌هایی دریافت می‌کنند که با پیشوند ly... آغاز می‌شوند. با استفاده از این گزینه، می‌توانید آزادانه این پیشوند را تغییر دهید.
-k|--keep_all: به‌طور معمول تمام فایل‌های موقت به جز فایل‌های eps حذف می‌شوند. با استفاده از این گزینه، تمام فایل‌های تولیدشده توسط برنامه lilypond یا سایر مبدل‌های فرمت نگه‌داشته می‌شوند.
-t|--temp_dir dir: با استفاده از این گزینه، دایرکتوری پایه‌ای را برای دایرکتوری موقت مشخص می‌کنید. نام این دایرکتوری عیناً و بدون هیچ پسوندی استفاده می‌شود. اگر این دایرکتوری وجود نداشته باشد ایجاد می‌شود. دایرکتوری موقت از طریق عملیات امنیتی پرل مستقیماً در زیر این دایرکتوری ایجاد می‌گردد. فایل‌های موقت در این دایرکتوری موقت ذخیره می‌شوند.

خروجی

-o|--output file_name: به‌طور معمول تمام خروجی groff این برنامه به STDOUT (خروجی استاندارد) ارسال می‌شود. با استفاده از این گزینه، می‌توان آن را تغییر داد به طوری که خروجی در فایلی با نام مشخص‌شده در آرگومان گزینه file_name ذخیره شود.
-v|-V|--verbose: اطلاعات بسیار بیشتری به STDERR (خطای استاندارد) ارسال می‌شود.

مجموعه گزینه‌های کوتاه

مدیریت آرگومان‌های گزینه‌ها

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

چنین مجموعه‌ای می‌تواند با نویسه گزینه‌ای که به یک آرگومان گزینه نیاز دارد خاتمه یابد. اگر این نویسه گزینه آخرین نویسه آرگومان نباشد، بخش پایانی آرگومان به عنوان آرگومان گزینه در نظر گرفته می‌شود. اگر آخرین نویسه آرگومان باشد، آرگومان بعدی به عنوان آرگومان گزینه در نظر گرفته می‌شود.

این رفتار، استاندارد مدیریت گزینه‌ها در POSIX و GNU است.

برای مثال،

-kVe some_dir: مجموعه‌ای از گزینه‌های کوتاه -k و -V بدون آرگومان گزینه است، که به دنبال آن گزینه کوتاه -e همراه با آرگومان گزینه که بخش بعدی آرگومان یعنی some_dir است، قرار دارد. بنابراین این آرگومان را می‌توان به صورت چند آرگومان مجزا نیز نوشت: -k -V -e some_dir.

مدیریت گزینه‌های بلند

آرگومان‌هایی که با دو خط تیره -- آغاز می‌شوند، اصطلاحاً گزینه‌های بلند نامیده می‌شوند. هر آرگومان دارای دو خط تیره تنها می‌تواند شامل یک گزینه بلند باشد.

گزینه‌های بلند می‌توانند دارای آرگومان گزینه باشند یا نباشند. یک آرگومان گزینه می‌تواند آرگومان بعدی باشد یا با علامت مساوی = به همان آرگومان گزینه بلند متصل شود.

--help: یک گزینه بلند بدون آرگومان گزینه است.
--eps_dir some_dir
--eps_dir=some_dir: گزینه بلند --eps_dir همراه با آرگومان گزینه some_dir است.

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

گزینه بلند --keep_all می‌تواند از --keep_al تا --k خلاصه شود، زیرا برنامه گزینه بلند دیگری ندارد که نام آن با نویسه k آغاز شود.

از سوی دیگر، گزینه --version را نمی‌توان بیشتر از --vers خلاصه کرد، زیرا گزینه بلند دیگری به نام --verbose نیز وجود دارد که می‌تواند تا --verb خلاصه شود.

همچنین می‌توان یک آرگومان گزینه را به شکل خلاصه‌شده نیز متصل کرد. بنابراین --e=some_dir مشابه با --eps_dir some_dir است.

علاوه بر این، این برنامه استفاده اختیاری از حروف کوچک و بزرگ را در نام گزینه‌ها مجاز می‌داند. این سبک زبان Perl است.

برای مثال، گزینه بلند --keep_all می‌تواند به صورت --Keep_All یا حتی به شکل خلاصه‌ای مانند --KeE نوشته شود.

ناحیه‌های LilyPond در ورودی roff

کد یکپارچه‌شده LilyPond

یک بخش lilypond درون ساختاری که به زبان groff نوشته شده است، کل بخش میان نشانه‌های زیر است:

.lilypond start

و

.lilypond end

یک ورودی groff می‌تواند چندین مورد از این بخش‌های lilypond داشته باشد.

هنگام پردازش چنین بخش lilypond میان .lilypond start و .lilypond end، می‌گوییم برنامه glilypond در حالت lilypond (lilypond mode) قرار دارد.

این بخش‌های lilypond به فایل‌های موقت lilypond با پسوند نام فایل .ly ارسال می‌شوند. این فایل‌ها بعداً به فایل‌های EPS تبدیل می‌گردند.

گنجاندن فایل‌های .ly

یک دستور خط فرمان اضافی برای گنجاندن فایل‌های lilypond به صورت زیر در ورودی groff ارائه می‌شود:

.lilypond include file_name

به ازای هر یک از چنین دستورات include، یک فایل از کدهای lilypond می‌تواند درون کدهای groff گنجانده شود. تعداد دلخواهی از این دستورات می‌تواند در ورودی groff گنجانده شود.

این دستورات گنجاندن تنها خارج از بخش‌های lilypond قابل استفاده هستند. درون حالت lilypond، این عمل گنجاندن ممکن نیست. بنابراین .lilypond include نباید در حالت lilypond استفاده شود؛ یعنی میان .lilypond start و .lilypond end. این فایل‌های ly گنجانده‌شده نیز به فایل‌های EPS تبدیل می‌شوند.

فایل‌های تولیدشده (GENERATED FILES)

در فرایند تبدیل بخش‌های lilypond به فایل‌های EPS، فایل‌های متعددی تولید می‌شوند. به‌طور پیش‌فرض، این فایل‌ها به عنوان فایل‌های موقت در نظر گرفته شده و به همین صورت در یک دایرکتوری موقت ذخیره می‌شوند. این فرایند را می‌توان با گزینه‌های خط فرمان تغییر داد.

گزینه‌های خط فرمان برای دایرکتوری‌ها

دایرکتوری موقت برای این برنامه یا به‌طور خودکار ایجاد می‌شود یا می‌توان آن را با گزینه -t|--temp_dir dir نام‌گذاری کرد.

علاوه بر این، فایل‌های EPS که بعداً توسط دستور .PSPIC در خروجی نهایی groff ارجاع داده می‌شوند را می‌توان در دایرکتوری دیگری ذخیره کرد که توسط گزینه خط فرمان -e|--eps_dir directory_name تعیین می‌شود. با این گزینه، دایرکتوری موقت را می‌توان در پایان اجرای برنامه کاملاً حذف کرد.

ابتدای نام فایل‌های موقت را می‌توان با گزینه‌های خط فرمان -p یا --prefix تنظیم کرد.

تمام فایل‌های موقت به جز فایل‌های EPS در نهایت حذف می‌شوند. این رفتار را می‌توان با تنظیم گزینه‌های خط فرمان -k یا --keep_files تغییر داد. با این کار، تمام فایل‌ها و دایرکتوری‌های موقت نگه‌داشته شده و حذف نمی‌شوند.

این فایل‌های EPS در یک دایرکتوری موقت یا دایرکتوری EPS ذخیره می‌شوند. اما فرایند تبدیل نمی‌تواند آن‌ها را حذف کند، زیرا برای نمایش مورد نیاز هستند که ممکن است زمان زیادی به طول انجامد.

فرایندهای تبدیل برای تولید فایل‌های EPS

حالت pdf2eps

در این حالت، که پیش‌فرض فعلی است، فایل‌های .ly توسط برنامه lilypond(1) با استفاده از

lilypond --pdf --output=file-name

به ازای هر فایل .ly به فایل‌های PDF تبدیل می‌شوند. مقدار file-name باید بدون پسوند .pdf ارائه شود. از طریق این فرایند، فایلی به نام file-name.pdf تولید می‌شود.

گام بعدی تبدیل این فایل‌های PDF به یک فایل PS است. این کار توسط برنامه pdf2ps(1) با استفاده از

$ 
pdf2ps 
file-name.pdf 
file-name.pds

انجام می‌شود. گام بعدی، یک فایل EPS از فایل PS ایجاد می‌کند. این کار توسط برنامه ps2eps(1) با استفاده از

$ ps2eps file-name.ps

انجام می‌شود.

بدین ترتیب، یک فایل file-name.eps برای هر بخش lilypond در فایل groff یا ورودی استاندارد ایجاد می‌شود.

آخرین گام که باید انجام شود، جایگزینی تمام بخش‌های lilypond با دستور groff زیر است:

.PSPIC file-name.eps

حالت ly2eps

در گذشته، این حالت پیش‌فرض بود. اما اکنون دیگر کار نمی‌کند، بنابراین حالت پیش‌فرض جدید یعنی pdf2eps را بپذیرید. برای آزمایش، این حالت را نیز می‌توان با گزینه --ly2eps در glilypond انتخاب کرد.

در این حالت، فایل‌های .ly توسط برنامه lilypond با استفاده از دستور

$ 
lilypond --ps -dbackend=eps -dgs-load-fonts --output=
file-name

به ازای هر فایل .ly به فایل‌های متعدد با فرمت‌های گوناگون از جمله فایل‌های eps تبدیل می‌شوند. نام فایل خروجی file-name باید بدون پسوند ارائه شود و دایرکتوری آن موقت است.

فایل‌های EPS متعددی ایجاد می‌شوند. یکی شامل فایل تبدیل‌شده کامل ly، به نام file-name.eps.

علاوه بر این، فایل‌های EPS برای هر صفحه وجود دارد، به نام file-name-digit.eps.

آخرین مرحله، جایگزینی تمام بخش‌های lilypond با مجموعه‌ای از فایل‌های صفحات EPS مربوطه است. این کار با دستورات groff زیر انجام می‌شود:

.PSPIC file-name-digit.eps

خروجی groff تولیدشده

ساختار جدید groff(7) تولیدشده توسط glilypond یا:

1): به خروجی استاندارد ارسال می‌شود و در آنجا می‌تواند در یک فایل ذخیره شده یا به groff(1) پایپ (هدایت) شود، و یا
2): با تعیین گزینه -o | --output file_name در یک فایل ذخیره شود.

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

برنامه glilypond توسط Bernd Warken نوشته شده است.

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

groff(1): نحوه استفاده از دستور groff را شرح می‌دهد و حاوی ارجاعاتی به مستندات تکمیلی سیستم groff است.
groff_tmac(5): درخواست .PSPIC را شرح می‌دهد.
lilypond(1): به طور خلاصه دستور lilypond را شرح می‌دهد و حاوی ارجاعاتی به مستندات تکمیلی است.
pdf2ps(1): یک فایل PDF را به فرمت PostScript تبدیل می‌کند.
ps2eps(1): یک فایل PS را به فرمت EPS تبدیل می‌کند.