Subject:
Re: History of LDP
From:
"Martin A. Brown" ####@####.####
Date:
3 Feb 2016 18:09:22 +0000
Message-Id: <alpine.LSU.2.11.1602030858240.2025@znpeba.jbaqresebt.arg>
Greetings David,
Thank you for your thoughts. You have been here in LDP for a long
time, and it is good to have your contributions.
>> > My view is that we made a big mistake by going with DocBook. Part of this
>> > was my fault for being partially ignorant of the situation along with our
>> > leader, Guylhen, also not understanding it and thinking that one could
>> > simplify DocBook by using only a subset of it. I was somewhat of a coward
>> > for not being more strongly opposed to DocBook.
>>
>> I think it was a good decision those days, but we missed an
>> opportunity to add more languages when it was technically possible.
>> And the biggest opportunity was to join github-like service earlier to
>> replace humans on admin side with robots.
>
>But it's my understanding that LDP had scripts which automatically
>processed submissions.
Sort of. This is where I have made my first efforts. The LDP had
and still has (some of) the scripts. Some are visible here:
https://github.com/tLDP/LDP/tree/master/LDP/builder
See (more) comments on automation below.
>And submission by authors was either via a CVS account or via
>"submit" with no account.
Correct. Remains largely correct. The only real change is that
authors will now send us pull requests via github.com, or patches
via ####@####.#### (BUT please wait, we're not quite ready for
that yet).
<digression>
Mark Komarinski has added a bit to the LDP-Author-Guide about git
(git.xml) and how we will (eventually) be ready to accept patches
via email for those who do not wish to use github.com.
</digression>
>What we needed (and still need is a CMS=Content Management System).
Yes. Agreed. Some sort of management tool would help tremendously.
To my way of thinking, this is one of the problems jdd was tackling
by developing the LDP wiki.
>It would establish categories for how-tos, etc. and a how-to could
>belong to multiple categories. I suggested a number of categories
>such as doc. being maintained but maintainer wants to quit.
Yes. Absolutely.
>Our CMS was to be the plone flavor of zope and David Merrill worked
>on it but became ill before he implemented it for LDP. He said he
>was incorporating most of the code writing he did for LDP into
>Plone but no one else came forward to study it and implement it. It
>was to include wiki editing also.
Unless somebody wishes to take over Lampadas (using Plone), I think
we should reassess what our goals are in choosing some sort of
management system.
>> It's very likely, that with support with one of discuss members
>> who wants to stay anonymous by now, we will be able to fully
>> automatize submission process and add all documentation formats
>> available via pandoc, and there is a huge amount of them:
>> markdown, reStructuredText, textile, HTML, DocBook, LaTeX,
>> MediaWiki markup, TWiki markup, OPML, Emacs Org-Mode, Txt2Tags,
>> Microsoft Word docx, LibreOffice ODT, EPUB, or Haddock markup.
Haddock?! That sounds fishy!
>I see neither linuxdoc nor plain text in the above list.
Multiple formats
----------------
I don't know much at all about pandoc, but if it allows us to
accept documents in more formats, then this is a good thing.
As far as accepted submissions, I'd be inclined to say the
following:
LDP accepts documentation in almost any format, however, we prefer
Linuxdoc, DocBook XML 4.2, __new_format_A__ and __new_format_B__.
Accept any format.
Convert to supported format.
At least one reason for creating documents in a structured markup
language is to enable automated extraction of the structured data.
That's why there has been a proliferation of document formats (and
it is unlikely to stop).
I reach back to the manifesto and assert that, yes, we can accept
high-quality plain text documents.
I would also, volunteer to convert such documents to one of our
supported (more structured) formats. The main point is not to
reject a document because of format.
Automation
----------
While there were tools in our version control system, it was not the
complete toolchain. Others were in Greg Ferguson's working
directory.
As nearly as I can figure (without bothering him directly), the
process went like this:
1. check in submissions to ####@####.#### (if emailed)
2. on document build box, check out document(s) from CVS
3. run ldp_mk (and ldp_cp? (and ldp_index? (and mk_sorted_ht?)))
4. copy into place (or did ldp_cp do that?)
So, the publication process appears to have been partially
automated.
I reconstructed the document handling process by examining both the
contents of the ./builder/ directory and a snapshot of the working
directory from the buildbox. The main script appears to have been
ldp_mk, which produced the various HTML, PDF, PS and text outputs
from the Linuxdoc and DocBook formats (there was no support present
for the WikiText format in this script).
In terms of documentation (on publishing the documentation, heh),
there is text in guide/docbook/LDP-Admin-Guide, from which I learned
very little about the mechanical process of publication. I needed
to read the Perl to understand.
Final comments on the automation issue(s):
While the tools that Greg Ferguson had collected, built, revised and
used for a decade worked, I thought it a good time for review.
* In the years since 2001 (or so) when many of the existing
scripts were written, the platform distributors (think, Debian,
RedHat/Fedora, SuSE/openSUSE) DocBook have made vast strides in
providing solid integration for Linuxdoc and DocBook processing
tools. I wanted to take advantage of these improvements.
* I desire tools that requires a minimum of local customization:
the current tools appear to have lots of hard-coded references
to local/homedir filesystem paths for XSL, DSSSL, SGML handling,
and even htmldoc and html2text tools.
Of course, it worked very well for years. But, rebuilding the
toolchain it on a new server could be (or could have been) a
headache.
* I desire a completely automated system (that can run as a
daemon or from cron or something). An automated system doesn't
go on vacation, which any one of us is likely to do at some
point.
* The existing tools handled not just our submissions, but also
LDPWN (LDP Weekly News), so there would have been some
untangling anyway.
* After the untangling, I suspect that it will be easier (from a
mechanical perspective) to support new documentation formats.
More soon,
-Martin
--
Martin A. Brown
http://linux-ip.net/
