discuss: Thread: LAG changes, multiple formats; DocBook 5.0 was [ My rejected "replacement" for the Author Guide


[<<] [<] Page 1 of 1 [>] [>>]
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/
Subject: Re: LAG changes, multiple formats; DocBook 5.0 was [ My rejected "replacement" for the Author Guide
From: Mark Komarinski ####@####.####
Date: 9 Feb 2016 16:48:48 +0000
Message-Id: <D83BEEB7-E598-4492-9E98-7F539948F801@wayga.org>

> On Feb 9, 2016, at 11:38 AM, Martin A. Brown ####@####.#### wrote:
> 
>> 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.

I’m fine with either.  Having separate HOWTOs gives each person or group their own ‘space’ but those HOWTOs don’t wind up relating to anything Linux related.  Embedding each format into the LAG will make it quite large, but it’s not that much more disk space or pages.

Either way we (I) need to untangle many of the DocBook-isms in the LAG.

-Mark
[<<] [<] Page 1 of 1 [>] [>>]


  ©The Linux Documentation Project, 2014. Listserver maintained by dr Serge Victor on ibiblio.org servers. See current spam statz.