Re: [oc] Automatic Core Metrics and Documentation

[Miha Lampret <mlampret@opencores.org>]

I agree with Tom that Wiki is not suitable for OC because it is impossible to 
have general look for all projects.

XML would be great for project documents but I am not sure if editing of 
project pages as XML documents would be easy enough for developers. Probably 
we need a tool/editor. In my opinion web editing is still best solution 
because it only requires browser and can be done from home, office or 
anywhere. From view of web developer the problem of XML documents is that 
searching through them is very slow in comparison with SQL database. For 
example.. on the first OC page there is a scetion called 'Last updated'. If I 
want to display it dinamically I have to load XML document of each project 
and check LastUpdated tag. Of course this can be done by task running from 
cron but souch things makes development and maintaince of OC web complicated.

My suggestion is that we continue to use SQL database together with XML. First 
step is to define OCProject shema then redefine SQL database structure which 
will be based on schema and implement export to XML, pdf, etc.. (for project 
pages and project documents). I think that for page editing web interface is 
still the best, XML can be used for documentation and other project 
documents.

regards,
Miha

On Monday 12 May 2003 11:16 pm, Niclas Hedhman wrote:

> 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