discuss: Thread: Linuxdoc AND Asciidoc support was [Re: progress update: 1. automation of source to output publication]

Hello and good evening David,

[I will respond about the automation/Lampadas question under 
separate cover.]

>> I tried the AsciiDoc tools against plain text, and they just work.
>> Thus, if we get a plain text submission, we can add the minimum markup
>> required to turn the document into a valid (structured) AsciiDoc format.
>> This lowers the bar for markup/document authoring and separates the
>> important content question from the language/format question.  (We
>> should be able to spend our time focusing on the high quality content,
>> not the opening/closing tags.)
>
>I was going to suggested the same for linuxdoc.  The markup to be
>submitted would be:
>------------------------------------------------------------------------
><title> Serial HOWTO
><author>David S. Lawyer, ####@####.#### 
><date> v2.28 July 2015 
>
><sect>Introduction
>The serial port, while obsolete on ...
>
><sect> ... Use blank lines to separate paragraphs.  Perhaps garble 
>the email to help avoid getting spam. 
>____________________________________________________________________ 
>Then a script is used by LDP to create a valid linuxdoc file: by 
>enclosing the submission in <article> </article> tags and then 
>adding the LinuxDoc DTD statement <!doctype linuxdoc system> on 
>line one.  Also a <p> (paragraph> tag must be added by the script 
>to the start of first line of each section.  One can make a vim 
>script to do this by editing an actual file in vim (an editor) and 
>recording the edit for reuse as a script (a feature of vim).  A sed 
>script would perhaps be a fraction of a second faster. The standard 
>tools for processing LinuxDoc adds closing tags to all the other 
>tags shown above and the author is seldom aware of this "internal" 
>finding of omitted tags.

This is great!  I think it is quite good that we will be able to 
support two distinctly different low-barrier-to-entry documentation 
languages, Linuxdoc and Asciidoc.

I would say:

  * Author choice.
  * Or volunteer choice.

This makes me quite happy.

[And, yes, I realize I still have to finish the work to get Asciidoc 
supported in an automation tool.]

>> In my travels over the last few weeks, through the wilds of Doculandia,
>> I examined the toolchain for AsciiDoc (asciidoc and a2x, specifically),
>> and I have come to the conclusion that we can easily support AsciiDoc,
>> as well.
>> 
>I once looked at AsciiDoc and concluded that LinuxDoc was just as 
>easy to learn/use.

Agreed!  Having learned both, they are both easy to write, read and 
understand.

>The AsciiDoc manual is huge compared to LinuxDoc but AsciiDoc has 
>better support for images and supports utf-8.

Agreed, also.

If we were comparing these two documentation formats as biological 
organisms, we could say that Asciidoc has the (non-trivial) benefit 
of inheriting the lessons of its great-great-great-uncle, SGML and 
many other text-processing tools.  Asciidoc came into a world where 
Unicode was already present.  Linuxdoc, on the other hand, is a 
direct child of SGML.  Therefore, it is not a surprise about the 
better support for Unicode in Asciidoc.

Image handling doesn't seem tricky at all in either Asciidoc or 
Linuxdoc, so I'm not quite sure what you mean as 'better' there, but 
it is probably immaterial.  These are both simple to learn and use.

>But wiki markup may be easier than either AsciiDoc or LinuxDoc.
>
>Am I correct that there are barriers to validating a wiki markup 
>off-line? Does one need to install a wiki system on their home PC 
>and then use it for writing wiki docs offline?

Good question.  I have no idea.  I have not touched the wiki markups 
at all.  They do not seem generally popular outside of the web 
frameworks that use the markup languages.

Given that Asciidoc and reStructuredText are popular documentation 
formats in the software documentation world, I started with these.  
Asciidoc seems a bit more well-suited for standalone documentation 
than RST, although I'll spend some more time with RST in the future.

Anyway, if anybody has strong suggestions, opinions or arguments on 
wiki languages, reStructuredText or others, I'm open to learning 
more.

>> I hereby commit to extending 'ldptool' to support AsciiDoc, in the same
>> way that I added support for DocBook 5.0.  See following...
>> 
>> Again, all of this is in the service of encouraging high quality
>> documentation.  It matters so little what the chosen markup language or
>> text format is.  If the content is good and the license is compatible,
>> let's take it.
>
>However, the markup becomes important when a an new potential 
>author considers taking over a doc.  If the markup is not familiar 
>and/or takes a non-trivial effort to learn (or use), the potential 
>author may not volunteer to take it over.

And, this is also true and a component of the decision-making 
process we should not forget.  This is a great argument for having a 
few low-barrier-to-entry documentation formats.

We cannot ever know what format will be familiar to any author (or 
possible future author).

Therefore, in conclusion, I would assert the following:

  TLDP should defer to the new submitter, the current author or the 
  document maintainer in terms of document format choice.

Let's spend our time worrying about licensing and content.  Let's 
spend less time on the choice of supported formats.  Automation 
should take care of that and enable a decrease of friction between 
the author's correction/submission and publication.

After all, it is the author (or maintainer) who is investing the 
time in the work, and who reaps the benefit when the document is 
publicly visible.

-Martin

-- 
Martin A. Brown
http://linux-ip.net/