Re: .html or .txt doc for Lua 5.2 (was: [ANN] Lua For Windows v5.1.3.7 Public Alpha4 released)

[Gerhard Sittig <Gerhard.Sittig@...>]

On Thu, May 22, 2008 at 14:03 -0300, Luiz Henrique de Figueiredo wrote:
> 
> In Lua 5.2, the whole documentation distributed in the tarball will be
> in HTML: it looks nicer and it allows links, both internal and external.
> May I suggest you move from TXT to HTML as well?

@LHF:  You "promise" to switch the doc which comes with Lua to HTML.
Later you wrote that a plain text version will be available, probably
gotten by means of 'lynx -dump'.  Is it a stupid question to ask which
source the HTML is made from in the first place?

What I have in mind is this:  I assume that you don't (want to) maintain
the doc in the .html format, but instead use some sort of markup
language and get the .html, .txt, .pdf etc formats from there.  Dumping
a .txt file from an .html input file by means of a (screen oriented)
renderer may not result in a text file as nice as getting the text file
from a markup processor.  Text docs need not be the plain pile of ASCII
chars these days, they can have structure and features, too, beyond what
'lynx -dump' could provide.  And having a readable, diffable, editable
_source_ for the doc lowers the entry barrier for contributors and
feedback.  Compare that against someone who needs to tell you where the
.html or .pdf file needs adjusting, instead of just sending a patch ...

Will you use some fullblown doc formatting system like latex, docbook,
or something more lightweight like asciidoc, markdown, or something
else, maybe homegrown?  I assume that very much of the doc is already
there, instead of getting created completely anew ...


virtually yours
Gerhard Sittig
-- 
     If you don't understand or are scared by any of the above
             ask your parents or an adult to help you.