Re: if SGML is so great...

[Stein Gjoen <sgjoen@mail.nyx.net>]

Kevin Turner wrote:
> 
> Mr. Preckshot has a point.  There are people, who may be potential
> contributers, who aren't going to care about docbook.  It doesn't matter
> that it's "not that hard" to learn.  Some people simply have other
> priorities.

There are alleged Word-to-SGML converters there, most (trying to)
work by way of RTF. I tried a few but was unsatisfied.

> If you feed them just enough docbook for them to get by, the truth is
> that you're not going to get any of docbook's benefits anyway...  a pile
> of <simpara>'s won't do a whit for your intelligent search engine.  Just
> like everything else, docbook's benefits aren't free.

A simple converter will give you the heading and the paragraph
parts but no useful contents markup.

However, as we are not yet using LinuxDoc features much beyond
simple conversion I feel we have some difficulties in trying to
convince people of the superbness of SGML. My NetHelp effort was
entirely handcoded from HTML though I feel SGML should have been
the optimum source had we had the tools.

> Now I've been up and down Norm's docbook guide, marked up a handful of
> pages of my own, and I still find myself turning again and again to the
> reference to ask "is that tag in this markup language, or the other
> one?"  "Do they have a tag for this exact thing, or do I use a more
> general one?"  "Is this tag depreciated?" etc, etc.  It slows down the
> writing.  So I can understand why someone without the indexing fetish
> wouldn't find it worth their while.
> 
> Solution:
> 
> Fortunately for the spiders and searchers of the world, there are a
> number of people with the indexing fetish who will gladly take a
> plaintext document and put the markup on it for you.  The last time
> someone asked for help with this on the Open Source Writer's Group list
> [1] (I think it was for the "Replacing NT with Linux HOWTO"), no less
> than four volunteers signed up to help with the transition.

I have proposed to start a recruiting frive to help marking up
documents. It is about time to write another column for LWN and
as noone has volunteered I fear I'll have to author a new entry.
That would be an ideal forum for a recruiting drive, as usual
I will submit a draft here first.

> No, it's not optimal having someone do the markup who doesn't understand
> the material as intimately as the author does.  And the author won't get
> off scott free either, e'll probably have to field questions like "Is
> this a system command, or an application name?".  But it sounds like a
> good deal overall.

I have had great difficulties locating valid tags, probably hidden
deep into the docs somewhere on my disks, I don't know.

To add near term benefits I would like a few new(?) tags
 - a command tag with chapter number for Linux commands
  such as "df(1)"
 - a keyword tag for global keywords that will be used
  in for instance metatags in HTML files
 - a file tag that renders to file:///location/of/file in HTML
  and courier in hardcopies

These would also be very useful in automated stub man page
generation.

I would also like to recruit people to help maintain the
existing LinuxDoc tools, hopefully to add these features.

SGMl seems a bit abstract, we to make it clear why it is
useful beyond conversion and we need to start taking advantage
of the features SGML should give us.

Also while I (hopefully) have your attention, I'd like a
spell check tool that checks my text and skips the markup
itself. With ispell I get innundated with every single part
of various URLs.

Regards,
   Stein Gjoen


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