Re: Authorship

[David Lawyer <dave@lafn.org>]

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). 

> 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.

> 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.

> 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.

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.  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.

> 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.

			David Lawyer


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