.TH "HXPIPE" "1" "10 Feb 2022" "8.x" "HTML-XML-utils"

.de d \" begin display
.sp
.in +4
.nf
.ft CR
.CDS
..
.de e \" end display
.CDE
.in -4
.fi
.ft R
.sp
..

.SH "نام (NAME)"
hxpipe \- تبدیل ساختار HTML یا XML به فرمت خطی مناسب پایپ
.SH "خلاصه دستور (SYNOPSIS)"
.B hxpipe
.RB "[\| " \-l " \|]"
.RB "[\| " \-H " \|]"
.RB "[\| " \-\- " \|]"
.RI "[\| " file-or-URL " \|]"
.SH "توضیحات (DESCRIPTION)"
دستور
.B hxpipe
یک فایل HTML یا XML را تجزیه کرده و یک نمایش خط‌محور از آن ارائه می‌دهد که برای پردازش‌های بعدی با
.B AWK
یا ابزارهای مشابه بسیار مناسب است. این قالب مشابه خروجی
ESIS (مجموعه اطلاعات ساختار عناصر)
است که توسط
.B nsgmls/onsgmls
تولید می‌شود.
.LP
عملیات معکوس، یعنی تبدیل مجدد به ساختار نشانه‌گذاری، توسط برنامه
.B hxunpipe
انجام می‌شود.
.LP
قالب خروجی به شرح زیر است:
.TP 10
<!--comment-->
توضیحات (کامنت‌ها) به صورت زیر در خروجی نمایش داده می‌شوند:
.d
*comment
.e
به این معنا که یک سطر با "*" شروع شده و متن کامنت در ادامه آن می‌آید. کاراکترهای رفتن به خط بعد (Line feed)، بازگشت به ابتدای خط (Carriage return) و تب (Tab) در متن به ترتیب به صورت "\\n"، "\\r" و "\\t" نوشته می‌شوند. متنی که شبیه به یک موجودیت کاراکتری عددی (Numerical character entity) باشد، با جایگزینی "&" با "\\" نوشته می‌شود. سطر با یک کاراکتر رفتن به خط بعد پایان می‌یابد.
.IP ""
توجه داشته باشید که
.B onsgmls
کامنت‌ها را با شروع از "_" به جای "*" خروجی می‌دهد و "&" را در موجودیت‌های کاراکتری عددی با "\\" جایگزین نمی‌کند (و به صورت پیش‌فرض کامنت‌ها را به کلی نادیده می‌گیرد).
.TP
<?processing instruction>
دستورالعمل‌های پردازشی (Processing instructions) به صورت زیر خارج می‌شوند:
.d
?processing instruction
.e
یعنی یک سطر با "?" شروع شده و متن دستورالعمل در ادامه آن قرار می‌گیرد. نویسه‌های خاص متن نیز مانند بخش کامنت‌ها اسکیپ می‌شوند (به بالا مراجعه کنید).
.TP
<!DOCTYPE root PUBLIC "-//foo//DTD bar//EN" "http://example.org/dtd">
شناسه‌های DOCTYPE به یکی از اشکال زیر در خروجی می‌آیند:
.d
!root "-//foo//DTD bar//EN" http://example.org/dtd
!root "-//foo//DTD bar//EN"
!root "" http://example.org/dtd
!root ""
.e
به ترتیب برای: یک DOCTYPE همراه با (۱) هر دو شناسه عمومی (Public) و سیستمی (System)، (۲) فقط شناسه عمومی، (۳) فقط شناسه سیستمی، یا (۴) هیچ‌کدام از این دو. به عبارت دیگر، یک سطر منفرد با "!" شروع می‌شود، به دنبال آن یک فاصله و یک رشته نقل‌قول‌شده (که ممکن است خالی باشد)، و سپس در صورت وجود یک فاصله و متنی دلخواه می‌آید. به وجود علامت‌های نقل‌قول برای شناسه عمومی و نبود آن برای شناسه سیستمی توجه کنید.
.TP
<elt att1="value1" att2="value2">
تگ آغازین (Start tag) به صورت زیر در خروجی قرار می‌گیرد:
.d
Aatt1 CDATA value1
Aatt2 CDATA value2
(elt
.e
به این صورت که شامل صفر یا چند سطر برای ویژگی‌ها (Attributes) و یک سطر برای نوع عنصر است. هر سطرِ مربوط به ویژگی با "A" شروع می‌شود و به دنبال آن نام ویژگی، یک فاصله، عبارت ثابت "CDATA"، یک فاصله دیگر و سپس مقدار ویژگی می‌آید. نویسه‌های خاص مقدار ویژگی همانند کامنت‌ها اسکیپ می‌شوند (به بالا مراجعه کنید). سطر مربوط به نوع عنصر نیز با "(" شروع شده و نام نوع عنصر در ادامه آن می‌آید.
.IP ""
دستور
.B hxpipe
فایل‌های DTD را نمی‌خواند و فرض می‌کند که ویژگی‌ها همواره از نوع CDATA هستند. این برنامه برخلاف
.B onsgmls
هرگز انواع دیگر (مانند IMPLIED، TOKEN، ID و غیره) را تولید نمی‌کند.
.TP
</elt>
تگ‌های پایانی (End tags) به صورت زیر خروجی داده می‌شوند:
.d
)elt
.e
یعنی به صورت سطری که با ")" شروع شده و به دنبال آن نوع عنصر می‌آید.
.TP
<empty att1="val1" att2="val2"/>
عناصر خالی (Empty elements) به این شکل خارج می‌شوند:
.d
Aatt1 CDATA val1
Aatt2 CDATA val2
|empty
.e
یعنی صفر یا چند سطر برای ویژگی‌ها و یک سطر که با "|" شروع شده و با نوع عنصر ادامه می‌یابد.
.IP ""
توجه داشته باشید که
.B onsgmls
هرگز علامت "|" را خروجی نمی‌دهد (با این حال می‌تواند به صورت اختیاری سطری شامل یک حرف "e" درست پیش از سطر "(" درج کند تا خالی بودن عنصر را مشخص نماید).
.TP
text
متن معمولی به این شکل در خروجی نمایش داده می‌شود:
.d
\-text
.e
یعنی به صورت یک سطر منفرد که با "\-" آغاز می‌شود. متن موجود همانند کامنت‌ها اسکیپ می‌شود (به بالا مراجعه کنید).
.TP
line numbers
هنگامی که گزینه
.B \-l
فعال باشد،
.B hxpipe
خطوطی به شکل زیر را در میان خروجی درج می‌کند:
.d
L12
.e
که در آن "12" با شماره سطر منبع که خروجی بعدی از آن آمده است جایگزین می‌شود.
.LP
دستور
.B hxpipe
ورودی را تنها از این جهت نرمال‌سازی می‌کند که ویژگی‌ها را با ترتیبی ثابت (به ترتیب الفبایی، اما مستقل از محلی‌سازی/Locale) خروجی می‌دهد. این برنامه فایل DTD را نمی‌خواند، بنابراین فاصله‌های خالی اضافی را حذف نمی‌کند و نمی‌تواند ویژگی‌های ضمنی (Implied) را اضافه کند. همچنین موجودیت‌های کاراکتری را بسط نمی‌دهد (هرچند می‌توانید ورودی را ابتدا از طریق
.B hxunent
پایپ کنید). این ابزار تگ‌های ضمنی را نیز اضافه نمی‌کند (مگر با استفاده از گزینه
.BR \-H ).
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر پشتیبانی می‌شوند:
.TP 10
.B \-l
افزودن سطرهای "L" به خروجی برای نشان دادن شماره سطرها در فایل منبع. در حال حاضر این گزینه همزمان با گزینه
.B \-H
کار نمی‌کند.
.TP
.B \-H
اعمال قواعد ویژه برای HTML. در حالت عادی،
.B hxpipe
ورودی را به عنوان یک فایل ساختاریافته معتبر (Well-formed) XML در نظر می‌گیرد. با فعال‌سازی این گزینه،
.B hxpipe
ورودی را HTML فرض کرده و تگ‌های ضمنی را اضافه می‌کند، عناصر خالی را تشخیص می‌دهد و محتوای تگ‌های <script> و <style> را به عنوان متن خام پردازش می‌نماید.
.SH "عملوندها (OPERANDS)"
عملوند زیر پشتیبانی می‌شود:
.TP 10
.I file-or-URL
نام یا نشانی اینترنتی (URL) فایل HTML. در صورت عدم درج، ورودی استاندارد (Standard input) خوانده می‌شود.
.SH "وضعیت خروج (EXIT STATUS)"
مقادیر خروج زیر بازگردانده می‌شوند:
.TP 10
.B 0
پایان موفقیت‌آمیز عملیات.
.TP
.B > 0
خطایی در تجزیه فایل HTML رخ داده است.
.B hxpipe
تلاش خواهد کرد خطا را اصلاح کرده و در هر صورت خروجی را تولید کند.
.SH "محیط (ENVIRONMENT)"
برای استفاده از پراکسی جهت دریافت فایل‌های از راه دور، متغیرهای محیطی
.B http_proxy
و
.B ftp_proxy
را تنظیم کنید. برای مثال:
.PP
.B http_proxy="http://localhost:8080"
.SH "اشکالات (BUGS)"
.LP
بازیابی و مدیریت خطا برای اسناد نامعتبر HTML بسیار ابتدایی است.
.LP
در حال حاضر
.B hxpipe
تنها می‌تواند فایل‌های از راه دور را از طریق پروتکل HTTP دریافت کند. این ابزار از فایل‌های دارای گذرواژه محافظت‌شده یا فایل‌هایی که محتوای آن‌ها به کوکی‌های HTTP وابسته است پشتیبانی نمی‌کند.
.LP
گزینه
.B \-l
باید برای ورودی‌های HTML (گزینه
.BR \-H )
نیز کار کند.
.SH "همچنین ببینید (SEE ALSO)"
.BR hxunpipe (1),
.BR hxunent (1),
.BR onsgmls (1).