Re: Another latecomer; A half-baked suggestion.

On Tue, Sep 17, 2002 at 12:59:46PM -0700, Sean Chittenden wrote:
> > > > 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.
> 
> <!ELEMENT doc (meta,introduction?,tutorial?,install?,api?,config?,sysadmin?,devhelp?,examples?,misc?,bugs?,history?,user_contrib?)>
> 

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.)
> 
> <!ELEMENT api (ruby_global_vars?,ruby_class_public_api?,ruby_class_protected_api?,ruby_class_private_api?,ruby_instance_public_api?,ruby_instance_protected_api?,ruby_instance_private_api?,ruby_instance_vars?,c_headers?,c_so_libs?,c_api?)>
> 

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.
From my perspective, you are suggesting that we use docbook
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.



-- 
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