[ruby-talk:03324] Re: about documentation

Hi,

At Tue, 13 Jun 2000 00:08:14 +0900 (JST),
in [ruby-talk:03304] Re: about documentation,
Toshiro Kuwabara <[e-mail]> 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