نام (NAME)

openjade - اعمال یک شیوه‌نامهٔ DSSSL روی یک سند SGML یا XML

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

openjade [-vCegG2s] [-b encoding] [-f error_file]
         [-c catalog_sysid] [-D dir] [-a link_type]
         [-A arch] [-E max_errors] [-i entity]
         [-w warning_type] [-d dsssl_spec] [-V variable=value]
         [-t output_type] [-o output_file] [sysid...]

توضیحات (DESCRIPTION)

دستور openjade یک پیاده‌سازی از زبان استاندارد DSSSL بر اساس ISO/IEC 10179:1996 است. موتور DSSSL یک سند SGML یا XML را به‌عنوان ورودی دریافت کرده و آن را به قالب‌هایی مانند موارد زیر تبدیل می‌کند:

* بازنمایی XML از درخت شیء جاری (flow object tree).

* قالب RTF که می‌تواند با نرم‌افزار رایگان Word Viewer 97 مایکروسافت نمایش داده شده و چاپ شود.

* قالب TeX

* قالب MIF که می‌تواند با Framemaker نمایش داده شده و چاپ شود.

* قالب SGML یا XML. این مورد در ترکیب با کلاس‌های غیر استاندارد flow object برای تولید SGML به کار می‌رود و در نتیجه امکان استفاده از openjade را برای تبدیل‌های SGML/XML فراهم می‌کند.

شناسهٔ سیستمی سندی که باید پردازش شود، به‌عنوان یک آرگومان به openjade داده می‌شود. اگر این آرگومان حذف شود، ورودی استاندارد خوانده خواهد شد.

برنامهٔ openjade شناسهٔ سیستمی مشخصات DSSSL را به‌صورت زیر تعیین می‌کند:

۱. اگر گزینهٔ -d مشخص شده باشد، از آرگومان آن به‌عنوان شناسهٔ سیستمی استفاده خواهد کرد.

۲. در غیر این صورت، در مقدمه (prolog) سند به‌دنبال دستورالعمل‌های پردازشی (processing instructions) می‌گردد. دو نوع دستورالعمل پردازشی شناخته می‌شود:

<?stylesheet href="sysid" type="text/dsssl">

داده‌های سیستمیِ دستورالعمل پردازشی مانند یک تگ آغازین SGML تجزیه می‌شوند. این داده‌ها صرف‌نظر از نحو عینی واقعی سند، با استفاده از نحو عینی مرجع (reference concrete syntax) تجزیه خواهند شد. نامی که دستورالعمل پردازشی با آن آغاز می‌شود می‌تواند stylesheet، xml-stylesheet یا xml:stylesheet باشد. دستورالعمل پردازشی نادیده گرفته خواهد شد مگر اینکه مقدار ویژگی type یکی از موارد text/dsssl، text/x-dsssl، application/dsssl یا application/x-dsssl باشد. مقدار ویژگی href شناسهٔ سیستمی مشخصات DSSSL است.

<?dsssl sysid>

شناسهٔ سیستمی، بخشی از داده‌های سیستمی دستورالعمل پردازشی است که پس از نام اولیه و هرگونه فاصلهٔ خالی (whitespace) قرار می‌گیرد.

اگرچه دستورالعمل پردازشی تنها در مقدمه شناسایی می‌شود، لزومی ندارد حتماً درون موجودیت سند (document entity) قرار داشته باشد. برای نمونه، می‌تواند درون یک DTD قرار گیرد. شناسهٔ سیستمی نسبت به مکانی که دستورالعمل پردازشی در آن قرار دارد تفسیر خواهد شد.

۳. در غیر این صورت، از شناسهٔ سیستمی سند در حالی که پسوند آن به .dsl تغییر یافته است استفاده خواهد کرد.

یک سند مشخصات DSSSL می‌تواند حاوی بیش از یک style-specification باشد. اگر شناسهٔ سیستمی مشخصات DSSSL با id# همراه باشد، آنگاه openjade از مشخصات شیوه‌ای استفاده می‌کند که شناسهٔ یکتای آن id است. این رفتار هم با گزینهٔ -d و هم با دستورالعمل‌های پردازشی مجاز است.

مشخصات DSSSL باید یک سند SGML منطبق بر معماری DSSSL باشد. برای دیدن یک نمونه، به dsssl/demo.dsl مراجعه کنید.

برنامهٔ openjade افزون بر گزینه‌های معمولی OpenSP (به onsgmls(1) مراجعه کنید)، از گزینه‌های زیر نیز پشتیبانی می‌کند (توجه داشته باشید که تمام گزینه‌ها به حروف کوچک و بزرگ حساس هستند؛ برای نمونه -g و -G دو گزینهٔ متفاوت‌اند):

-d dsssl_spec

مشخص می‌کند که dsssl_spec شناسهٔ سیستمی مشخصات DSSSL مورد استفاده است.

-G

حالت اشکال‌زدایی (Debug mode). هنگامی که در ارزیابی یک عبارت خطایی رخ دهد، openjade یک ردگیری پشته (stack trace) را نمایش خواهد داد. توجه داشته باشید که این گزینه بهینه‌سازی فراخوانی انتهایی (tail-call optimization) را غیرفعال می‌کند.

-c filename

آرگومان‌های filename به‌جای موجودیت سند، فایل‌های کاتالوگ را مشخص می‌کنند. موجودیت سند توسط نخستین مدخل DOCUMENT در فایل‌های کاتالوگ مشخص می‌شود.

-s

حالت سازگاری سخت‌گیرانه (Strict compliance mode). در حال حاضر تنها اثر آن این است که jade از هیچ نام نویسهٔ از‌پیش‌تعریف‌شده، نگاشت‌های sdata-entity یا name-characters استفاده نمی‌کند. این ویژگی برای اطمینان از این‌که شیوه‌نامهٔ شما با سایر پیاده‌سازی‌های DSSSL سازگار و قابل‌حمل است و دقیقاً با مشخصات DSSSL مطابقت دارد، مفید است.

-t output_type

مقدار output_type نوع خروجی را به‌صورت زیر مشخص می‌کند:

fot بازنمایی XML از درخت شیء جاری (flow object tree)

rtf rtf-95 قالب RTF مایکروسافت (مورد استفاده در تبدیل‌های SGML/XML به RTF). گزینهٔ rtf-95 خروجی بهینه‌شده برای Word 95 به‌جای Word 97 تولید می‌کند.

tex قالب TeX (مورد استفاده در تبدیل‌های SGML/XML به TeX)

sgml sgml-raw قالب SGML (مورد استفاده در تبدیل‌های SGML/XML به SGML). گزینهٔ sgml-raw شکست خط (linebreak) درون تگ‌ها ایجاد نمی‌کند.

xml xml-raw قالب XML (مورد استفاده در تبدیل‌های SGML/XML به XML). گزینهٔ xml-raw شکست خط درون تگ‌ها ایجاد نمی‌کند.

html قالب HTML (مورد استفاده در تبدیل‌های SGML/XML به HTML)

mif قالب MIF (مورد استفاده در تبدیل‌های SGML/XML به MIF)

-o output_file

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

-V variable

این گزینه معادل اجرای (define variable #t) است، با این تفاوت که این تعریف نسبت به هر تعریفی از variable درون یک شیوه‌نامه اولویت خواهد داشت.

-V variable=value

این گزینه معادل اجرای (define variable "value") است، با این تفاوت که این تعریف نسبت به هر تعریفی از variable درون یک شیوه‌نامه اولویت خواهد داشت.

-V (define variable value)

این گزینه معادل اجرای (define variable value) است، با این تفاوت که این تعریف نسبت به هر تعریفی از variable درون یک شیوه‌نامه اولویت خواهد داشت. توجه داشته باشید که احتمالاً باید از سازوکار گریز (escaping) برای فاصله‌ها استفاده کنید تا کل عبارت Scheme به‌عنوان یک آرگومان خط فرمان پردازش شود.

-wtype

کنترل هشدارها و خطاها. استفاده از چند گزینهٔ -w مجاز است. مقادیر زیر برای type هشدارها را فعال می‌کنند:

xml هشدار دربارهٔ ساختارهایی که توسط XML مجاز دانسته نمی‌شوند.

mixed هشدار دربارهٔ مدل‌های محتوای مختلط (mixed content models) که اجازهٔ استفاده از pcdata# را در هیچ نقطه‌ای نمی‌دهند.

sgmldecl هشدار دربارهٔ ساختارهای مشکوک و مبهم گوناگون در اعلان SGML.

should هشدار دربارهٔ توصیه‌های مختلف ISO 8879 که سند از آن‌ها پیروی نکرده است. (توصیه‌ها با عبارت «should» بیان شده‌اند، برخلاف الزامات که معمولاً با «shall» مشخص می‌شوند).

default هشدار دربارهٔ ارجاعات پیش‌فرض‌شده (defaulted references).

duplicate هشدار دربارهٔ اعلان‌های موجودیت تکراری.

undefined هشدار دربارهٔ عنصرهای تعریف‌نشده: عنصرهایی که در DTD به کار رفته‌اند اما تعریف نشده‌اند.

unclosed هشدار دربارهٔ تگ‌های آغازین و پایانی بسته‌نشده.

empty هشدار دربارهٔ تگ‌های آغازین و پایانی خالی.

net هشدار دربارهٔ تگ‌های آغازین فعال‌کنندهٔ net و تگ‌های پایانی تهی (null).

min-tag هشدار دربارهٔ تگ‌های آغازین و پایانی کوتاه‌شده (minimized). این گزینه معادل ترکیبی از هشدارهای unclosed، empty و net است.

unused-map هشدار دربارهٔ نقشه‌های ارجاع کوتاه استفاده‌نشده: نقشه‌هایی که با یک اعلان نگاشت ارجاع کوتاه تعریف شده‌اند اما هرگز در اعلان استفاده از ارجاع کوتاه در DTD به کار نرفته‌اند.

unused-param هشدار دربارهٔ موجودیت‌های پارامتری که تعریف شده‌اند اما در DTD استفاده نشده‌اند. موجودیت‌های پارامتری درونی استفاده‌نشده که مقدار متن آن‌ها INCLUDE یا IGNORE باشد این هشدار را دریافت نمی‌کنند.

notation-sysid هشدار دربارهٔ نشانه‌گذاری‌هایی (notations) که هیچ شناسهٔ سیستمی برای آن‌ها قابل تولید نبود.

all هشدار دربارهٔ شرایطی که معمولاً (به نظر نویسنده) باید از آن‌ها اجتناب شود. معادل با: mixed، should، default، undefined، sgmldecl، unused-map، unused-param، empty و unclosed.

یک هشدار را می‌توان با آوردن نام آن پس از پیشوند -no غیرفعال کرد؛ بنابراین -wall -wno-duplicate تمام هشدارها را به جز هشدارهای مربوط به اعلان‌های موجودیت تکراری فعال می‌کند.

مقادیر زیر برای warning_type خطاها را غیرفعال می‌کنند:

no-idref برای مقدار ارجاع ID که هیچ عنصری آن را به‌عنوان ID خود ندارد، خطایی صادر نشود. اثر این گزینه به‌گونه‌ای خواهد بود که گویی هر ویژگیِ اعلان‌شده به‌عنوان مقدار ارجاع ID، به‌صورت یک نام (name) اعلان شده است.

no-significant هنگامی که نویسه‌ای که در نحو عینی مرجع یک نویسهٔ معنی‌دار (significant character) نیست در یک رشته در اعلان SGML رخ می‌دهد، خطایی صادر نشود. این گزینه ممکن است همراه با برخی مجموعه‌های آزمایشی دارای باگ مفید باشد.

no-valid الزام معتبر بودن نوع سند (type-valid) را برمی‌دارد. اثر این کار تغییر اعلان SGML به مشخص کردن VALIDITY NOASSERT و IMPLYDEF ATTLIST YES ELEMENT YES است. گزینهٔ -wvalid باعث تغییر اعلان SGML به VALIDITY TYPE و IMPLYDEF ATTLIST NO ELEMENT NO می‌شود. اگر هیچ‌یک از گزینه‌های -wvalid یا -wno-valid مشخص نشوند، مقادیر VALIDITY و IMPLYDEF مشخص‌شده در اعلان SGML استفاده خواهند شد..SH "محیط (ENVIRONMENT)"

برنامه OpenJade متغیرهای محیطی SP_CHARSET_FIXED و SP_SYSTEM_CHARSET را نادیده می‌گیرد و همیشه از Unicode به‌عنوان مجموعه نویسه‌های داخلی خود استفاده می‌کند، گویی که SP_CHARSET_FIXED برابر با 1 بوده و SP_SYSTEM_CHARSET تنظیم نشده است. بنابراین تنها متغیر محیطی SP_ENCODING به نحوه مدیریت مجموعه‌های نویسه در OpenJade مربوط می‌شود.

افزونه‌های OPENJADE (OPENJADE EXTENSIONS)

رویه‌های خارجی زیر در دسترس هستند. این رویه‌های خارجی توسط یک پیش‌نمونه (prototype) به همان شیوه‌ای که در استاندارد آمده است، تعریف می‌شوند. برای استفاده از یکی از این رویه‌های خارجی، باید از رویه استاندارد external-procedure با استفاده از شناسه عمومی "UNREGISTERED::James Clark//Procedure::name" استفاده کنید که در آن name نام ارائه‌شده در اینجا است؛ معمولاً با گنجاندن عبارت زیر در مشخصات DSSSL:

(define name (external-procedure "UNREGISTERED::James Clark//Procedure::name"))

توجه داشته باشید که اگر external-procedure شناسه عمومی مشخص‌شده را نشناسد، مقدار #f را برمی‌گرداند. می‌توانید از این قابلیت استفاده کنید تا مشخصات DSSSL شما بتوانند با سایر پیاده‌سازی‌هایی که از این افزونه‌ها پشتیبانی نمی‌کنند نیز به خوبی کار کنند.

برای رویه‌های خارجی اضافه‌شده توسط تیم OpenJade، از شناسه عمومی با قالب "UNREGISTERED::OpenJade//Procedure::name" استفاده کنید.

یک راه ساده برای دستیابی به تمام رویه‌های خارجی، استفاده از مشخصات سبک dsssl/extensions.dsl#procedures است. فایل dsssl/extensions.dsl همچنین شامل مشخصات سبکی است که کلاس‌های شیء جریان غیراستاندارد و مشخصه‌های موروثی پشتیبانی‌شده توسط بک‌اندها را به روشی راحت در دسترس قرار می‌دهد.

اشکال‌زدایی

(debug obj)

پیامی شامل مقدار obj تولید می‌کند و سپس obj را بازمی‌گرداند.

کنترل سرصفحه/پاورقی simple-page-sequence

(if-first-page sosofo1 sosofo2)

این مورد فقط می‌تواند در تعیین مقدار یکی از مشخصه‌های سرصفحه/پاورقی simple-page-sequence استفاده شود. این رویه یک sosofo برمی‌گرداند که در صورت بودن صفحه در اولین صفحه از simple-page-sequence به عنوان sosofo1 و در غیر این صورت به عنوان sosofo2 نمایش داده می‌شود.

(if-front-page sosofo1 sosofo2)

این مورد فقط می‌تواند در تعیین مقدار یکی از مشخصه‌های سرصفحه/پاورقی simple-page-sequence استفاده شود. این رویه یک sosofo برمی‌گرداند که اگر صفحه رویی (یعنی recto، شماره‌فرد) باشد به عنوان sosofo1 و اگر صفحه پشت (یعنی verso، شماره‌زوج) باشد به عنوان sosofo2 نمایش داده خواهد شد.

شماره‌گذاری

(all-element-number)

(all-element-number osnl)

این رویه مشابه element-number است به جز اینکه عناصر را با هر شناسه عمومی شمارش می‌کند. اگر osnl یک عنصر نباشد مقدار #f را برمی‌گرداند، در غیر این صورت مقدار ۱ به علاوه تعداد عناصری که پیش از osnl شروع شده‌اند را برمی‌گرداند. این روشی کارآمد برای ساخت یک شناسه یکتا برای هر عنصری در یک سند فراهم می‌کند.

دسترسی به نهاد خارجی

(read-entity string)

این رویه یک رشته شامل محتویات نهاد خارجی با شناسه سیستمی string را بازمی‌گرداند. این باید فقط برای نهادهای متنی (CDATA و SDATA) استفاده شود و نه برای نهادهای دودویی (NDATA).

دسترسی به محلی‌سازی POSIX

(language lang country)

این رویه در صورتی که سیستم از زبان مشخص‌شده پشتیبانی کند، یک شیء از نوع language برمی‌گرداند. پارامتر lang یک رشته یا نماد است که کد زبان دو حرفی را ارائه می‌دهد. پارامتر country یک رشته یا نماد است که کد کشور دو حرفی را ارائه می‌دهد.

این رویه از لوکال‌های POSIX استفاده می‌کند. این یک افزونه OpenJade است و در همه سیستم‌عامل‌ها پشتیبانی نمی‌شود.

رویه‌های استاندارد گسترش‌یافته

(sgml-parse sysid #!key active: parent: architecture:)

این رویه به شما امکان می‌دهد تا معماری SGML را مشخص کنید که سند باید با توجه به آن تجزیه شود. این یک افزونه OpenJade است.

(expt q k)

این رویه به شما امکان می‌دهد تا یک کمیت را به یک توان صحیح برسانید. این یک افزونه OpenJade است..SH "محدودیت‌ها (LIMITATIONS)"

این بخش محدودیت‌های فرانت‌اند (موتور همه‌منظوره DSSSL) را شرح می‌دهد؛ هر بک‌اند (backend) نیز محدودیت‌های خاص خود را دارد.

برنامه openjade تعریف‌های داخلی در ابتدای بدنه و حالت (test => recipient) در عبارت‌های cond را مجاز نمی‌داند.

برنامه openjade تنها از یک طرح بیشه (grove plan) ثابت و واحد پشتیبانی می‌کند که شامل ماژول‌های زیر است:

* baseabs

* prlgabs0

* prlgabs1

* instabs

* basesds0

* instsds0

* subdcabs

این برنامه بخش‌های زیر از SDQL را پیاده‌سازی نمی‌کند: پشتیبانی از HyTime، تجزیه کمکی (auxiliary parsing)، عبارت‌های باقاعده گره (node regular expressions).

قواعد پرس‌وجو (Query rules)، همگام‌سازی sosofo، شیءهای sosofo غیرمستقیم، مقادیر مرجع (reference values)، ناحیه‌های تزیین (decoration areas) و ویژگی‌های قلم (font properties) پشتیبانی نمی‌شوند.

توجه داشته باشید که تنها ویژگی‌های موروثی (inherited characteristics) که برای برخی از شیءهای جریان (flow objects) پشتیبانی‌شده قابل اعمال هستند، می‌توانند مشخص شوند.

مدیریت نویسه/گلیف (Character/glyph handling)

این برنامه تنها از یک مجموعه نویسه (character repertoire) از پیش تعریف‌شده پشتیبانی می‌کند. نام نویسه‌ای به فرم U-XXXX که در آن XXXX چهار رقم هگزادسیمال بزرگ است، به عنوان اشاره به نویسه یونیکد با آن کد شناسایی می‌شود. برای بسیاری از نویسه‌ها، استفاده از نام ISO/IEC 10646 با حروف کوچک به همراه کلمات جداشده با خط تیره نیز امکان‌پذیر است.

برخی از نام‌های موجودیت SDATA رایج از مجموعه‌های موجودیت ISO شناسایی شده و به نویسه‌ها نگاشت می‌شوند. علاوه بر این، نام موجودیت SDATA به فرم U-XXXX، که در آن XXXX چهار رقم هگزادسیمال بزرگ است، به نویسه یونیکد با آن کد نگاشت می‌گردد.

اکنون OpenJade از فرم‌های عناصر اعلانی standard-chars، map-sdata-entity، add-name-chars، add-separator-chars و char-repertoire پشتیبانی می‌کند که به شیوه‌نامه (style-sheet) اجازه می‌دهد نام‌های نویسه اضافی، نگاشت‌های موجودیت sdata، نویسه‌های نام (یعنی نویسه‌های مجاز در شناسه‌ها) و نویسه‌های جداکننده را تعریف کند. در حال حاضر تنها مجموعه نویسه شناخته‌شده، مجموعه داخلی (built-in) است. این مجموعه دارای شناسه عمومی "UNREGISTERED::OpenJade//Character Repertoire::OpenJade" است.

اعتبارسنجی (Validation)

موارد متعددی که مطلوب است بررسی شوند، بررسی نمی‌شوند:

* هنگامی که مقدار مجاز یک ویژگی موروثی یک نماد (symbol) است، OpenJade تنها بررسی می‌کند که آن مقدار نمادی مجاز به عنوان مقدار برخی از ویژگی‌ها باشد؛ در این حالت با #t و #f مانند نوع خاصی از نماد رفتار می‌شود.

* برنامه OpenJade بررسی نمی‌کند که آیا یک شیء جریان در زمینه‌ای که مجاز است رخ داده است یا خیر.

* برنامه OpenJade از پیوست شدن شیءهای جریان به درگاه اصلی (principal port) یک شیء جریان دیگر، هنگامی که آن شیء نباید درگاه اصلی داشته باشد، جلوگیری نمی‌کند.

* بیشتر بررسی‌های نوع (type-checking) در زمان اجرا انجام می‌شوند، نه در زمان کامپایل.

* برنامه OpenJade ویژگی‌های غیرموروثی که تعیین آن‌ها الزامی است را بررسی نمی‌کند.

* این برنامه بررسی نمی‌کند که آیا ویژگی‌های اختیاری استفاده‌شده در فرم ویژگی‌ها (features form) اعلان شده‌اند یا خیر.

سایر محدودیت‌ها

توابع اولیه (primitives) زیر صرفاً ساختگی (stub) هستند:

char-script-case همیشه آخرین آرگومان را برمی‌گرداند.

address-visited? همیشه #f را برمی‌گرداند..SH "مثال‌ها (EXAMPLES)"

با داشتن یک فایل SGML به نام file.sgml، از شیوه‌نامهٔ file.dsl استفاده کرده و خروجی را در قالب یک فایل rtf منتشر کنید:

openjade -t rtf file.sgml

استفاده از یک شیوه‌نامهٔ متفاوت:

openjade -t rtf -d docbook.dsl file.sgml

استفاده از مشخصهٔ سبک print موجود در شیوه‌نامه:

openjade -t rtf -d docbook.dsl#print file.sgml

و استفاده از مشخصهٔ html موجود در شیوه‌نامه برای تبدیل به html:

openjade -t sgml -i html -d docbook.dsl#html file.sgml

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

onsgmls(1)

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

James Clark, Ian Castle <ian.castle@looksystems.co.uk>.