discuss: LAG changes, multiple formats; DocBook 5.0 was [ My rejected "replacement" for the Author Guide
Subject:
LAG changes, multiple formats; DocBook 5.0 was [ My rejected
"replacement" for the Author Guide
From:
"Martin A. Brown" ####@####.####
Date:
9 Feb 2016 16:37:47 +0000
Message-Id: <alpine.LSU.2.11.1602090824060.2025@znpeba.jbaqresebt.arg>
>>> When I came to LDP in 1998 there was no Author Guide. But there
>>> was a 3-page (printed) learn-by-examples for Linuxdoc and one just
>>> emailed in submissions. A new leader, Lars Wirzenius, in early
>>> 1999 automated submissions and it worked (I used it), but he
>>> resigned due to not wanting to tolerate insults and then no one
>>> continued to implement his (beta) automated submission system.
>>> Under Lars' system, you just emailed to a submit address and sent
>>> your password in the clear. So LDP had simple automatic submission
>>> 17 years ago.
>> Ah, interesting. Neat.
>>
>> That reminds me of the first-generation of tools for whois domain
>> and Internet number resource management. There was an email gateway
>> that would handle change requests. In the late 1990s, this fell by
>> the wayside because of ease of abuse. [Some used cryptographic
>> tools to secure the content and provide authorization, but
>> eventually, web applications and interfaces riding on HTTP
>> supplanted this.]
>
> I started the LAG after trying to figure out how DocBook worked.
> I'll admit my bias towards a cleaner and richer format, but not
> everyone shares my opinion and I'll have to deal with it ;)
I, personally, prefer the richness of DocBook, so I share your
preference. However, I think David's point is right, especially,
since we have heard questions in the past about supporting X, Y and
Z formats. So, yeah, I'll have to deal with it, too! :)
>> I see your point here about separating the process/policy content in
>> the LDP Author Guide from the technical matters, which will differ
>> depending on format and tooling.
>>
>> I'd hate to remove the good DocBook information from the LDP Author
>> Guide, but if we are going to accept multiple formats, it would be
>> good to examine the LDP Author Guide to see where we could
>> de-emphasize DocBook, while retaining the valuable information for
>> those who do choose DocBook.
>>
>> Mark: Any objections to some adjustment of LDP Author Guide along
>> those lines? I'd be happy to volunteer to read, suggest and
>> possibly provide patches, if you would like.
>
> No problem there. It looks like there's a link to the
> 'Howtos-with-LinuxDoc-mini-HOWTO'. Maybe break the various
> acceptance formats into their own HOWTOs and have the LAG link to
> each of those and then document the LDP processes?
That would be great! Especially the part about having a single
output page (location, section, whatnot) that points to all of the
supported formats and the support documentation.
But, see below, also....
> It'll be a lot of work but will allow each person with their own
> their own space to list the features and use of their particular
> format.
I observe that the LDP-Author-Guide contains a great deal of DocBook
specific material in the appendices. So, another option would be to
label each appendix with the formats it discusses.
-Martin
--
Martin A. Brown
http://linux-ip.net/
