Hi, At Tue, 13 Jun 2000 00:08:14 +0900 (JST), in [ruby-talk:03304] Re: about documentation, Toshiro Kuwabara <toshirok / yb3.so-net.ne.jp> wrote: > > Well... Some rubyist loves RD very much, they wrote even books and > articles of magazines in RD. On the other hand, some think RD is not > so good. well... it is very difficult to satisfy all hackers... I am probably one in the latter ;-) > >I guess one of the questions we need to answer is: do we want a single > >master format for all documentation, or is it acceptable to have (say) > >rd for the in-source library documentation and xml for the external > >stuff (such as how-to's). > > Maybe, we don't choose one, I think. > If you want XML based documentation format, there is rubyapi2, it is > used for Ruby/Gtk document. > (But I don't know whether rubyapi2 has english web page or not.) Solly, rubyapi2 English page is not available. http://www.ueda.info.waseda.ac.jp/~igarashi/ruby/rubyapi2-19991106.tar.gz I have not maintained it for a long time. Ruby/GTK API Document is anything but completion. source XML (includes rubyapi.dtd): http://www.ruby-lang.org/gtk/download/ruby-gtk-rubyapi-20000228.tar.gz generated HTML pages: http://www.ruby-lang.org/gtk/en/doc.html#api My impressions on XML based documents are: * many tools are avilable to process them as you know... XML parsers are already available. This is a reason to try XML as Ruby/GTK document format. * not hard to write with proper tools I use PSGML mode on Emacs. If a DTD is provided, it is not so hard to write document from scratch. But RD is easier to write than XML and I write it without such tools. * not friendly to sources It is desirable that documents are in sources for the consistency. But I cannot use PSGML mode in C programs or Ruby scripts (I wish I could use multiple modes in a buffer). Without PSGML mode, it is harder to write (or cannot). So, Ruby/GTK API Document is currently separated from sources. and TODO I think about rubyapi now are: * redesign DTD rubyapi.dtd * rewrite with xmltypemap.rb(provide mapping elements to objects) * inter-conversion from/to RD format(based on some conventions) * various output format * improve performance (currenly process documents on memory) I'm not certain rubyapi or some other XML-based formats has marked benefits. I have tried XML for Ruby/GTK, but I think Ruby/GTK is probably a exception. Because this is very very large wrapper written in C. As Dave says in [ruby-talk:03314], I think we need to try RD for the present. ---- Hiroshi IGARASHI