Re: [oc] Automatic Core Metrics and Documentation

[Tom Hawkins <tom1@launchbird.com>]

On Monday 12 May 2003 06: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.

I think it would be convenient to combined metadata and documentation 
into a single document.  The tools would then extract the appropriate 
information when generating webpages, pdfs, or database entries for 
searching.  For example, each project would consist of a collection 
of cores; each core looking something like:

<core>
  <core_name>Some Core</core_name>
  <cvs_location>some_core</cvs_location>
  <version>0.1.3</version>
  <license_type>BSD</license_type>
  <core_language>Verilog-2001</core_language>
  <core_language>VHDL</core_language>
  <core_dependencies>
    <cvs_location>some_other_core</cvs_location>
    <cvs_location>yet_another_core</cvs_location>
  </core_dependencies>
  <core_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"/>
  </core_interface>
  <core_documentation>
    <!-- Docs goes here. -->
  </core_documentation>
</core>

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.

Of course, "bread text" tags would be used at other places in the XML, 
such as for general project information.

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


-- 
Tom Hawkins
Launchbird Design Systems, Inc.
952-200-3790
tom1@launchbird.com
http://www.launchbird.com/


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