Re: Documentation Metrics

["Greg Ferguson" <gferg@hoop.timonium.sgi.com>]

On Oct 17,  4:14pm, David C. Merrill, Ph.D. wrote:
> Subject: Re: Documentation Metrics
> *revised, "beta" metrics are at the end of the post*
> [...]
>
> From: "Martin WHEELER" <mwheeler@startext.co.uk>
> > On Mon, 16 Oct 2000, David C. Merrill, Ph.D. wrote:
> >
> > > I am working on the set of metrics to be used in reviewing our
> documents.
> > >
> > > 5. Source Format
> > > - DocBook SGML
> > > - DocBook XML (none currently, I think)
> > > - LinuxDoc SGML
> > > - HTML
> > > - text
> > > - texinfo
> > > - whatever else you find
> >
> > suggestion:
> >
> > 5. Source Format
> >    * SGML - DocBook
> >           - Linuxdoc
> >           - other
> >    * XML  - DocBook
> >           - other
> >    * HTML - 2.0
> >           - 3.2
> >           - 4.0 (strict/transitional)
> >           - 4.01
> >           - other
> >    * text
> >    * texinfo
> >    * other
>
> I will store the file formats using the more hierarchical format
> you show above. It makes sense. However, the distinction in HTML
> dialects is not important to me. Any document whose source is HTML
> will need conversion to DocBook.

Agreed.

> AFAIK, there are no "other" SGML DTDs currently in use. If we find some,
> though, we'll identify them as such.

True; at this point in time.

You could provide a finer level of granularity  to the DocBook
category, such as:

    - DocBook 3.x
    - DocBook 4.x

but then again, I'm not sure if anything would be gained from doing
that. I suppose it might be valuable to track if, in the future, we
ever decide to drop support for, say 3.x. At this time it's virtually
a no-brainer to support/process both DTDs at this point.

> [...]
> 11. Keywords
> These will be used in generating meta-data.

I struggled with this when I did a snapshot of all HOWTOs for the omf.
It came down to parsing the SGML, trying to grab keywords from the
abstract/title area(s) and then reviewing them (by "hand"). With
only 300 HOWTOs this was possible.

If we are in the process of creating a catalog, we might want to try
to tackle this now, and/or put the keyword content back into the
source SGML (so that it can be easily parsed/indexed/etc.).

> ...

This is shaping up nicely.

r,

-- 
Greg Ferguson     - s/w engr / mtlhd         | gferg at sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com/ |
Linux Doc Project - http://www.linuxdoc.org/ | gferg at metalab.unc.edu


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org