Bug 3047

Summary:	Better docs
Product:	Sisyphus	Reporter:	Mikhail Yakshin <greycat>
Component:	ruby-doc	Assignee:	Alexander Bokovoy <ab>
Status:	CLOSED FIXED	QA Contact:	qa-sisyphus
Severity:	enhancement
Priority:	P2	CC:	abulava, admsasha, cas, majioa, mike, nbr, pav, rider, thatman
Version:	unstable
Hardware:	all
OS:	Linux

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

С тех пор все радикально поменялось, так что, видимо, баг уже малоактуален.