Another latecomer; A half-baked suggestion

Concerning everything else that you said, it seems to me that
you are envisioning a system that will provide full
documentation capabilities. That is, a way to write large
documentation documents that can be exported to many formats. Am
I correct?

There any other kind? If you put forth a standard like POD, then

Yes. Let me explain. It has been discussed that there are different
types of documentation. Some of those listed are: API, tutorial,
installation, users guide and reference manual.

Sorry, I don’t understand the above. Are you saying that some XML file
has a set of doc types defined? What are the ‘?’ for?

My point is that we don’t need to put each of these types of
documentation inside the source. (It is a matter of discussion if it
needs to be linked from the source.)

Again, I’m not sure what you are saying.

Also, to me it is not clear that all these types of documentation
possess the same markup requirements. So, I think that a system that
facilitates footnotes, creation of an index, bibliography and table
of contents may be overkill for an API documentation system.

Agreed. An API documentation system needs very little.

*) It’s parent class’s name (automatically determined)
*) The method name (automatically determined?)
*) Its arguments (arity is known, but a manual description is needed)
*) Its return value (manual)
*) Exceptions a method will throw (possibly automatic, but needs manual descriptions)
*) Information about performance and resources (expensive, fast, memory, external dependencies)

Shouldn’t need any more than that. Something as simple as:

class: Foo

name: bar

arg: argname, description…[newline reached]

more description for argname

arg: argname2, description for argname2

return: it’s return value

exception: Foo::ExceptionBadOne, description of exception

exception: Foo::ExceptionBadTwo, description of exception

notes: various performance notes

This is good. This is the type of thing we need to discuss and
put in the functional spec.

Sean: I don’t see any problem with what you are proposing.
to create various doc outputs. Also, if rdoc export to xml,
you are saying that with xml style sheets you can make that
pretty too.

To me this is all doable and does not need to be part of the
base isntall, but can be installed as a 3rd party doc tool.

Since you are so active with this, I want to make sure we take
your ideas into consideration so that in the least we do not
inhibit the use of this feature rich functionality and at the
most that the standard doc system works cooperatively with such
a document system.

But this brings up the issue that was skirted, and that
is exactly how do we support both. It could be as simple as
the doc writer uses simple ML or docbook for external
documents. The simple ML for more routine work and
docbook for larger doc projects.
Also, I suppose that for a system to work cooperatively that
a way be provided that an external doc system could fetch
the internal api docs automatically. Whether that means
that the standard doc system export that information or
a tool/module be provided to access the information remains to be determined.


On Tue, Sep 17, 2002 at 12:59:46PM -0700, Sean Chittenden wrote:
From my perspective, you are suggesting that we use docbook

Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

----- End forwarded message -----

Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class