RE: Authorship

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

Well, I think I'm coming off as kind of a prick in this email, just don't
take it personally.

> -----Original Message-----
> From: David Lawyer [mailto:dave@lafn.org]
> Sent: Wednesday, June 07, 2000 2:38 PM
> To: Gregory Leblanc
> Cc: ldp-discuss@lists.linuxdoc.org
> Subject: Re: Authorship
> 
> On Thu, Jun 01, 2000 at 02:38:46PM -0700, Gregory Leblanc wrote:
> > As for formats, uhm, scary to open that can again.  Anyway, 
> I think we need
> > to start a review process for NEW documents that could 
> become part of the
> > LDP collection.  They propose writing their doc and all 
> that Jazz on the
> > list, then go write it unless somebody else is/has done so. 
>  When it's done,
> > they send a draft of it to the LDP-Submit list, in 
> Any-Old-Format (tm).
> 
> In "Any-Old-Format" there could be no sections, sub-sections, etc.
> Thus the author needs to subdivide the document into sections and
> subsections, etc. in some logical way.  LinuxDoc forces one to do this
> and is easy to learn so I think that in most cases LinuxDoc (or
> DocBook) should be required.  If something is really good and the
> author will not covert it (but offers it to us) then we need to find
> someone to make the conversion (or help the author do so). 

Obviously, normal structured writing conventions apply, as well as writing
in accordance with established HOWTO structures, the ideas in the template,
and the HOWTO-HOWTO.  I'm ONLY talking about markup here.  I don't think we
should suggest LinuxDoc for anything except for maintenance of old HOWTOs.
I'm looking at an abbreviated XML dtd for DocBook that Norm Walsh has put
together, I'll let you know how things look.  

> > Anybody who has the time and inclination replies to the list, saying
> > that they're going to take a look at the doc.  We give them a few
> > days to take a look and make sure that the document is accurate, and
> > isn't written without punctuation or capitalization.  Any changes
> > proposed by our reviewers should get sent to the author,
> 
> with a CC to ldp-submit.  That way if someone else wants to comment on
> the doc they will know what changes have already been suggested.

Good point, I hadn't thought of that, thanks!

> > and after a few days they can say "ok, I got this feedback from the
> > nice LDP volunteers, and make some changes".  This is the version
> > that will become part of the LDP's collection.  They can submit it
> > in any format for this initial version.  
> 
> Unless we have people ready to convert it, I think it should be in one
> of our sgml formats at this stage.

I think the last posting to ldp-discuss and oswg-discuss lists show that we
do have people ready to convert it.

> > We'll encourage authors to write the DocBook version on their own,
> > but if they decide that they cannot do that, we'll ask LDP and/or
> > OSWG groups for someone to translate that to DocBook.  
> 
> I think that we should at this time let the author choose between
> LinuxDoc and DocBook without prejudice to either format.  I use vim
> and have written macros (called map in vim) for a few tags so I don't
> have to type them.  I guess this is doing it manually.  I noticed that
> LinuxDoc had each paragraph enclosed with start-end tags which would
> make it much more difficult to do manually.  With LinuxDoc you only
> use a paragraph tag at the start of a section (or subsection).  There
> seems to be a lot more tags (and nested ones) in LinuxDoc.

I'm not sure if you've got all the DTD's named correctly here.  I find that
the stricter rules for DocBook with regards to "tag minimization" are much
better.  I'll post one of my old "vents" about tag minimization (that is,
omitting end tags) just after this email.

> Another difficulty with LinuxDoc is that the conversion to plain text
> doesn't use section numbering like 2.13.  This makes the text doc
> difficult to navigate. 

Do you mean DocBook?  I suspect that we can fix these issues without too
much trouble.  I think I even have a message from David Mason (Redhat Labs
and GNOME doc guy) telling how to fix that.  Maybe it was some other
"emulate LinuxDoc output" thing...

> For example, from the table of contents it is
> more difficult to go to a certain sub-section.  Also the section
> headers and subsection headers within the document look the same so
> it's more difficult to navigate.  This is another reason in favor of
> LinuxDoc.  But since DocBook has more features, it's better in other
> ways.  Thus I'm suggesting keeping LinuxDoc for quite a while or until
> DocBook (or a subset thereof) is made almost as simple as LinuxDoc.

Hmm, that shouldn't be hard to fix either.  It should be just recursion in
the stylesheets that we're using to process documents.  I don't really want
to learn DSSSL, but I suppose that I could if nobody else volunteers for
that.  I've got a BUSY summer at work, so this could become something of a
constraint on time.

> > Once the translation is done, it should not be hard for the author
> > to continue to use DocBook for future updates, and they 
> should do so.
> 
> I would ask them first if they want it to be translated to DocBook or
> LinuxDoc.  At present, I want to do my unpdates in LinuxDoc and in
> fact can't do otherwise since my older PC can't cope well with
> DocBook.

I don't think so.  If we're translating them to SGML, it's not that much
more difficult to update DocBook than it is to update LinuxDoc.  Personally,
I think this "machine isn't capable" idea is a silly excuse (no offense
intended).  Debian has good DocBook packages, and Stephanie B... (sorry,
can't spell the whole name) has a good Debian DocBook document on the Debian
website.  For me, I don't EVER use any of the tools to convert my work into
HTML, at least not for the stuff that I've modified for the LDP, or for the
GNOME project.  I have the tools installed so that I can use the DTD in
Emacs and get validation and syntax highlighting.  When the LDP gets our
"work" server online, it will be extremely trivial to get the tools going
EXACTLY the same way that the LDP does.  (Is there anything underway on
this?)  Later,
	Greg


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