Re: [oc] Automatic Core Metrics and Documentation

[Niclas Hedhman <niclas@hedhman.org>]

On Friday 09 May 2003 06:04 am, Tom Hawkins wrote:
> On Friday 09 May 2003 05:07 pm, Niclas Hedhman wrote:

> > Regarding documentation, I would recommend DocBook format, as it is

> I wouldn't recommend DocBook for OC for one reason:  We don't 
> need the generality and
> complexity of DocBook.  But what we do need are specific tags for
> core documentation, such as specifying a core's interface:

I think there are two things being discussed at the same time.
1. Metadata.
2. Documentation.

When I say,"Documentation", I typically refer to "bread text", english, 
written so any normal human being can understand it, so to speak.

Metadata is software term for what engineers say "specification" or 
"datasheet" and so on.

Both are valid in this discussion.

DocBook was recommended only for the "documentation" part above.

The beauty of XML is that you can aggregate (merge) documents, without loosing 
track of what is what.

To define an OpenCore schema (or DTD if you prefer) should also be no problem, 
and these can, as you say, build a lot of HTML content automatically (kind 
of), which would be nice.

> Wiki is a cool idea, but I'm not sure this type of freedom is good for
> OC.  

Ok. Cocoon mentioned above, introduce Wiki recently, and in a matter of weeks, 
the documentation of Cocoon was improved by a magnitude or more. And looks 
really good.

> Therefore, I propose the following:  OC projects enter ALL information
> into an XML document that must adhere to the OcProject.DTD.  This
> includes:
>   - General Information
>   - Project News
>   - Core(s) Documentation
>   - Module Information and Compile/Build Constraints
>   - Testbench Information

It's a good start. Everyone, try not to do everything in one go. Evolutionary 
changes is probably advisable, or things won't take off.

Cheers.
Niclas
--
To unsubscribe from cores mailing list please visit http://www.opencores.org/mailinglists.shtml