[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [oc] Automatic Core Metrics and Documentation
I would suggest you flip it around.
Define in XML then "index" with SQL. Then only when an XML doc is added (or
revised) would that doc (and that doc only) be scanned for fields specified
for indexing in the SQL database. A reference to this doc, and not the doc
itself, would be entered into the SQL database. As an optimization, when an
XML doc references another XML doc and if that referenced XML doc is already
indexed then the index operation need only to extract and merge the indexes
of the referenced document.
The only problem I see with this is similar to trying to index what is in
#include files when conditional compilation statements are used. i.e. does
the index reflect all possible configurations or does it reflect a specific
configuration.
Also, if the document repository is made accessible to Google then you could
generate an SQL report listing all the index name and value fields (comment)
with the top-level XML doc link. In this manner a user can find a hit not
only on OpenCores but also on other repositories as well. If they want only
OpenCores references then they can add that to the search line.
Jim Dempsey
----- Original Message -----
From: "Miha Lampret" <mlampret@opencores.org>
To: <cores@opencores.org>
Sent: Monday, May 12, 2003 6:48 AM
Subject: Re: [oc] Automatic Core Metrics and Documentation
> 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
--
To unsubscribe from cores mailing list please visit http://www.opencores.org/mailinglists.shtml