Вперед Назад

Используя комплект MPGL

В дополнение к основному headerdoc2html и gatherheaderdoc сценарии, комплект HeaderDoc содержит дополнительные утилиты для генерации страниц руководства (использующий mdoc макро-набор).

Комплект Man Page Generation Language (MPGL) содержит две утилиты: xml2man и hdxml2manxml. xml2man утилита преобразовывает подобный mdoc диалект XML, Man Page Generation Language (MPGL) в страницы руководства. hdxml2manxml утилита преобразовывает вывод HeaderDoc XML в серию файлов, которые могут тогда быть обработаны с помощью xml2man.

Обе команды имеют очень простой синтаксис. Никакой взятия любые параметры.

hdxml2manxml filename1 filename2 ... filenameN

xml2man inputfile.mxml [ outputfile.1 ]

В случае xml2man, выходное имя файла обычно оставляется незаполненное.

Остаток от этой главы описывает диалект XML, используемый этими утилитами.

Диалект Man Page Generation Language (MPGL)

В этом разделе описываются базовый синтаксис Man Page Generation Language (MPGL). Части синтаксиса сокращены вследствие сложности. Для получения информации об этих подробных данных посмотрите примеры далее в этой главе.

Синтаксис MPGL включает подмножество mdoc. Весь текст невыровнен, и некоторая избыточность была сокращена. В частности usage раздел в файле MPGL предоставляет исходную информацию и для SYNOPSIS и для разделов OPTIONS традиционной страницы справочника. Вне тех изменений, если Вы знакомы с mdoc макро-набором, необходимо чувствовать себя хорошо дома.

На верхнем уровне (во внешнем <manpage> тег), страница MPGL состоит из некоторых или всех следующих больших блоков:

**Таблица 5-1** метки блока MPGL
Метка блока	Описание
`<docdate>`	Последняя измененная дата страницы руководства.
`<description>`	Описание технологии в целом. Это - первый главный раздел получающейся страницы руководства.
`<doctitle>`	Заголовок страницы руководства.
`<os>`	Операционная система, для которой была записана страница руководства.
`<section>`	Раздел человека, в котором должны появиться страницы руководства.
`<names>`	Имена и описания функций или инструментов, описанных в этой странице руководства (см. пример для синтаксиса).
`<usage>`	Использование командной строки или параметры функции (см. пример для синтаксиса).
`<returnvalues>`	Функциональное возвращаемое значение (текстовое описание).
`<environment>`	Взаимодействие с переменными окружения.
`<files>`	Файлы используются инструментом командной строки.
`<examples>`	Примеры использования.
`<diagnostics>`	Поиск и устранение неисправностей информации.
`<errors>`	Функциональные ошибочные значения (обычно ограничиваемый возвращенными через `errno` глобальная переменная).
`<seealso>`	Перекрестные ссылки на другие страницы руководства (см. пример).
`<conformingto>`	Стандарты, которым соответствуют инструмент или функция.
`<history>`	Историческая информация.
`<bugs>`	Известные ошибки в инструменте или функции.

Любое поле может содержать или блок необработанного текста или следующее подмножество XHTML:

**Таблица 5-2** теги XHTML поддерживается MPGL
Тег XHTML	Описание
`<p>`	абзац
`<blockquote>`	блок с отступом
`<tt>`	буквенный текст с отступом или код
`<ul>`	неупорядоченный (маркируют) список
`<ol>`	упорядоченный (пронумерованный) список
`<li>`	элемент списка (в списке)
`<code>`	буквенный текст
`<dl>`	срок и список определения
`<dt>`	срок (в сроке и списке определения)
`<dd>`	определение (в сроке и списке определения)

Любое поле может также содержать любой из следующих MPGL-специфичных встроенных тегов:

**Таблица 5-3** Дополнительные MPGL-специфичные встроенные теги
Тег	Описание
`<path>`	путь
`<function>`	имя функции
`<command>`	название команды
`<manpage>`	перекрестная ссылка страницы справочника (см. пример),

Простой функциональный пример

Перечисление 5-1 является примером того, как записать страницу руководства MPGL для функции.

Перечисление 5-1 простой пример MPGL для функции

<manpage>

<docdate>August 28, 2002</docdate>

<doctitle>Document title</doctitle>

<os>OS X</os>

<section>3</section>

<names>

        <name>foo<desc>This is foo's description</desc></name>

        <name>bar<desc>This is bar's description</desc></name>

</names>

<usage>

        <func><type>int</type><name>foo</name>

            <arg>int k<desc>This is a k.</desc></arg>

            <arg>char *b<desc>This is a b.</desc></arg>

        </func>

</usage>

<returnvalues>

        <p>Returns kIONotANumber if you can't count.</p>

        <p>Returns kIOMoron this if you REALLY can't count.</p>

</returnvalues>

<environment>

        TEXT

</environment>

<files>

        <file>/path/to/filename<desc>This is a waste of time</desc></file>

        <file>/path/to/another/filename<desc>This is also a waste of time</desc></file>

</files>

<examples>

        TEXT

</examples>

<diagnostics>

        TEXT

</diagnostics>

<errors>

        TEXT

</errors>

<seealso>

        <p>This is a text container, really, but generally contains

        lines like this:</p>

        <manpage>foo<section>1</section>, </manpage>

        <manpage>bar<section>3</section></manpage>

</seealso>

<conformingto>

        <p>Here's a list of conformance:</p>

        <ul>

            <li>Single UNIX Specification</li>

            <li>POSIX</li>

        </ul>

</conformingto>

<history>

        TEXT

</history>

<bugs>

        <p>Here are some bugs:</p>

<p>

        <ol>

                <li>Bug one....</li>

                <li>Bug two....</li>

                <li>Bug three....</li>

        </ol>

        </p>

        <p>I think that pretty much covers it.</p>

</bugs>

</manpage>

Простой пример команды

Перечисление 5-2 является примером того, как записать страницу руководства MPGL для единственной команды или ряда команд с тем же синтаксисом.

Перечисление 5-2 простой пример MPGL для команды

<manpage>

<docdate>August 28, 2002</docdate>

<doctitle>Document title</doctitle>

<os>Darwin</os>

<section>1</section>

<names>

        <name>foo<desc>this is a description</desc></name>

        <name>bar<desc>this is also a description</desc></name>

</names>

<usage>

        <flag optional="1">a<arg>attributes</arg><desc>This is the atts flag</desc></flag>

        <flag>d<arg>date</arg><desc>This is the date flag</desc></flag>

        <flag>x<desc>This is the -x flag</desc></flag>

        <arg>filename<desc>This is the filename</desc></arg>

</usage>

<returnvalues>

        <p>Returns kIONotANumber if you can't count.</p>

        <p>Returns kIOMoron if you REALLY can't count.</p>

</returnvalues>

<environment>

        TEXT

</environment>

<files>

        <file>/path/to/filename<desc>This is a waste of time</desc></file>

        <file>/path/to/another/filename<desc>This is also a waste of time</desc></file>

</files>

<examples>

        TEXT

</examples>

<diagnostics>

        TEXT

</diagnostics>

<errors>

        TEXT

</errors>

<seealso>

        <p>This is a text container, really, but generally contains

        lines like this:</p>

        <manpage>foo<section>1</section>, </manpage>

        <manpage>bar<section>3</section></manpage>

</seealso>

<conformingto>

        <p>Here's a list of conformance:</p>

        <ul>

            <li>Single UNIX Specification</li>

            <li>POSIX</li>

        </ul>

        <p>Here's a definition list:</p>

        <dl>

            <dd>foo_aaa</dd>

                <dt>This is foo</dt>

            <dd>bar</dd>

                <dt>This is bar</dt>

        </dl>

</conformingto>

<history>

        This program should be history....

</history>

<bugs>

        <p>Here are some bugs:</p>

<p>

        <ol>

                <li>Bug one....</li>

                <li>Bug two....</li>

                <li>Bug three....</li>

        </ol>

        </p>

        <p>I think that pretty much covers it.</p>

</bugs>

</manpage>

Пример мультикоманды

Перечисление 5-3 является примером того, как записать страницу руководства MPGL для многократных команд на единственной странице.

Перечисление 5-3 пример MPGL для многократных команд

<manpage>

<docdate>August 28, 2002</docdate>

<doctitle>Document title</doctitle>

<os>Darwin</os>

<section>1</section>

<names>

        <name>hdxml2manxml<desc>HeaderDoc XML to MPGL translator</desc></name>

        <name>xml2man<desc>MPGL to mdoc (man page) translator</desc></name>

        <name>examplemc<desc>MPGL to mdoc (man page) translator</desc></name>

</names>

<usage>

        <command name="hdxml2manxml">

                <arg>filename [ filename ... ]<desc>the filename(s) to be processed</desc></arg>

        </command>

        <command name="xml2man">

                <arg>filename<desc>This is the filename</desc></arg>

                <arg optional="1">output_filename<desc>This is the filename</desc></arg>

        </command>

        <command name="example">

                <arg>filename<desc>This is the filename</desc></arg>

                <arg optional="1">output_filename<desc>This is the filename</desc></arg>

        </command>

        <command name="example">

                <arg>filename [ filename ... ]<desc>the filename(s) to be processed</desc></arg>

                <flag optional="1">c<arg>time_to</arg><arg optional="1">crash</arg><desc>Seems like a useful flag</desc></flag>

        </command>

</usage>

<environment>

        <p>The <name>xml2man</name> program was designed to convert Man Page

        Generation Language (MPGL) XML files into mdoc-based manual pages.

        The MPGL is a fairly direct translation of mdoc to XML.</p>

        <p>The <name>hdxml2manxml</name> tool was designed to translate

        from headerdoc's XML output to an mxml file for use with xml2man.</p>

</environment>

<seealso>

        <p>For more information on xml2man, see</p>

        <manpage>xml2man<section>1</section>, </manpage>

        <manpage>hdxml2manxml<section>1</section>, </manpage>

</seealso>

</manpage>

Вперед Назад