RE: if SGML is so great...

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

Please, don't send HTML emails, I won't elaborate on that.

> -----Original Message-----
> From: Gary Preckshot [mailto:garrell@inreach.com]
> Sent: Tuesday, May 02, 2000 7:57 PM
> To: LDP
> Subject: Re: if SGML is so great...
> 
> I don't give a care whether or not you LIKE sgml, I've given
> reasons why I
> think it's important for the LDP.
> I think it's quite reasonable that LDP uses SGML internally 
> and for document storage. 

You cannot get to SGML from anything else and have it contain real meaning.
It's pointless to convert from other formats to SGML for the reasons that
you use SGML, because none of that content is converted over.  When I write
a document, I put in examples of how you can do something.  If I did that in
HTML, I might have it as a different font, or something else entirely.  How
do I translate that into an SGML <example></example> section?  It simply
can't be done.  Translating documents TO SGML defeats the purpose of SGML.

> These arent' reasons that you
> should
> write in SGML, but reasons that the LDP should use SGML.
> Precisely. 
> You can write documents in any
> format you
> want, but if you want them to be a part of our "core" collection,
> then they
> have to be in a useful format to use, namely, SGML.
> No, I think you've got it backwards. If YOU want new authors 
> to write for the LDP core document collection then YOU 
> (meaning LDP) need to implement converters from popular 
> formats to SGML. Otherwise, stop whining about getting new 
> authors. If you're not going to be hospitable, you reduce the 
> population from which you can choose. 

The Linux Documentation Project provides a service for users, and for
authors.  We provide a website where you can go to find documentation for
ANYTHING that you want to do with Linux.  We provide these documents in
multiple formats, and a good way of getting to them, and a good way of
searching through them.  I don't feel that we're stunting the growth of the
LDP by asking people to write in SGML.  If they want to have a completely
stand-alone document, that's completely ineffective for anything other than
the exact task it was written for, then fine, write the thing in HTML.  If
you want to have one that's useful, stop whining, sit down for 3 hours, and
learn enough SGML to write the document.  I REALLY don't care, except that I
want to make the documentation available for linux as good as, or better
than, for any other operating environment out there.  We ain't there yet.

> If you supply
> us with
> an HTML doc, we'll say here's a new HTML doc, it's going in with
> the rest of
> our HTML docs.
> Fine. For what I want to do, that's quite sufficient.
So do it, and stop whining.  
> For most HOWTOs, if you have to search them, they're too long or 
> too verbose.

How often do you consult a tecnical reference manual?  Say, for example,
you're sitting down in front of your Meridian1 PBX, and you need to know how
to add a phone.  Wouldn't you rather be able to fire up your documentation
looker, and say give me an example of how to create a phone using the
Meridian1 PBX.  It would probably come back with 2 examples, 1 for a digital
phone, and 1 for an analogue phone.  You can do the exact same thing for
something like the IP-MASQ howto.  You say, give me an example of a basic
masquerade script, and it comes back with 2 (or three, soon) examples, 1 for
the 2.0.x kernels, 1 for the 2.2.x kernels, and 1 for the 2.4.x kernels.
It's NOT as uncommon as you seem to think.  

> There isn't much to most HOWTO subjects, and 
> they're mostly very diffuse as to information content. I say 
> that as a reader of HOWTOs, and IEEE reviewer, and an 
> experienced technical author. You can look me up in INSPEC or 
> various technical databases. I'm George G. Preckshot. 

Firstly, I disagree.  I use the HOWTOs all the time, and I find them to not
only have good content, but they're also fun to read.  I've read lots of
"professional" technical documents put out by all kinds of people, and they
are absolutely boring to read, and the information in them is generally
harder to find, and has FAR more tangents and boring stuff stuck in the
middle.  However, using SGML properly, you don't need to read any of the
content that you're looking for.  :)  Thanks,
	Greg


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