[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [oc] Automatic Core Metrics and Documentation
On Monday 12 May 2003 05:52 am, Tom Hawkins wrote:
> On Monday 12 May 2003 06:16 pm, Niclas Hedhman wrote:
> Inside <core_documentation> is where you would find the "bread text"
> with standard tags for chapters, sections, paragraphs, lists, tables,
> hyper-links, program listings, etc. This could be flow-blown
> DocBook, but I think that's overkill. The simpler the better. Then
> maybe in the future we could as tags to automatically generate block,
> state-transition, and waveform diagrams.
There is a reasonable Simple-DocBook, a subset, which I, for instance, use for
my needs. One of the reasons to support DocBook, is that one can expect more
tools to come out around it, such as OpenOffice 1.1.
> > The beauty of XML is that you can aggregate (merge) documents,
> > without loosing track of what is what.
>
> Can you give me an example of what you mean by this, and how it would
> relate to OC? I'm by no means an XML expert.
Ok, there are many technologies available to do the "aggregation" itself, but
fundamental for it to work is Name Spaces. The Name Space separates parts of
the document for each "processing unit" so it can ignore "the other stuff".
A small example;
An OC project file.
<?xml version="1.0" ?>
<core xmlns="http://www.opencores.org/OpenCoreProject/1"
name="UART16550">
<version>1.0</version>
<!--- All the stuff --->
</core>
My own stuff...
<?xml version="1.0" ?>
<core xmlns=""http://www.bali.ac/Hardware/Cores/1"
name="ShiftReg96"
<version>1.0</version>
</core>
Merging two documents with XInclude;
<?xml version="1.0" ?>
<whatever
xmlns:bali=""http://www.bali.ac/Hardware/Cores/1"
xmlns:oc="http://www.opencores.org/OpenCoreProject/1"
xmlns:xinclude="http://www.w3.org/tr/xinclude"
xmlns="http://www.whatever.org/whatever"
>
<xinclude:include href="uart16550.xml" />
<xinclude:include href="ShiftReg96.xml />
</whatever>
Then the resulting document would be;
<?xml version="1.0" ?>
<whatever
xmlns:bali=""http://www.bali.ac/Hardware/Cores/1"
xmlns:oc="http://www.opencores.org/OpenCoreProject/1"
xmlns="http://www.whatever.org/whatever"
>
<oc:core name="UART16550">
<oc:version>1.0</oc:version>
<!--- All the stuff --->
</oc:core>
<bali:core name="ShiftReg96"
<bali:version>1.0</bali:version>
</bali:core>
</whatever>
And if you fed this document into a XML processor (XSLT for instance) that
only understand the OpenCoresProject namespace, it will only process the
oc:xxx tags and ignore the rest. (The prefix on tags can be used at attribute
level as well.)
NOW, this may seem trivial, but it is not. Again, I want to illustrate with an
example. I modify your proposed example;
<core
xmlns="http://www.opencores.org/OpenCoreProject/1"
xmlns:xinclude="http://www.w3.org/tr/xinclude"
>
<name>uart16550</name>
<cvs_location>/cores/uart16550</cvs_location>
<version>0.1.3</version>
<license_type>BSD</license_type>
<language>Verilog-2001</language>
<language>VHDL</language>
<dependencies>
<cvs_location>some_other_core</cvs_location>
<cvs_location>yet_another_core</cvs_location>
</dependencies>
<interface>
<parameter name="bus_width" type="integer"/>
<input name="clock" width="1"/>
<input name="data" width="8"/>
<inout name="bus" width="parametric"/>
<output name="result" width="24"/>
</interface>
<documentation>
<xinclude:include href="toc.xml"/>
<xinclude:include href="intro.xml"/>
<xinclude:include href="architecture.xml"/>
<xinclude:include href="interfaces.xml"/>
<xinclude:include href="license.xml"/>
</documentation>
</core>
And for intro.xml something like;
<?xml version="1.0"?>
<!-- not sure of the official name space ?? -->
<article xmlns="http://www.oasis.org/Simplified DocBook/EN/4.1.2.5
>
<title>UART16550 - Introduction</title>
<para>
This is an OpenCores project for the 16550 UART.
</para>
<section>
<title>Features</title>
<para>
</para>
</section>
<section>
<title>Timing Overview</title>
<para>
<imageobject>
<imagedata fileref="images/timing1.png"
width="300" depth="45" format="PNG"/>
</imageobject>
</para>
</section>
</article>
NOW, when the uart16550.xml is processed, the xinclude is used to link to
another document, but could just as well be DocBook written write there, and
if you have some specialized XML processor for the OC stuff, you just specify
in that processor to only understand the
"http://www.opencores.org/OpenCoresProject" name space, and it will jump the
docbook stuff.
It is harder to explain than to use.... :o)
XSL Tranformer is one very common case it is used, since you interleave the
instructions with the generated result. It wouldn't work without namespaces.
Besides XInclude there are other aggregation methods, <import> in XSL, and
Cocoon for instance is basically tailored to these kind of problems.
RDF, that has been mentioned, uses knowledge about the namespaces to allow for
very advanced searches, classic example; Where you can search for Java (as in
Indonesia) and don't get everything about the programming language or coffee
returned.
I envision that the "User Documentation" (i.e. the DocBook part) is written in
a standard word processor and a simple include link in the Core metadata
document.
Also, note that I changed the <core_name> tag to <name> since we already know
it is a core from the namespace.
Question has also been risen about SQL storage versus XML document, and there
seems to be a consensus that SQL is much faster.
Well, not so at all. The best combination is that XML documents are stored
as-is, and a Indexer (e.g. Google) is used. But Google is not good, since it
doesn't discriminate between content. An RDF capable indexer is prefered,
since you then can search for content within certain tags/namespaces and so
forth.
SQL is slower because then the XML document has to be recreated over and over
again, and that is a rather slow process, comparatively speaking.
ALSO, the XML docs should be part of the CVS, so that versioning of these are
also maintained at all times.
Niclas
--
To unsubscribe from cores mailing list please visit http://www.opencores.org/mailinglists.shtml