On 17/11/05 at 08:58 +0100, Lucas Nussbaum wrote: > Hi, > > Yesterday, I worked on the packaging of the XMPP4R library. It is a > rather large library which includes docs, examples, and unit tests. > > I think we should come up with a common policy on how we should package > libraries : > > - should examples, rdoc documentation, ri documentation, unit tests be > packaged ? > > - should they be packaged in only one other package (-dev ? -doc ?) or > several others ? (-examples, -doc, -tests) ? > > - How do one generate documentation for ri ? > > - I think that it would be a good idea to package unit tests, because > that would allow for automatic testing of packages after installation. > For example, rake was recently broken in sid : it was ok when it was > uploaded, but the upgrade from ruby 1.8.2 to ruby 1.8.3 broke it. > This could have been detected by some unit tests run by a cron job. > (Also, it would ease the work of developers who work on ruby packaging > in ubuntu, by making it very easy to track down issues introduced by a new > package :-) > > - What should we include in the rdoc files ? public methods only ? > inline source ? diagrams ? (they are very cool!) I usually generate my > HTML doc with rdoc --all --diagram --fileboxes --inline-source > --line-numbers. But this creates a 1.8M -doc package for libxmpp4r-ruby, > while the library itself is only 36K... > > My libxmpp4r-ruby package in the pkg-ruby-extras SVN repository does > multipackaging and generates rdoc at package build time. We an use it as > a basis for discussion.
Replying to myself, and Ccing [EMAIL PROTECTED] After thinking about it for a while, I came to the conclusion that we have to consider the user's point of view. There are two kinds of library users : - those only using software that relies on this library. Those don't care about rdoc documentation, etc. - those developing software using this library. Those want as much help as possible. Therefore, I think ruby libraries should be packaged using two binary packages : - libxxxxx-ruby1.8: contains only /usr/lib/ruby/1.8/xxxx/* and the copyright/changelog stuff. - libxxxxx-ruby1.8-dev: contains examples, unit tests, rdoc documentation, ri documentation. About unit tests: it would be great to have a common architecture to deal with our unit tests. This way, one could run a script on a regular basis to check that all his installed packages still work correctly. About ri documentation: is there a debian package already generating some of it, except the ri1.8 package itself ? About rdoc documentation: it tends to be *big*. Here are some number while generating XMPP4R's documentation : Options: --all --diagram --fileboxes --inline-sources --line-numbers Time: 84s Size: 4756k Options: --diagram --fileboxes --inline-sources --line-numbers (removed --all) Time: 81s Size: 4642k (Expected, since I don't use many private methods) Options: --diagram --inline-sources --line-numbers (removed --all --fileboxes) Time: 65s Size: 3220k Removing --fileboxes decreases the size of diagrams slightly. Options: --inline-sources --line-numbers (removed --all --diagram --fileboxes) Time: 17s Size: 1000k Diagrams seem to take a lot of space. Options: (removed --all --diagram --fileboxes --inline-sources --line-numbers) Time: 17s Size: 2096k When source is not inlined, it uses much more space. So it seems that the biggest contribution to the rdoc doc is diagrams. Looking at them, it seems most of them are redundant (they are the same except for the title). Maybe one could look at the rdoc code and see if a patch is possible ? I've updated libxmpp4r to split files according to the above policy. -- | Lucas Nussbaum | [EMAIL PROTECTED] http://www.lucas-nussbaum.net/ | | jabber: [EMAIL PROTECTED] GPG: 1024D/023B3F4F | -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
