[devel] docs creations

[devel] docs creations

[Vyt]

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

Hello, All!

Было бы просто здорово, если бы кто-нибудь из корифеев разразился
кратким введением на тему _правильного_ написания документации.
Хотя бы в виде набора ссылок для начинающих...

Интересует формат, инструменты, необходимые пакеты из Sisyphus,
приемы. 

Из имеющегося обилия сложно выбрать нужное, после ковыряния с
postfix.xml от MhZ смотрю на http://www.docbook.org, чувствую,
что это надолго :)

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

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [devel] docs creations

[Yura Zotov]

On Fri, Mar 01, 2002 at 06:48:26PM +0300, Vyt wrote:
> Hello, All!
> 
> Было бы просто здорово, если бы кто-нибудь из корифеев разразился
> кратким введением на тему _правильного_ написания документации.
> Хотя бы в виде набора ссылок для начинающих...
> 
> Интересует формат, инструменты, необходимые пакеты из Sisyphus,
> приемы. 
> 
> Из имеющегося обилия сложно выбрать нужное, после ковыряния с
> postfix.xml от MhZ смотрю на http://www.docbook.org, чувствую,
> что это надолго :)
> 

Можно, например, на texinfo.

--
Юрий А. Зотов

Re: [devel] docs creations

[Igor Homyakov]

On Fri, Mar 01, 2002 at 07:10:28PM +0300, Yura Zotov wrote:
> On Fri, Mar 01, 2002 at 06:48:26PM +0300, Vyt wrote:
> > Hello, All!
> > 
> > Было бы просто здорово, если бы кто-нибудь из корифеев разразился
> > кратким введением на тему _правильного_ написания документации.
> > Хотя бы в виде набора ссылок для начинающих...
> > 
> > Интересует формат, инструменты, необходимые пакеты из Sisyphus,
> > приемы. 
> > 
> > Из имеющегося обилия сложно выбрать нужное, после ковыряния с
> > postfix.xml от MhZ смотрю на http://www.docbook.org, чувствую,
> > что это надолго :)
> > 
> 
> Можно, например, на texinfo.
> 
На мой взгляд docbook представляеться боллее правильным решением 

-- 
Igor Homyakov
<homyakov(at)ramax.spb.ru>

[devel] Re: docs creations

[Vyt]

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

On Fri, 1 Mar 2002 20:17:31 +0300
Igor Homyakov <homyakov@ramax.spb.ru> wrote:

<skipped>

> > > Было бы просто здорово, если бы кто-нибудь из корифеев разразился
> > > кратким введением на тему _правильного_ написания документации.
> > > Хотя бы в виде набора ссылок для начинающих...
> > > 
> > > Интересует формат, инструменты, необходимые пакеты из Sisyphus,
> > > приемы. 
> > > 
> > > Из имеющегося обилия сложно выбрать нужное, после ковыряния с
> > > postfix.xml от MhZ смотрю на http://www.docbook.org, чувствую,
> > > что это надолго :)
> > > 
> > 
> > Можно, например, на texinfo.

Плохо выразился - нужно писать документацию не к исходным
текстам, скорее общая, например, к jabber ;)

> На мой взгляд docbook представляеться боллее правильным решением

Спасибо!

Нашел великолепную статью Бориса Тоботраса
http://xtalk.opensource.ru/SGML/SGML-article.html
Он меня не убедил, он меня выразил :)

Похоже, что форматом лучше взять sgml с docbook-dtds, если не
прав - поправьте, pls.

<skipped>

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

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [devel] Re: docs creations

[Vitaly Lipatov]

On 1 March 2002 19:28, Vyt wrote:
> Похоже, что форматом лучше взять sgml с docbook-dtds, если не
> прав - поправьте, pls.
>
Использовать LyX для написания sgml?
-- 
Lav
Виталий Липатов
ФГУП "ЦНИИ Судовой Электротехники и Технологии", Санкт-Петербург
GNU! Linux! LaTeX! LyX!

[devel] Re: docs creations

[Michael Shigorin]

On Sat, Mar 02, 2002 at 12:38:21AM +0300, Vitaly Lipatov wrote:
> > Похоже, что форматом лучше взять sgml с docbook-dtds, если не
> > прав - поправьте, pls.
> Использовать LyX для написания sgml?
И, ежели выйдет по-русски -- ито возвращайтесь в студию, пжста :)

-- 
 ---- WBR, Michael Shigorin <mike@altlinux.ru>
  ------ http://visa.chem.univ.kiev.ua/~mike/

Re: [devel] Re: docs creations

[Vitaly Lipatov]

On 2 March 2002 09:58, Michael Shigorin wrote:
> On Sat, Mar 02, 2002 at 12:38:21AM +0300, Vitaly Lipatov wrote:
> > > Похоже, что форматом лучше взять sgml с docbook-dtds, если не
> > > прав - поправьте, pls.
> >
> > Использовать LyX для написания sgml?
>
> И, ежели выйдет по-русски -- ито возвращайтесь в студию, пжста :)
Так дело, я так понял, в утилитах из docbook-dtds,
с ними непонятки.
-- 
Lav
Виталий Липатов
ФГУП "ЦНИИ Судовой Электротехники и Технологии", Санкт-Петербург
GNU! Linux! LaTeX! LyX!

[devel] Re: docs creations

[Mikhail Zabaluev]

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

Hello Vitaly,

On Sat, Mar 02, 2002 at 11:12:53AM +0300, Vitaly Lipatov wrote:
>
> On 2 March 2002 09:58, Michael Shigorin wrote:
> > On Sat, Mar 02, 2002 at 12:38:21AM +0300, Vitaly Lipatov wrote:
> > > > Похоже, что форматом лучше взять sgml с docbook-dtds, если не
> > > > прав - поправьте, pls.
> > >
> > > Использовать LyX для написания sgml?
> >
> > И, ежели выйдет по-русски -- ито возвращайтесь в студию, пжста :)
> Так дело, я так понял, в утилитах из docbook-dtds,
> с ними непонятки.

В docbook-dtds нет утилит, они в docbook-utils.
Что за непонятки?

-- 
Stay tuned,
  MhZ                                     JID: mookid@jabber.org
___________
If you have a procedure with 10 parameters, you probably missed some.

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]

Re: [devel] Re: docs creations

[Vitaly Lipatov]

On 2 March 2002 14:30, Mikhail Zabaluev wrote:
> Hello Vitaly,
>
> On Sat, Mar 02, 2002 at 11:12:53AM +0300, Vitaly Lipatov wrote:
> > On 2 March 2002 09:58, Michael Shigorin wrote:
> > > On Sat, Mar 02, 2002 at 12:38:21AM +0300, Vitaly Lipatov wrote:
> > > > > Похоже, что форматом лучше взять sgml с docbook-dtds, если не
> > > > > прав - поправьте, pls.
> > > >
> > > > Использовать LyX для написания sgml?
> > >
> > > И, ежели выйдет по-русски -- ито возвращайтесь в студию, пжста :)
> >
> > Так дело, я так понял, в утилитах из docbook-dtds,
> > с ними непонятки.
>
> В docbook-dtds нет утилит, они в docbook-utils.
> Что за непонятки?
Я так и не понял, какие пакеты надо установить, чтобы потом преобразовывать
sgml (или xml?) во что-то там.
Пытаюсь установить, но натыкаюсь на ошибки:

Следующие НОВЫЕ пакеты будут установлены:
  docbook-dtds docbook-utils docbook-utils-pdf
0 пакетов будет обновлено, 3 будет добавлено новых, 2 будет удалено(заменено) 
и
9 не будет обновлено.
Необходимо получить 0B/340kB архивов. После распаковки 1162kБ будет 
использовано.
Продолжить? [Y/n]
Выполняется программа RPM (/bin/rpm -Uv --replacepkgs -h)...
Подготовка...                
##################################################
docbook-dtds                 
##################################################
add command failed
add command failed
add command failed
add command failed
add command failed
add command failed
add command failed
add command failed
add command failed
add command failed
ошибка: ошибка выполнения сценария %post из docbook-dtds-1.0-alt1, код 
возврата
3
-- 
Lav
Виталий Липатов
ФГУП "ЦНИИ Судовой Электротехники и Технологии", Санкт-Петербург
GNU! Linux! LaTeX! LyX!

[devel] Re: docs creations

[Mikhail Zabaluev]

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

Hello Vitaly,

On Sat, Mar 02, 2002 at 03:29:28PM +0300, Vitaly Lipatov wrote:
>
> > В docbook-dtds нет утилит, они в docbook-utils.
> > Что за непонятки?
> Я так и не понял, какие пакеты надо установить, чтобы потом преобразовывать
> sgml (или xml?) во что-то там.
> Пытаюсь установить, но натыкаюсь на ошибки:
> 
> Следующие НОВЫЕ пакеты будут установлены:
>   docbook-dtds docbook-utils docbook-utils-pdf
> 0 пакетов будет обновлено, 3 будет добавлено новых, 2 будет удалено(заменено) 
> и
> 9 не будет обновлено.
> Необходимо получить 0B/340kB архивов. После распаковки 1162kБ будет 
> использовано.
> Продолжить? [Y/n]
> Выполняется программа RPM (/bin/rpm -Uv --replacepkgs -h)...
> Подготовка...                
> ##################################################
> docbook-dtds                 
> ##################################################
> add command failed
> add command failed
> add command failed
> add command failed
> add command failed
> add command failed
> add command failed
> add command failed
> add command failed
> add command failed
> ошибка: ошибка выполнения сценария %post из docbook-dtds-1.0-alt1, код 
> возврата
> 3

xml-common и sgml-common установлены последние?

Проверьте каталоги на предмет кавычек у аргумента директивы CATALOG:

/etc/sgml/catalog
/etc/sgml/*-docbook-*.cat

Попробуйте проставить кавычки вручную, если их нет, и повторить
установку docbook-dtds (можно с --force). Сообщите о результатах.

-- 
Stay tuned,
  MhZ                                     JID: mookid@jabber.org
___________
The most difficult thing in the world is to know how to do a thing and to
watch someone else doing it wrong, without commenting.
		-- T.H. White

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]

Re: [devel] Re: docs creations

[Vitaly Lipatov]

On 2 March 2002 16:39, Mikhail Zabaluev wrote:
> Hello Vitaly,
>
> On Sat, Mar 02, 2002 at 03:29:28PM +0300, Vitaly Lipatov wrote:
> > > В docbook-dtds нет утилит, они в docbook-utils.
> > > Что за непонятки?
> >
> > Я так и не понял, какие пакеты надо установить, чтобы потом
> > преобразовывать sgml (или xml?) во что-то там.
> > Пытаюсь установить, но натыкаюсь на ошибки:

> xml-common и sgml-common установлены последние?
[lav@lav mpl]$ [lav@lav Project]$ rpm -q xml-common
xml-common-0.6.3-alt6
[lav@lav Project]$ rpm -q sgml-common
sgml-common-0.6.3-alt6

>
> Проверьте каталоги на предмет кавычек у аргумента директивы CATALOG:
>
> /etc/sgml/catalog
> /etc/sgml/*-docbook-*.cat
Да есть там везде кавычки
>
> Попробуйте проставить кавычки вручную, если их нет, и повторить
> установку docbook-dtds (можно с --force). Сообщите о результатах.
Вот этого я не понимаю:
$sudo apt-get install docbook-dtds --reinstall
Обработка файловых зависимостей... Завершено
Чтение списков пакетов... Завершено
Построение дерева зависимостей... Завершено
Возможно, Вам потребуется запустить `apt-get -f install' для исправления:
Извините, но следующие пакеты имеют неудовлетворенные зависимости:
  docbook-dtds: Obsoletes: docbook-dtd30-sgml
                Obsoletes: docbook-dtd412-xml
E: Некоторые зависимости не были найдены. Попробуйте `apt-get -f install' без 
указания пакетов или укажите пакет-решение.

Объясните мне, по последним веяниям sgml и xml разнесены по разным пакетам, 
или наоборот, объединены? А то у меня какие-то круговые зависимости ---
установливаешь одно, убирается другое...
-- 
Lav
Виталий Липатов
ФГУП "ЦНИИ Судовой Электротехники и Технологии", Санкт-Петербург
GNU! Linux! LaTeX! LyX!

[devel] Re: docs creations

[Mikhail Zabaluev]

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

Hello Vitaly,

On Sat, Mar 02, 2002 at 08:54:27PM +0300, Vitaly Lipatov wrote:
>
> Вот этого я не понимаю:
> $sudo apt-get install docbook-dtds --reinstall
> Обработка файловых зависимостей... Завершено
> Чтение списков пакетов... Завершено
> Построение дерева зависимостей... Завершено
> Возможно, Вам потребуется запустить `apt-get -f install' для исправления:
> Извините, но следующие пакеты имеют неудовлетворенные зависимости:
>   docbook-dtds: Obsoletes: docbook-dtd30-sgml
>                 Obsoletes: docbook-dtd412-xml
> E: Некоторые зависимости не были найдены. Попробуйте `apt-get -f install' без 
> указания пакетов или укажите пакет-решение.
> 
> Объясните мне, по последним веяниям sgml и xml разнесены по разным пакетам, 
> или наоборот, объединены? А то у меня какие-то круговые зависимости ---
> установливаешь одно, убирается другое...

docbook-dtds заменяет все docbook-dtd*-*ml

-- 
Stay tuned,
  MhZ                                     JID: mookid@jabber.org
___________
If you're careful enough, nothing bad or good will ever happen to you.

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]

[devel] Re: docs creations

[Mikhail Zabaluev]

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

Hello Vyt,

On Fri, Mar 01, 2002 at 06:48:26PM +0300, Vyt wrote:
>
> Hello, All!
> 
> Было бы просто здорово, если бы кто-нибудь из корифеев разразился
> кратким введением на тему _правильного_ написания документации.
> Хотя бы в виде набора ссылок для начинающих...
> 
> Интересует формат, инструменты, необходимые пакеты из Sisyphus,
> приемы. 
> 
> Из имеющегося обилия сложно выбрать нужное, после ковыряния с
> postfix.xml от MhZ смотрю на http://www.docbook.org, чувствую,
> что это надолго :)

А чего тут долгого, после того как в дистрибутиве всё более-менее
налажено, можно просто пролистать Docbook: The Definitive Guide
и начать ваять документы, как сделал я.
По сложности примерно то же, что HTML (даже без таблиц), но по
"прямизне" и продуманности гораздо лучше.

-- 
Stay tuned,
  MhZ                                     JID: mookid@jabber.org
___________
Each person has the right to take the subway.

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]