Пытался найти систему для ведения единой документации, чтобы и для печати, и для on-line. Наткнулся на DocBook - везде пишут, какая это замечательная вещь! Попробовал поставить - ничерта не выходит. Поставил OpenJade, DTDs и всё прочее, как описано в различных документах. Я вообще себя идиотом не считаю и мне приходилось не только компилять и ставить что-то из исходников, но и ковыряться в них... Так вот с этим OpenJade явно что-то не так - он встал, но при запуске обычно выдаёт кучу мусора (например 'openjade --help' - пишет после каждой строки строчку, состоящую из одного символа, '>', и про половину опций - что-то вроде "неизвестный ключ"). При попытке обработки какого-нибудь sgml-файла, предлагаемого где-нибудь на www.oasis-open.org (или в других многочисленных topic-related местах) в качестве примера выдаёт кучу сообщений, смысл которых не вполне ясен, возможно из-за того, что SGML я ещё не изучил, а в качестве результата - что-то страшное. Например при просьбе выдать html (используя .../ldp.dsl#html) был выдан 'plain text', в котором каждый обзац представлен одной строкой. И это ещё не самый плохой случай из всех моих экспериментов.Я прошу прощения за такой длинный спич, но наболело!
Вопрос же в следующем: кто-нибудь реально использовал эту штуку, и если да, то какие версии чего (включая TeX, JadeTeX, или_что_там_ещё, etc) и как всё это заставить работать?!
P.S. Очень нужно - на работе замучились с синхронизацией различных версий документации!
> Пытался найти систему для ведения единой документации, чтобы и для печати, и для on-line.
<skipped>
> Я прошу прощения за такой длинный спич, но наболело!
>Вопрос же в следующем: кто-нибудь реально использовал эту штуку, и если да,
>то какие версии чего (включая TeX, JadeTeX, или_что_там_ещё, etc) и как
>всё это заставить работать?!
> P.S. Очень нужно - на работе замучились с синхронизацией различных версий документации!
>
Есть пример проекта документации FreeBSD.
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer
Все необходимые доки по формату и прочему на сайте имеются. Простейший способ освоить этот формат - скачать немного документации в sgml и посмотреть как там все устроено.
Еще один способ - залезть на www.php.net
Там тоже есть примеры прямо на DocBook.
У FreeBSD на мой взгляд небольшое но существенное преимущество: все ставится на раз из портов или пакетов, тебе не придется долбаться с этими прогами, все сразу заработает. Но все это конечно только getting started... Формат доков придется переделывать под себя.
>Есть пример проекта документации FreeBSD.
>http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer
Я посмотрел оглавление - судя по всему ничего нового к тому, что я уже читал там нет, но всё-равно я почитаю, спасибо.>Все необходимые доки по формату и прочему на сайте имеются. Простейший способ
>освоить этот формат - скачать немного документации в sgml и посмотреть
>как там все устроено.
Проблема собственно не в освоении формата, а в том, чтобы всё работало...>У FreeBSD на мой взгляд небольшое но существенное преимущество: все ставится на
>раз из портов или пакетов, тебе не придется долбаться с этими
Боюсь порты мне не подойдут, т.к. я сижу под линухом. Мне бы всё это самому собрать. Да вот только не работает чегой-то...Кстати, ещё пара странных моментов относительно DocBook: нигде всё необходимое не лежит в одном месте, хотя многие части одна без другой не имеют смысла, и ещё, половина лежит в .tar.gz, а половина - в .zip, то есть что-то ориентировано на unix-пользователей, а что-то - на windows, единой системы как будто нет...
>>Есть пример проекта документации FreeBSD.
>>http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer
>Я посмотрел оглавление - судя по всему ничего нового к тому, что
>я уже читал там нет, но всё-равно я почитаю, спасибо.
>
>>Все необходимые доки по формату и прочему на сайте имеются. Простейший способ
>>освоить этот формат - скачать немного документации в sgml и посмотретья еще и другой вариант давал, надо только поискать было. сам за тебя все нашел:
вот здесь
http://www.php.net/download-docs.php
внизу страницы есть такая ссылка:
http://cvs.php.net/co.php/phpdoc/howto/howto.html.tar.gz?p=1
как они пишут документацию, что для этого надо....
почитай, если руки на месте - у тебя все получится.