.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXINCL" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH "نام (NAME)"
hxincl \- بسط دادن فایل‌های HTML یا XML گنجانده‌شده
.SH "خلاصه دستور (SYNOPSIS)"
.B hxincl
.RB "[\| " \-x " \|]"
.RB "[\| " \-f " \|]"
.RB "[\| " \-s
.IR name=subst " \|]"
.RB "[\| " \-s
.IR name=subst " \|]..."
.RB "[\| " \-b
.IR base " \|]"
.RI "[\| " file\-or\-URL " \|]"
.LP
.B hxincl
.B \-M
.I target
.RB "[\| " \-s
.IR name=subst " \|]"
.RB "[\| " \-s
.IR name=subst " \|]..."
.RB "[\| " \-b
.IR base " \|]"
.RB "[\| " \-G " \|]"
.RI "[\| " file\-or\-URL " \|]"
.SH "توضیحات (DESCRIPTION)"
.LP
بدون گزینهٔ
.BR \-M ،
دستور
.B hxincl
یک فایل HTML یا XML را در خروجی استاندارد کپی می‌کند و به‌دنبال کامنت‌هایی با ساختاری معین می‌گردد. چنین کامنتی با فایلی که نام آن به‌عنوان مشخصهٔ دستورالعمل ذکر شده است، جایگزین می‌شود. برای نمونه:
.d
\&...<!-- include "foo.html" -->...
.e
با محتوای فایل \fIfoo.html\fP جایگزین خواهد شد.
.LP
کامنت با عبارت
.d
<!-- begin-include "foo.html" -->
.e
پیش از متن گنجانده‌شده و عبارت
.d
<!-- end-include "foo.html" -->
.e
پس از آن جایگزین می‌شود. این کامنت‌ها اجرای دوبارهٔ
.B hxincl
را بر روی فایل حاصل برای به‌روزرسانی موارد گنجانده‌شده ممکن می‌سازند.
.PP
استفاده از علامت‌های نقل‌قول تکی به‌جای نقل‌قول دوتایی مجاز است. همچنین اگر نام فایل فاقد فاصله باشد، می‌توان علامت‌های نقل‌قول را حذف کرد.
.PP
با گزینهٔ
.BR \-M ،
دستور
.B hxincl
یک خط از وابستگی‌ها تولید می‌کند که برای گنجاندن در یک Makefile مناسب است.
.I target
هدف قاعدهٔ Makefile است و
.B hxincl
تمامی فایل‌هایی را که به‌صورت بازگشتی گنجانده شده‌اند، پس از «:» فهرست خواهد کرد. برای نمونه، نتیجهٔ
.d
hxincl -M myfile.html inputfile
.e
ممکن است به‌صورت زیر باشد:
.d
myfile.html: foo.html bar.html
.e
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر پشتیبانی می‌شوند:
.TP 10
.B \-x
استفاده از قواعد XML: المان‌های خالی با یک ممیز (اسلش) در انتها نوشته می‌شوند: <IMG\ />.
.TP
.BI \-b " base"
نشانی پایه (base URL) را برای حل کردن URLهای نسبی تعیین می‌کند. به‌طور پیش‌فرض، فایلی که به‌عنوان آرگومان داده شده است نشانی پایه محسوب می‌شود.
.TP
.B \-f
کامنت‌ها را پس از گنجاندن فایل‌ها حذف می‌کند. این بدان معناست که دیگر نمی‌توان
.B hxincl
را بعداً بر روی فایل حاصل برای به‌روزرسانی موارد گنجانده‌شده اجرا کرد. (برای یادآوری:
.BR f inal
یا
.BR f rozen.)
.TP
.BI \-s " name=substitution"
گنجاندن فایلی متفاوت با آنچه در دستورالعمل مشخص شده است. اگر کامنت به‌صورت
.d
<!-- include "name" -->
.e
باشد، فایل
.I substitution
به‌جای آن گنجانده می‌شود. و اگر نام فایل در کامنت شامل متغیری به نام
.I name
باشد که با % مشخص شده است، برای نمونه:
.d
<!-- include "xxx-%name%" -->
.e
آنگاه
.RI % name %
با
.I substitution
جایگزین شده و بنابراین فایل
.RI xxx\- substitution
گنجانده خواهد شد. گزینهٔ
.B \-s
می‌تواند چندین بار تکرار شود. متغیرهای محصورشده با % به‌صورت بازگشتی بسط داده می‌شوند؛ یعنی اگر متن جایگزین شامل یک متغیر باشد، آن متغیر نیز بسط خواهد یافت. برای نمونه، اگر دو گزینهٔ
.B \-s name=%p1%.rrr
و
.B \-s p1=subst
داده شوند، عبارت «xxx-%name%» به «xxx-subst.rrr» بسط داده می‌شود.
.TP
.BI \-M " target"
به‌جای تولید فایل ورودی با تمام موارد گنجانده‌شدهٔ بسط‌یافته، فقط فهرست تمامی فایل‌هایی را که ورودی به‌صورت بازگشتی شامل می‌شود، در قالب قاعده‌ای مناسب برای Makefile خروجی می‌دهد.
.I target
به‌عنوان هدف آن قاعده چاپ می‌شود.
.TP
.B \-G
صرف‌نظر کردن از پیام‌های خطا در صورتی که فایلی برای گنجاندن یافت نشود. (تنها همراه با
.BR \-M .)
.SH "عملوندها (OPERANDS)"
عملوند زیر پشتیبانی می‌شود:
.TP 10
.I file\-or\-URL
نام یک فایل HTML یا XML یا نشانی اینترنتی (URL) آن. در صورت عدم وجود، ورودی استاندارد خوانده می‌شود.
.SH "وضعیت خروج (EXIT STATUS)"
مقدارهای خروج زیر بازگردانده می‌شوند:
.TP 10
.B 0
پایان موفقیت‌آمیز.
.TP
.B > 0
خطایی هنگام تجزیهٔ یکی از فایل‌های HTML یا XML رخ داده است.
.SH "محیط (ENVIRONMENT)"
برای استفاده از یک پیشکار (پروکسی) جهت دریافت فایل‌های دوردست، متغیرهای محیطی
.B http_proxy
یا
.B ftp_proxy
را تنظیم کنید؛ برای نمونه:
.B http_proxy="http://localhost:8080"
.SH "گزارش باگ‌ها (BUGS)"
.LP
ورودی را به‌صورت پیش‌فرض UTF-8 فرض می‌کند. موجودیت‌های نویسه‌ای (character entities) را بسط نمی‌دهد. به‌جای آن، ورودی را از طریق لوله به
.BR hxunent (1)
و
.BR asc2xml (1)
ارسال کنید تا به UTF-8 تبدیل شود.
.LP
فایل‌های دوردست (مشخص‌شده با یک URL) در حال حاضر تنها برای HTTP پشتیبانی می‌شوند. فایل‌های محافظت‌شده با گذرواژه یا فایل‌هایی که وابسته به «کوکی‌های» HTTP هستند پشتیبانی نمی‌شوند. (می‌توانید از ابزارهایی مانند
.BR curl (1)
یا
.BR wget (1)
برای دریافت چنین فایل‌هایی استفاده کنید.)
.SH "همچنین ببینید (SEE ALSO)"
.BR asc2xml (1),
.BR hxnormalize (1),
.BR hxnum (1),
.BR hxprune (1),
.BR hxtoc (1),
.BR hxunent (1),
.BR xml2asc (1),
.BR UTF-8 " (RFC 2279)"