نام (NAME)

hxincl - بسط دادن فایل‌های HTML یا XML گنجانده‌شده

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

hxincl [ -x ] [ -f ] [ -s name=subst ] [ -s name=subst ]... [ -b base ] [ file-or-URL ]

hxincl -M target [ -s name=subst ] [ -s name=subst ]... [ -b base ] [ -G ] [ file-or-URL ]

توضیحات (DESCRIPTION)

بدون گزینهٔ -M، دستور hxincl یک فایل HTML یا XML را در خروجی استاندارد کپی می‌کند و به‌دنبال کامنت‌هایی با ساختاری معین می‌گردد. چنین کامنتی با فایلی که نام آن به‌عنوان مشخصهٔ دستورالعمل ذکر شده است، جایگزین می‌شود. برای نمونه:

...<!-- include "foo.html" -->...

با محتوای فایل foo.html جایگزین خواهد شد.

کامنت با عبارت

<!-- begin-include "foo.html" -->

پیش از متن گنجانده‌شده و عبارت

<!-- end-include "foo.html" -->

پس از آن جایگزین می‌شود. این کامنت‌ها اجرای دوبارهٔ hxincl را بر روی فایل حاصل برای به‌روزرسانی موارد گنجانده‌شده ممکن می‌سازند.

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

با گزینهٔ -M، دستور hxincl یک خط از وابستگی‌ها تولید می‌کند که برای گنجاندن در یک Makefile مناسب است. target هدف قاعدهٔ Makefile است و hxincl تمامی فایل‌هایی را که به‌صورت بازگشتی گنجانده شده‌اند، پس از «:» فهرست خواهد کرد. برای نمونه، نتیجهٔ

hxincl -M myfile.html inputfile

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

myfile.html: foo.html bar.html

گزینه‌ها (OPTIONS)

گزینه‌های زیر پشتیبانی می‌شوند:

-x

استفاده از قواعد XML: المان‌های خالی با یک ممیز (اسلش) در انتها نوشته می‌شوند: <IMG />.

-b base

نشانی پایه (base URL) را برای حل کردن URLهای نسبی تعیین می‌کند. به‌طور پیش‌فرض، فایلی که به‌عنوان آرگومان داده شده است نشانی پایه محسوب می‌شود.

-f

کامنت‌ها را پس از گنجاندن فایل‌ها حذف می‌کند. این بدان معناست که دیگر نمی‌توان hxincl را بعداً بر روی فایل حاصل برای به‌روزرسانی موارد گنجانده‌شده اجرا کرد. (برای یادآوری: final یا frozen.)

-s name=substitution

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

<!-- include "name" -->

باشد، فایل substitution به‌جای آن گنجانده می‌شود. و اگر نام فایل در کامنت شامل متغیری به نام name باشد که با % مشخص شده است، برای نمونه:

<!-- include "xxx-%name%" -->

آنگاه %name% با substitution جایگزین شده و بنابراین فایل xxx-substitution گنجانده خواهد شد. گزینهٔ -s می‌تواند چندین بار تکرار شود. متغیرهای محصورشده با % به‌صورت بازگشتی بسط داده می‌شوند؛ یعنی اگر متن جایگزین شامل یک متغیر باشد، آن متغیر نیز بسط خواهد یافت. برای نمونه، اگر دو گزینهٔ -s name=%p1%.rrr و -s p1=subst داده شوند، عبارت «xxx-%name%» به «xxx-subst.rrr» بسط داده می‌شود.

-M target

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

-G

صرف‌نظر کردن از پیام‌های خطا در صورتی که فایلی برای گنجاندن یافت نشود. (تنها همراه با -M.)

عملوندها (OPERANDS)

عملوند زیر پشتیبانی می‌شود:

file-or-URL

نام یک فایل HTML یا XML یا نشانی اینترنتی (URL) آن. در صورت عدم وجود، ورودی استاندارد خوانده می‌شود.

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

مقدارهای خروج زیر بازگردانده می‌شوند:

0

پایان موفقیت‌آمیز.

> 0

خطایی هنگام تجزیهٔ یکی از فایل‌های HTML یا XML رخ داده است.

محیط (ENVIRONMENT)

برای استفاده از یک پیشکار (پروکسی) جهت دریافت فایل‌های دوردست، متغیرهای محیطی http_proxy یا ftp_proxy را تنظیم کنید؛ برای نمونه: http_proxy="http://localhost:8080"

گزارش باگ‌ها (BUGS)

ورودی را به‌صورت پیش‌فرض UTF-8 فرض می‌کند. موجودیت‌های نویسه‌ای (character entities) را بسط نمی‌دهد. به‌جای آن، ورودی را از طریق لوله به hxunent(1) و asc2xml(1) ارسال کنید تا به UTF-8 تبدیل شود.

فایل‌های دوردست (مشخص‌شده با یک URL) در حال حاضر تنها برای HTTP پشتیبانی می‌شوند. فایل‌های محافظت‌شده با گذرواژه یا فایل‌هایی که وابسته به «کوکی‌های» HTTP هستند پشتیبانی نمی‌شوند. (می‌توانید از ابزارهایی مانند curl(1) یا wget(1) برای دریافت چنین فایل‌هایی استفاده کنید.)

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

asc2xml(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1), xml2asc(1), UTF-8 (RFC 2279)