:: Re: [DNG] Documentation format phil…
Etusivu
Poista viesti
Vastaa
Lähettäjä: KatolaZ
Päiväys:  
Vastaanottaja: dng
Aihe: Re: [DNG] Documentation format philosophies
On Sun, Nov 12, 2017 at 09:35:09PM -0500, Steve Litt wrote:
> On Sun, 12 Nov 2017 00:39:34 +0100
> Svante Signell <svante.signell@???> wrote:
>
> > On Sat, 2017-11-11 at 13:33 -0500, Steve Litt wrote:
> > >
> > > >  We use LaTEX in technical documents, 
> > >
> > > LaTeX is wonderful *for what it does*, which is make beautifully
> > > typeset documents whose linefeeds are determined at compile time,
> > > not at read time (like ePub, HTML or Xhtml). The problem is that
> > > you can't reasonably convert LaTeX to XML, HTML, Xhtml or the
> > > like.
> >
> > Ever heard about latex2html?
>
> Tell me more about it. Have you used it to convert a significant LaTeX
> document to HTML? If so, was it real, semantic HTML, or did the system
> do early style to appearance conversions? Do you think the resulting
> HTML would be reasonable input to an ePub creation process?
>



The whole discussion seem to have a little point to me. HTML is not
"semantic" at all. So the only way you can convert a LaTeX document
into HTML is by trying to match in HTML the visual style that LaTeX
would have used to render the document. And the result will be lousy,
as many others have pointed out, since LaTeX is a professional
typesetting system meant for high-quality paged media, while HTML is a
badly-designed, unstructured markup language.

I am convinced that there is no single *perfect* way to write
documentation, and that, unfortunately, different source formats are
needed for documents with different purposes. I would never write a
manpage in LaTeX or XML (actually, I would never write anything in
XML, but that's another story) as I would never write a scientific
paper in anything else than LaTeX. But I have done both things, at
times, and even worse things with docs that I won't mention here :)

The result is that, IMHO, the utopia of "write once, deliver in
whatever format will come in the next 20 years" is doomed to remain an
utopia. And complicating things to impossible levels using XML is not
gonna help at all.

I thing stuff like markdown and orgmode are more than fine for most of
the manpage-wiki-tutorial-and-the-likes documentation, but you can't
get much of eyecandies with them.

As with programming languages, the only reasonable way to cope with
document formats is probably to learn as many formatting systems as
possible, and to use "the right one" for each task.

My2Cents

KatolaZ

-- 
[ ~.,_  Enzo Nicosia aka KatolaZ - Devuan -- Freaknet Medialab  ]  
[     "+.  katolaz [at] freaknet.org --- katolaz [at] yahoo.it  ]
[       @)   http://kalos.mine.nu ---  Devuan GNU + Linux User  ]
[     @@)  http://maths.qmul.ac.uk/~vnicosia --  GPG: 0B5F062F  ] 
[ (@@@)  Twitter: @KatolaZ - skype: katolaz -- github: KatolaZ  ]