[devel] xml2man

[devel] xml2man

[Илья Евсеев]

  Всем привет!
В каком состоянии находятся XSL-стили для трансляции из DocBook в man?
В прошлом году дискуссия закончилась на том, что есть нечто криво-убогое
в самом DocBook и дополняющий его man.xsl в составе Самбы.
Соответственно, конкретных вопросов три:
1) перестал ли ./manpages/ в docbook-style-xsl-1.64.0-alt1 быть кривым?
   По моим ощущениям, сгенерированная им man-страница
   выглядит некачественно (см. dosbox-install в пакете dosbox).
   Если перестал, то пишет ли кто-нибудь man-страницы с его помощью?
   Если пишет, то в каких пакетах можно взглянуть на образцы?
2) Если ./manpages/ так и остался кривым, то опакечивал ли кто-нибудь man.xsl из Самбы?
3) Если не опакечивал и не собирается, то есть ли у нас XML packaging policy?
   В принципе, если заглянуть в пакеты alt-docs-xsl-*, всё ясно и без неё,
   но она бы, если дойдут руки, всяко не помешала.

С уважением,
Илья Евсеев

[devel] Re: xml2man

[Vitaly Ostanin]

[-- Attachment #1.1: Type: text/plain, Size: 1334 bytes --]

Илья Евсеев пишет:
>   Всем привет!
> В каком состоянии находятся XSL-стили для трансляции из DocBook в man?
> В прошлом году дискуссия закончилась на том, что есть нечто криво-убогое
> в самом DocBook и дополняющий его man.xsl в составе Самбы.

Я бы не назвал первые криво-убогими. Судя по тому, что самба в 
ман транслирует, то всё ок.

> Соответственно, конкретных вопросов три:
> 1) перестал ли ./manpages/ в docbook-style-xsl-1.64.0-alt1 быть кривым?
>    По моим ощущениям, сгенерированная им man-страница
>    выглядит некачественно (см. dosbox-install в пакете dosbox).

Это неконкретные ощущения.

>    Если перестал, то пишет ли кто-нибудь man-страницы с его помощью?
>    Если пишет, то в каких пакетах можно взглянуть на образцы?

Я писал, уже давно, в пакете нету, есть в аттаче.

> 2) Если ./manpages/ так и остался кривым, то опакечивал ли кто-нибудь man.xsl из Самбы?
> 3) Если не опакечивал и не собирается, то есть ли у нас XML packaging policy?
>    В принципе, если заглянуть в пакеты alt-docs-xsl-*, всё ясно и без неё,
>    но она бы, если дойдут руки, всяко не помешала.

Вы имеете в виду XSL packaging policy ? Насколько я знаю - нет. У 
меня в ближайшее время руки точно не дойдут. И потом ещё не 
дойдут до определённого момента :)

<skipped/>

-- 
Regards, Vyt
mailto:  vyt@vzljot.ru
JID:     vyt@vzljot.ru

[-- Attachment #1.2: xmllint.1 --]
[-- Type: text/plain, Size: 7296 bytes --]

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "XMLLINT" 1 "" "" ""
.SH NAME
xmllint \- êîíñîëüíàÿ óòèëèòà äëÿ ðàáîòû ñ XML
.SH "Îáçîð"

.nf
\fBxmllint\fR [--version] [--debug] [--shell] [--debugent] [--copy] [--recover] [--noent]
        [--noout] [--htmlout] [--nowrap] [--valid] [--postvalid] [--dtdvalid
        \fIURL\fR] [--timing] [--repeat] [--insert] [--compress] [--sgml] [--html]
        [--push] [--memory] [--nowarning] [--noblanks] [--format] [--testIO]
        [--encode \fIencoding\fR] [--catalogs] [--nocatalogs] [--auto] [--xinclude]
        [--loaddtd] [--dtdattr] [--dropdtd] [\fIXML-ôàéë\fR...]
.fi

.SH "Îïèñàíèå"

.PP
Ïðîãðàììà xmllint îáðàáàòûâàåò îäèí èëè íåñêîëüêî XML ôàéëîâ, óêàçàííûõ â ñòðîêå çàïóñêà êàê \fBXML-ôàéë\fR\&. xmllint ñîçäà¸ò ðàçíûå âàðèàíòû âûâîäà â çàâèñèìîñòè îò âûáðàííûõ îïöèé\&. Ïðîãðàììà ïîëåçíà äëÿ âûÿâëåíèÿ îøèáîê â êîäå XML ôàéëà èëè â ñàìîì ïàðñåðå\&.

.PP
 xmllint ÿâëÿåòñÿ ÷àñòüþ áèáëèîòåêè libxml2: \fIhttp://xmlsoft.org\fR\&.

.RS
.Sh "Note"

.PP
Äëÿ ïåðåâîäà íåêîòîðûõ òåðìèíîâ XML èñïîëüçóþòñÿ ðóññêèå ïåðåâîäû: \fIhttp://croll.hotbox.ru/W3C/Consortium/Translation/russian-ru.html\fR äîêóìåíòîâ World Wide Web Consortium: \fIhttp://www.w3.org\fR (W3C)\&.

.RE

.SH "Îïöèè"

.TP
\fB--version\fR
Ïîêàçàòü âåðñèþ èñïîëüçóåìîé áèáëèîòåêè libxml2\&.

.TP
\fB--debug\fR
Îáðàáîòàòü ôàéë è âûâåñòè ñ êîììåíòàðèÿìè ñòðóêòóðó ïðåäñòàâëåíèÿ äîêóìåíòà â ïàìÿòè\&.

.TP
\fB--shell\fR
Çàïóñòèòü êîìàíäíóþ ñðåäó\&. Ïîäðîáíîñòè î äîñòóïíûõ êîìàíäàõ ñðåäû îïèñàíû äàëüøå\&.

.TP
\fB--debugent\fR
Âêëþ÷èòü îòëàäêó ñóùíîñòåé (entities), óêàçàííûõ â äîêóìåíòå\&.

.TP
\fB--copy\fR
Òåñòèðîâàòü ðåàëèçàöèþ âíóòðåííåãî êîïèðîâàíèÿ\&. Êàê ïðàâèëî, ïðîñòî êîïèðóåò äîêóìåíò íà ñòàíäàðòíûé âûâîä\&.

.TP
\fB--recover\fR
Èãíîðèðîâàòü ìåëêèå îøèáêè â èñõîäíîì äîêóìåíòå\&.

.TP
\fB--noent\fR
Çàìåíÿòü ññûëêè íà ñóùíîñòè èõ çíà÷åíèÿìè\&. Ïî óìîë÷àíèþ xmllint îñòàâëÿåò â äîêóìåíòå ññûëêè íà ñóùíîñòè\&. Ýòà îïöèÿ ïîëåçíà âìåñòå ñ \fB--postvalid\fR äëÿ ïðîâåðêè äîêóìåíòîâ, èëè ïðè èñïîëüçîâàíèè ñóùíîñòåé â çíà÷åíèÿõ àòðèáóòîâ\&.

.TP
\fB--noout\fR
Îòêëþ÷àåò âûâîä\&. Ïî óìîë÷àíèþ xmllint âûâîäèò ðåçóëüòèðóþùóþ ñòðóêòóðó äîêóìåíòà\&.

.TP
\fB--htmlout\fR
Âûâåñòè ðåçóëüòàò â ôîðìàòå HTML\&. Äîáàâëÿåò â âûâîä íåîáõîäèìûå HTML-òåãè, ïîçâîëÿþùèå ïðîñìîòðåòü ðåçóëüòèðóþùèé âûâîä â áðàóçåðå\&.

.TP
\fB--nowrap\fR
Íå âûâîäèòü íà÷àëüíîå îáúÿâëåíèå HTML è çàâåðøàþùèå òåãè\&.

.TP
\fB--valid\fR
Ïðîâåðèòü ñîîòâåòñòâèå äîêóìåíòà (validating) îáúÿâëåííîìó òèïó äîêóìåíòà (íàïðèìåð, DTD)\&. Ìîæíî ÿâíî óêàçàòü òèï äîêóìåíòà äëÿ ïðîâåðêè ñ ïîìîùüþ îïöèè \fB--dtdvalid\fR\&. Ïî óìîë÷àíèþ xmllint òàêæå ïðîâåðÿåò, ÷òî äîêóìåíò ïðàâèëüíî ñôîðìèðîâàí (well-formed), òî åñòü ñîîòâåòñòâóåò ïðàâèëàì ðàçìåòêè XML\&. .RS .Sh "Tip" .PP Ïîëåçíî èñïîëüçîâàòü ýòó îïöèþ âìåñòå ñ \fB--noout\fR, òîãäà ïðîâåðî÷íûå ñîîáùåíèÿ íå áóäóò ïóòàòüñÿ ñ âûâîäîì ñàìîãî äîêóìåíòà\&. .RE
Äîêóìåíòû, îáúåäèí¸ííûå ñ ïîìîùüþ îïöèè \fB--xinclude\fR, íóæíî ïðîâåðÿòü îïöèåé \fB--postvalid\fR\&.

.TP
\fB--postvalid\fR
Ïðîâåðèòü ñîîòâåòñòâèå äîêóìåíòà òèïó äîêóìåíòà ïîñëå åãî ðàçáîðà è îáðàáîòêè\&.

.TP
\fB--dtdvalid \fIURL\fR\fR
Ïðîâåðÿòü ñîîòâåòñòâèå òèïó äîêóìåíòà, óêàçàííîìó â \fIURL\fR\&.

.TP
\fB--timing\fR
Âûâîäèòü èíôîðìàöèþ î âðåìåíè, çàòðà÷åííîì íà âûïîëíåíèå ðàçëè÷íûõ äåéñòâèé\&.

.TP
\fB--repeat\fR
Ïîâòîðèòü îïåðàöèþ 100 ðàç, èñïîëüçóåòñÿ äëÿ îïðåäåëåíèÿ ïðîèçâîäèòåëüíîñòè\&.

.TP
\fB--insert\fR
Òåñòèðîâàòü âñòàâêó ýëåìåíòîâ (âíóòðåííèé òåñò)\&.

.TP
\fB--compress\fR
Âêëþ÷èòü gzip-ñæàòèå âûâîäà\&.

.TP
\fB--sgml\fR
Èñïîëüçîâàòü DocBook SGML ïàðñåð\&. Ïîçâîëÿåò ñîçäàâàòü â ïàìÿòè ïðåäñòàâëåíèå äîêóìåíòà, ñîçäàííîãî â ôîðìàòå DocBook SGML, è îáðàáàòûâàòü åãî êàê ñîçäàííûé â XML\&.

.TP
\fB--html\fR
Èñïîëüçîâàòü HTML ïàðñåð\&.

.TP
\fB--push\fR
Èñïîëüçîâàòü ``push'' ðåæèì ïàðñåðà\&.

.TP
\fB--memory\fR
Îáðàáàòûâàòü â ïàìÿòè\&.

.TP
\fB--nowarning\fR
Íå âûâîäèòü ïðåäóïðåæäàþùèå ñîîáùåíèÿ (warnings)\&.

.TP
\fB--noblanks\fR
Âûáðàñûâàòü èãíîðèðóåìûå ïðîáåëüíûå ñèìâîëû\&.

.TP
\fB--format\fR
Ôîðìàòèðîâàòü ðåçóëüòèðóþùèé âûâîä\&.

.TP
\fB--testIO\fR
Òåñòèðîâàòü âîçìîæíîñòè ââîäà/âûâîäà\&.

.TP
\fB--encode \fIencoding\fR\fR
Êîäèðîâàòü âûâîä â óêàçàííîé êîäèðîâêå\&. Êîäèðîâêà â îáúÿâëåíèè XML óñòàíàâëèâàåòñÿ àâòîìàòè÷åñêè\&.

.TP
\fB--catalogs\fR
Èñïîëüçîâàòü ôàéëû êàòàëîãîâ (catalogs) èç ïåðåìåííîé \fISGML_CATALOG_FILES\fR\&. Èíà÷å èñïîëüçóåòñÿ êàòàëîã ïî óìîë÷àíèþ -- \fI/etc/xml/catalog\fR\&.

.TP
\fB--nocatalogs\fR
Íå èñïîëüçîâàòü ëþáûå êàòàëîãè\&.

.TP
\fB--auto\fR
Âûâåñòè íåáîëüøîé äîêóìåíò äëÿ òåñòèðîâàíèÿ\&.

.TP
\fB--xinclude\fR
Îáðàáàòûâàòü âêëþ÷åíèÿ äîêóìåíòîâ ïî ñòàíäàðòó XML Inclusions (XInclude): \fIhttp://www.w3.org/TR/xinclude/\fR\&. Ïî óìîë÷àíèþ xmllint íå âûïîëíÿåò òàêèå âêëþ÷åíèÿ\&. .RS .Sh "Note" .PP  libxml2 äî âåðñèè2\&.4\&.25 îáúåäèíåíèå áîëüøîãî êîëè÷åñòâà äîêóìåíòîâ òðåáîâàëî î÷åíü ìíîãî ðåñóðñîâ è âðåìåíè\&. Ñ âåðñèè 2\&.4\&.25 êîä âêëþ÷åíèé ñåðü¸çíî ïåðåïèñàí è íàäîáíîñòè â áîëüøèõ ðåñóðñàõ íåò\&. .RE .RS .Sh "Tip" .PP Äëÿ ïðîâåðêè äîêóìåíòîâ, èñïîëüçóþùèõ âêëþ÷åíèÿ, íóæíî ïîëüçîâàòüñÿ îïöèåé \fB--postvalid\fR\&. .RE

.TP
\fB--loaddtd\fR
Çàãðóçèòü âíåøíèé òèï äîêóìåíòà\&. Ýòà îïöèÿ ïîëåçíà äëÿ ðàçðåøåíèÿ ñóùíîñòåé, îáúÿâëåííûõ âî âíåøíåì òèïå äîêóìåíòà, ïðè îáúåäèíåíèè íåñêîëüêèõ âêëþ÷àåìûõ äîêóìåíòîâ â îäèí\&.

.TP
\fB--dtdattr\fR
Çàãðóçèòü âíåøíèé òèï äîêóìåíòà è ïîñòðîèòü äåðåâî ñ óíàñëåäîâàííûìè àòðèáóòàìè\&.

.TP
\fB--dropdtd\fR
Óäàëèòü îáúÿâëåíèå òèïà äîêóìåíòà èç âûâîäà\&.

.SH "Êîìàíäíàÿ ñðåäà"

.PP
 xmllint ïîçâîëÿåò èñïîëüçîâàòü èíòåðàêòèâíûé ðåæèì êîìàíä (îïöèÿ \fB--shell\fR)\&. 
Êîìàíäû èíòåðàêòèâíîãî ðåæèìà:
.TP
\fBbase\fR
Ïîêàçàòü XML áàçó óçëà\&.

.TP
\fBbye\fR
Âûéòè èç ðåæèìà êîìàíä\&.

.TP
\fBcat node\fR
Ïîêàçàòü òåêóùèé óçåë, èëè óêàçàííûé [node]\&.

.TP
\fBcd path\fR
Ïåðåéòè ê óêàçàííîìó óçëó, èëè ê êîðíåâîìó, åñëè óçåë [path] íå óêàçàí\&.

.TP
\fBdir path\fR
Ñîõðàíèòü èíôîðìàöèþ óçëà (ïðîñòðàíñòâî èì¸í, àòðèáóòû, ñîäåðæèìîå)\&.

.TP
\fBdu path\fR
Ïîêàçàòü ñòðóêòóðó ïîääåðåâà îò óêàçàííîãî [path] óçëà, èëè îò òåêóùåãî, åñëè íå óêàçàí\&.

.TP
\fBexit\fR
Âûéòè èç ðåæèìà êîìàíä\&.

.TP
\fBhelp\fR
Ïîêàçàòü ñïðàâêó\&.

.TP
\fBfree\fR
Ïîêàçàòü èíôîðìàöèþ îá èñïîëüçîâàíèè ïàìÿòè\&.

.TP
\fBload name\fR
Çàãðóçèòü äîêóìåíò, óêàçàííûé \fIname\fR\&.

.TP
\fBls path\fR
Ïîêàçàòü ñîäåðæèìîå [path] èëè òåêóùåãî êàòàëîãà\&.

.TP
\fBpwd\fR
Ïîêàçàòü ïóòü ê òåêóùåìó óçëó\&.

.TP
\fBquit\fR
Âûéòè èç ðåæèìà êîìàíä\&.

.TP
\fBsave name\fR
Ñîõðàíèòü òåêóùèé äîêóìåíò ñ óêàçàííûì [name] èëè ñ îðèãèíàëüíûì èìåíåì\&.

.TP
\fBvalidate\fR
Ïðîâåðèòü äîêóìåíò íà îøèáêè (ñîîòâåòñòâèå îáúÿâëåííîìó òèïó, ïðàâèëüíîñòü XML)\&.

.TP
\fBwrite name\fR
Çàïèñàòü òåêóùèé óçåë â ôàéë ñ óêàçàííûì \fIname\fR èìåíåì\&.
 

.SH "Ññûëêè"

.TP 3
\(bu
Ðóññêèå ïåðåâîäû: \fIhttp://croll.hotbox.ru/W3C/Consortium/Translation/russian-ru.html\fR äîêóìåíòîâ World Wide Web Consortium: \fIhttp://www.w3.org\fR (W3C);
.TP
\(bu
Ñàéò áèáëèîòåêè libxml2: \fIhttp://xmlsoft.org\fR;
.LP

.SH AUTHORS
John Fleck <jfleck@inkstain\&.net>, Ziying Sherwin <sherwin@nlm\&.nih\&.gov>, Heiko Rupp <hwr@pil-huhn\&.de>.

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [devel] Re: xml2man

[Mikhail Zabaluev]

[-- Attachment #1: Type: text/plain, Size: 658 bytes --]

В Втр, 21/12/2004 в 14:36 +0300, Vitaly Ostanin пишет:
> > 3) Если не опакечивал и не собирается, то есть ли у нас XML packaging policy?
> >    В принципе, если заглянуть в пакеты alt-docs-xsl-*, всё ясно и без неё,
> >    но она бы, если дойдут руки, всяко не помешала.
> 
> Вы имеете в виду XSL packaging policy ? Насколько я знаю - нет. У 
> меня в ближайшее время руки точно не дойдут. И потом ещё не 
> дойдут до определённого момента :)

У меня тоже -- я сейчас активно занимаюсь Java packaging policy :)

Пока можно заглянуть в документы Debian -- мы, скорее всего, не будем
изобретать велосипед. Но, возможно, слегка его модифицируем.


[-- Attachment #2: Эта часть сообщения подписана цифровой подписью --]
[-- Type: application/pgp-signature, Size: 189 bytes --]