RE: Authorship

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

> -----Original Message-----
> From: David Lawyer [mailto:dave@lafn.org]
> Sent: Friday, June 09, 2000 1:46 PM
> To: Gregory Leblanc
> Cc: 'David Lawyer'; ldp-discuss@lists.linuxdoc.org
> Subject: Re: Authorship
> 
> On Fri, Jun 09, 2000 at 11:36:22AM -0700, Gregory Leblanc wrote:
> > > -----Original Message-----
> > > From: David Lawyer [mailto:dave@lafn.org]
> > > Sent: Friday, June 09, 2000 11:33 AM
> > > To: Gregory Leblanc; ldp-discuss@lists.linuxdoc.org
> > > Subject: Re: Authorship
> > > 
> > [snip]
> > > Actually, the use of minimal tags for DocBook might be a 
> good idea if
> > > it could be made a "standard" and if it's not hard to 
> implement.  But
> > > this is a long-term project (and rather low-priority for 
> the LDP).  So
> > > I'm retracting it with a but ...  My apologies to both 
> Gregory Leblanc
> > > and Gary Preckshot for having to disagree with me on 
> something which I
> > > wrote by mistake.
> > 
> > Can you define "minimal tags"?  I've got no idea what that means.
> 
> What I mean is something like LinuxDoc where one doesn't need tags to
> mark the start and end of paragraphs nor to designate a <Title> after
> say <Sect1>.  You just use double spacing to separate paragraphs and
> anything after say <sect1> is a section title by default (as in
> LinuxDoc).  LinuxDoc avoids the complex nested structures of DocBook.
> Perhaps one can't really make DocBook nearly as simple as LinuxDoc.
> If so, then I think that LinuxDoc needs to be retained for a long time
> until something better comes along.

I happen to think that this is one of the BAD things about Linuxdoc.  I
think that this strictness yields better documents, with modern SGML
editors, it's not difficult, you just say "What can I put here" and it gives
you a list.  You click on one of them, and it inserts the tag.  You put text
there, then close the tag, bingo, you're done.  Sorry, but closing tags and
marking paragraphs is NOT a hardship.  I don't have any really good
arguments for this, except for the on that I posted about tag minimization.
Perhaps somebody else can present a better argument here, but I really do
NOT like those things about LinuxDoc, and I do NOT think that they make it
easier to learn the basics of LinuxDoc than of DocBook.  I learned enough
DocBook to allow me to build a very deep outline using DocBook.  I took a
single application template from the GNOME Documentation Project, and a
single, small application and documented it by filling in the template.  I
posted it once to the list asking for comments, and they corrected me on one
writing convention, and on one markup convention (which happened to be
inconsistent in the template).  I certainly don't consider myself a DocBook
expert at this point, but I learned PLENTY from those two projects to start
writing my own DocBook documents.  Oh, I also read DocBook: TDG beforehand,
but I didn't understand very much of it at the time.  Now I use it as a
reference book.  So, I suppose I spent a few hours learning it, but it's
something that I wanted to do to help out the LDP, and because just about
EVERY Open doc project is using it, with the exception of GNU, and they're
just off in their own little world anyway.

> > What do you think is better about example.sgml than template.sgml?
> 
> For one, template.sgml is 5 times as long as example.sgml.  BTW I
> think that example.sgml could be improved upon and I once started to
> try doing it but didn't finish.  example.sgml tells you to print out
> the sgml source since some people will be reading a formatted
> rendition.  It also tells one that macros (should be tags?) are
> enclosed in angle brackets.  The "license" currently in template.sgml
> is not really a license.  template.sgml fails to explain enough about
> the various tags but talks mostly about what the author thinks the
> content of a HOWTO should include.  This distracts from the main
> purpose of learning LinuxDoc.

Hmm, I see your point.  I do like the idea of a template, in addition to
just example.sgml though.  What do you think about just an essentially blank
template, that is, a document with plenty of the markup in place, some
examples of how to do specific things, but basically just the layout for a
HOWTO?  

> I think that much of the content of template.sgml is good but belongs
> in another document (namely the HOWTO-HOWTO).  Thus I think what we
> need is a major revision on example.sgml.  So if I find time I'll
> continue my work on revising example.sgml (Only about 10% of the task
> is completed so far).

Well, stop slacking off!  :-)  I guess I'll sit down and try to do a
conversion of example.sgml again.  I started it once, but I thought that it
was a very poor document (no offense to the author intended), and needed to
be 80% re-written, especially for use with DocBook.  Later,
	Greg


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