.\" Copyright (c) 2002 Bill C. Riemers
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" GNU General Public License, either Version 2 of the license,
.\" or (at your option) any later version. The license should have
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual. Otherwise check the web site
.\" of the Free Software Foundation at http://www.fsf.org.
.\"
.\" I, Bill C. Riemers, hereby grant all rights to this code,
.\" provided usage complies with the GPL or a written exception to
.\" the GPL granted by any of Bill C. Riemers, Leon Bottou,
.\" Yann Le Cun, or the Free Source Foundation.
.\"
.\" ------------------------------------------------------------------
.\" DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
.\" Lizardtech Software.  Lizardtech Software has authorized us to
.\" replace the original DjVu(r) Reference Library notice by the following
.\" text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
.\"
.\"  ------------------------------------------------------------------
.\" | DjVu (r) Reference Library (v. 3.5)
.\" | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
.\" | The DjVu Reference Library is protected by U.S. Pat. No.
.\" | 6,058,214 and patents pending.
.\" |
.\" | This software is subject to, and may be distributed under, the
.\" | GNU General Public License, either Version 2 of the license,
.\" | or (at your option) any later version. The license should have
.\" | accompanied the software or you may obtain a copy of the license
.\" | from the Free Software Foundation at http://www.fsf.org.
.\" |
.\" | The computer code originally released by LizardTech under this
.\" | license and unmodified by other parties is deemed "the LIZARDTECH
.\" | ORIGINAL CODE."  Subject to any third party intellectual property
.\" | claims, LizardTech grants recipient a worldwide, royalty-free,
.\" | non-exclusive license to make, use, sell, or otherwise dispose of
.\" | the LIZARDTECH ORIGINAL CODE or of programs derived from the
.\" | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU
.\" | General Public License.   This grant only confers the right to
.\" | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to
.\" | the extent such infringement is reasonably necessary to enable
.\" | recipient to make, have made, practice, sell, or otherwise dispose
.\" | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to
.\" | any greater extent that may be necessary to utilize further
.\" | modifications or combinations.
.\" |
.\" | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
.\" | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
.\" | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
.\" | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\" +------------------------------------------------------------------
.TH DJVUTOXML 1 "15 نوامبر 2002" "DjVuLibre XML Tools" "راهنمای ابزارهای کاربردی"
.de SS
.SH \\0\\0\\0\\$*
..
.SH "نام (NAME)"
djvutoxml \- استخراج فراداده، پیوندها و متن‌های پنهان پرونده‌های DjVu در قالب XML

.SH "خلاصه دستور (SYNOPSIS)"
.BI "djvutoxml [" "گزینه‌ها" "] " "inputdjvufile" " [" "outputxmlfile" "]"
.br
.BI "djvuxmlparser [ -o " "djvufile" " ] " "inputxmlfile"

.SH "توضیحات (DESCRIPTION)"
ابزارهای XML برای DjVuLibre امکان ویرایش فراداده‌ها، پیوندها و متن پنهان مرتبط با پرونده‌های DjVu را فراهم می‌کنند. بر خلاف
.BR djvused (1)
ابزارهای XML برای DjVuLibre بر فناوری XML تکیه دارند و می‌توانند از مزایای ویرایشگرها و اعتبارسنج‌های XML بهره ببرند.

.SH DJVUTOXML
برنامه
.B djvutoxml
یک پروندهٔ XML با نام
.I outputxmlfile
ایجاد می‌کند که حاوی ارجاع به سند اصلی DjVu
.RI ( inputdjvufile )
و همچنین برچسب‌هایی است که فراداده، پیوندها و متن پنهان مرتبط با پروندهٔ DjVu را توصیف می‌کنند.
.PP
گزینه‌های زیر پشتیبانی می‌شوند:
.TP
.BI "--page " "pagenum"
انتخاب یک صفحه در یک سند چندصفحه‌ای.
بدون این گزینه،
.B djvutoxml
خروجی XML مربوط به تمام صفحات سند را تولید می‌کند.
.TP
.BI "--with-text"
مشخص می‌کند که عنصر
.B HIDDENTEXT
برای هر صفحه باید در خروجی گنجانده شود.
اگر این گزینه بدون گزینهٔ
.B --with-anno
مشخص شود، گزینهٔ
.B --without-anno
به صورت ضمنی اعمال می‌شود. اگر هیچ‌یک از گزینه‌های
.BR --with-text ،
.BR --without-text ،
.B --with-anno
یا
.B --without-anno
مشخص نشوند، گزینه‌های
.B --with-text
و
.B --with-anno
به صورت ضمنی در نظر گرفته می‌شوند.
.TP
.BI "--without-text"
مشخص می‌کند که عنصر
.B HIDDENTEXT
برای هیچ صفحه‌ای در خروجی قرار نگیرد. اگر بدون گزینهٔ
.B --without-anno
مشخص شود، گزینهٔ
.B --with-anno
به صورت ضمنی اعمال می‌شود.
.TP
.BI "--with-anno"
مشخص می‌کند که عنصر ناحیهٔ
.B MAP
برای هر صفحه باید در خروجی گنجانده شود. اگر بدون گزینهٔ
.B --with-text
مشخص شود، گزینهٔ
.B --without-text
به صورت ضمنی اعمال می‌شود.
.TP
.BI "--without-anno"
مشخص می‌کند که عنصر ناحیهٔ
.B MAP
برای هیچ صفحه‌ای در خروجی قرار نگیرد. اگر بدون گزینهٔ
.B --without-text
مشخص شود، گزینهٔ
.B --with-text
به صورت ضمنی اعمال می‌شود.

.SH DJVUXMLPARSER
پرونده‌های تولیدشده توسط
.B djvutoxml
را می‌توان با استفاده از یک ویرایشگر متن یا ویرایشگر XML تغییر داد.
برنامه
.B djvuxmlparser
پروندهٔ XML ورودی
.I inputxmlfile
را به منظور اصلاح فراداده‌های پروندهٔ DjVu مربوطه تجزیه و پردازش می‌کند.
.TP
.BI "-o " "djvufile"
در اصل پروندهٔ مقصد DjVu پرونده‌ای است که توسط عنصر
.I OBJECT
در پروندهٔ XML به آن ارجاع داده شده است.
این گزینه امکان بازنویسی و تغییر نام پروندهٔ مشخص‌شده در عنصر
.I OBJECT
را فراهم می‌کند.

.SH "تعریف نوع سند (DJVUXML DOCUMENT TYPE DEFINITION)"
پروندهٔ تعریف نوع سند (DTD) در مسیر
.IP "" 2
.B /usr/share/djvu/pubtext/DjVuXML-s.dtd
.PP
ورودی و خروجی ابزارهای DjVu XML را تعریف می‌کند.
.PP
تعریف DTD با نام DjVuXML-s یک نسخهٔ ساده‌شده از DTD اچ‌تی‌ام‌ال است:
.IP "" 2
.B \%http://www.w3c.org/TR/1998/REC-html40-19980424/sgml/dtd.html
.PP
که چند ویژگی جدید مخصوص DjVu به آن افزوده شده است. هر یک از صفحات مشخص‌شده در سند DjVu به صورت عناصر
.B OBJECT
درون عنصر
.B BODY
پروندهٔ XML نمایش داده می‌شوند.
هر عنصر
.B OBJECT
ممکن است شامل چندین عنصر
.B PARAM
برای مشخص کردن ویژگی‌هایی مانند نام صفحه، وضوح تصویر (رزولوشن) و ضریب گاما باشد.
همچنین هر عنصر
.B OBJECT
می‌تواند شامل یک عنصر
.B HIDDENTEXT
باشد تا متن پنهان (که معمولاً توسط یک موتور OCR تولید می‌شود) درون صفحهٔ DjVu را مشخص کند. علاوه بر این، هر عنصر
.B OBJECT
می‌تواند به یک عنصر تک‌ناحیه‌ای
.B MAP
ارجاع دهد که شامل چندین عنصر
.B AREA
است تا تمامی نواحی پیوند و هایلایت درون سند DjVu را نشان دهد.
.SS "عناصر PARAM"
عناصر مجاز
.B PARAM
برای یک
.B OBJECT
در DjVu شامل موارد زیر می‌شوند (اما به آن‌ها محدود نیستند):
.B PAGE
برای تعیین نام صفحه،
.B GAMMA
برای تعیین ضریب تصحیح گاما (معمولاً 2.2)، و
.B DPI
برای تعیین وضوح تصویر صفحه (رزولوشن).
.SS "عناصر HIDDENTEXT"
عنصر
.B HIDDENTEXT
از عناصر تودرتوی
.BR PAGECOLUMNS ،
.BR REGION ،
.BR PARAGRAPH ،
.B LINE
و
.B WORD
تشکیل شده است. عمیق‌ترین عنصر مشخص‌شده باید مختصات کادر مرزی عنصر را با جهت‌گیری بالا به پایین مشخص کند. بدنهٔ عمیق‌ترین عنصر باید حاوی متن باشد. اکثر اسناد DjVu از
.B LINE
یا
.B WORD
به عنوان پایین‌ترین سطح عنصر استفاده می‌کنند، اما هر عنصری به عنوان پایین‌ترین سطح مجاز است. همیشه یک فاصله (فاصله‌گذاری) بین عناصر
.B WORD
و یک خط جدید (Line feed) بین عناصر
.B LINE
اضافه می‌شود. از آنجا که زبان‌هایی مانند ژاپنی از فاصله بین کلمات استفاده نمی‌کنند، برای موتورهای OCR آسیایی بسیار رایج است که از
.B WORD
به جای کاراکتر استفاده کنند.
.SS "عناصر MAP"
بدنهٔ عناصر
.B MAP
از عناصر
.B AREA
تشکیل شده است. علاوه بر ویژگی‌های فهرست‌شده در
.IP "" 2
.BR \%http://www.w3.org/TR/1998/REC-html40-19980424/struct/objects.html#edef-AREA ,
.PP
ویژگی‌های
.BR bordertype ،
.BR bordercolor ،
.B border
و
.B highlight
به ترتیب برای تعیین نوع کادر، رنگ کادر، عرض کادر و رنگ‌های برجسته‌سازی اضافه شده‌اند. مقادیر مجاز برای هر یک از این ویژگی‌ها در DTD با نام DjVuXML-s فهرست شده‌اند.
علاوه بر این، شکل
.B oval
به فهرست اشکال مجاز اضافه شده است. یک بیضی از یک کادر مرزی مستطیلی استفاده می‌کند.

.SH "اشکالات (BUGS)"
شاید بهتر بود به جای تعریف عنصر
.BR HIDDENTEXT ،
از شیوه‌نامه‌های CSS2 با عناصر استاندارد HTML استفاده می‌شد.

.SH "نویسندگان (AUTHORS)"
ابزارهای DjVu XML و DTD توسط
Bill C. Riemers <docbill@sourceforge.net>
و Fred Crary نوشته شده‌اند.

.SH "همچنین ببینید (SEE ALSO)"
.BR djvu (1),
.BR djvused (1),
.BR utf8 (7)