Bug 3047 - Better docs
Summary: Better docs
Status: CLOSED FIXED
Alias: None
Product: Sisyphus
Classification: Development
Component: ruby-doc (show other bugs)
Version: unstable
Hardware: all Linux
: P2 enhancement
Assignee: Alexander Bokovoy
QA Contact: qa-sisyphus
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2003-09-26 05:21 MSD by Mikhail Yakshin
Modified: 2006-12-17 10:19 MSK (History)
10 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Mikhail Yakshin 2003-09-26 05:21:24 MSD
У меня есть два предложения:

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

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

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

Могу сделать дополнительный пакет, который будет содержать сгенерированную
документацию и обновлять его периодически. Пакет не будет требовать ничего для
своей установки.
Comment 2 Mikhail Yakshin 2003-09-30 16:40:24 MSD
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 Alexander Bokovoy 2003-09-30 16:47:42 MSD
1. Да, внутренняя документация.

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

rdoc может генерировать графы зависимостей между модулями и классами, это самое
важное в его функциональности. Для этого используется graphviz (dot),
получающиеся файлы суммарно имеют объем около 15Мб.
Comment 4 Andrei Bulava 2004-03-09 19:56:01 MSK
$ 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 Michael Shigorin 2006-12-16 23:21:33 MSK
(In reply to comment #4)
> Нету ruby-doc-extra
Есть ruby-doc-extra! :-)

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