I was trying to use my RubyAEOSA documentation, and started suspecting
that there was stuff missing. Sure enough, there's a whole "doc" folder
with stuff not generated by RDoc. It looks like RDoc-ready files,
except there's both *.en and *.jp versions for most plus *.en.html and
*.jp.html. None of those extensions will normally get read by RDoc, and
there was no .document file.
Nor are there any doc-building commands in the install.rb file.
There IS a highly mysterious "build_html.rb" file in the doc directory.
It appears to run a command-line tool named "rd2" against the non-html
files. I don't have an rd2 command.
I did find a web-replica of a man page that said
rd2 - converter from RD to other mark-up language.
and a different page that had
Rd2 RDTool, http://www2.pos.to/
tosh/ruby/rdtool/en/index.html
But even when I removed the odd space before "tosh", that link still
leads to a 404. I did eventually run down
http://raa.ruby-lang.org/project/rdtool
Which got me this information:
RDtool is RD formater and utilities. (RD is Ruby's POD)
If you use Ruby 1.8, you might not need to install Racc and so on.
If you will install RDtool on WinNT, you should read
Dirk Detering's HOWTO document.
http://www.dets-home.de/it-writings/Install_rd2_winnt.html
And now I'm stuck. The only documentation (for what appears to be a
documentation tool!) is the "How to install on Windows" link. (The fact
that this is typical of my experience with Ruby things is why I'm here
. . . ) What does "RD is Ruby's POD" mean? Is there any documentation
about the markup language itself? Is it still actively used, is it
being replaced by SimpleMarkup that ships with RDoc, or is something
else replacing it? Is there an rd2sm.lib translator for it?
OK, I did find an archived maillist message from Booker Bense from
2002(!) suggesting that RDOc should *output* RD2 and POD. So now I know
that POD is yet another markup language.
So I guess that RubyAEOSA's doc directory contains documentation marked
up in RD2, rather than SimpleMarkup, although the only relevant
difference I've noticed so far is how a URL is specified.
Any comments or information that people could provide would be
appreciated, since I'm probably going to write a proper RDoc control
.document for this package . . .
[p.s. There's also the whole issue of SimpleMarkup's link markup, but
that's for a different message...]
|
