Bug 3047 - Better docs
: Better docs
Status: CLOSED FIXED
: Sisyphus
(All bugs in Sisyphus/ruby-doc)
: unstable
: all Linux
: P2 enhancement
Assigned To:
:
:
:
:
:
  Show dependency tree
 
Reported: 2003-09-26 05:21 by
Modified: 2006-12-17 10:19 (History)


Attachments


Note

You need to log in before you can comment on or make changes to this bug.


Description From 2003-09-26 05:21:24
У меня есть два предложения:

1. Вынести книжку "Programming Ruby" в отдельный пакет. Rationale: она
достаточно большая, насколько я знаю, со времен 1.6, если не раньше, вообще
никак не менялась, уже порядком устарела, хотя и является одним из наиболее
полных источников информации по Ruby. Вынесение ее в пакет типа ruby-doc-book
сэкономило бы массу трафика при апгрейдах. Заодно можно не извращаться, а
проставить тогда версию пакета равной версии книжки.

2. Генерировать rdoc для всего того, что есть в ruby-stdlibs прямо в пакете и
хранить статически, либо после установки генерить его на месте по post-install,
чтобы всегда под рукой был удобный reference manual.
------- Comment #1 From 2003-09-29 13:34:03 -------
1. Вынес, будет отдельный пакет ruby-doc-extra-0.1-alt1 со всей дополнительной
документацией (Programming Ruby, доклады с конференций, etc)

2. Генерация при установке мне не очень нравится -- тянет за собой достаточно
большой комплект ненужных в работе ruby-stdlibs программ (graphviz, по крайней
мере). Сгенерированная документация получается где-то в районе 20Мб.

Могу сделать дополнительный пакет, который будет содержать сгенерированную
документацию и обновлять его периодически. Пакет не будет требовать ничего для
своей установки.
------- Comment #2 From 2003-09-30 16:40:24 -------
1. Ок, а что же тогда останется в ruby-doc? Какие-то ридмишки от мелких
модулей?

2. Не очень понятно, чем не нравится динамическая генерация. Пусть будет
виртуальный пакет типа ruby-doc-reference. Сам пакет будет выходить новый с
каждой новой версией ruby-stdlibs (собираться из того же спека, что и они). В
пакете ничего не будет, зато будет скрипт, запускающийся каждый раз при
обновлении (обновление ruby-stdlibs будет тянуть за собой безусловное
обновление
ruby-doc-reference, если таковой установлен, т.е. зависимость
ruby-doc-reference
требует равный по версии ruby-stdlibs). Пакет ruby-doc-reference может
требовать
все, чего ему захочется. Если пользователю не нужна документация - пожалуйста,
не ставь - не будет ни документации, ни зависимостей. Если нужна -
замечательно...

И еще я не очень понимаю, при чем тут graphviz. По-моему для генерации
документации достаточно rdoc, разве нет?
------- Comment #3 From 2003-09-30 16:47:42 -------
1. Да, внутренняя документация.

2. Динамическая генерация занимает время. На AthlonXP 1700+ это порядка 5 минут.
Такое недопустимо при обновлении.

rdoc может генерировать графы зависимостей между модулями и классами, это самое
важное в его функциональности. Для этого используется graphviz (dot),
получающиеся файлы суммарно имеют объем около 15Мб.
------- Comment #4 From 2004-03-09 19:56:01 -------
$ apt-cache search ruby-doc
fxruby-doc - Документация по FXRuby
ruby-doc - Documentation for the powerful language Ruby

Нету ruby-doc-extra, пришлось качать Programming Ruby v0.4 с
pragmaticprogrammer.com :-(
------- Comment #5 From 2006-12-16 23:21:33 -------
(In reply to comment #4)
> Нету ruby-doc-extra
Есть ruby-doc-extra! :-)

По второму пункту, как понимаю, контрвозражений нет?
------- Comment #6 From 2006-12-17 10:19:23 -------
С тех пор все радикально поменялось, так что, видимо, баг уже малоактуален.