Re: [DNG] Documentation format philosophies

2017-11-13 Thread Haines Brown 
On Sun, Nov 12, 2017 at 09:35:09PM -0500, Steve Litt wrote:
> On Sun, 12 Nov 2017 00:39:34 +0100
> 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?

Tried them all, and only one that was successful in most respects was
the lwarp package.

Haines Brown
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Documentation format philosophies

2017-11-13 Thread KatolaZ 
On Sun, Nov 12, 2017 at 09:35:09PM -0500, Steve Litt wrote:
> On Sun, 12 Nov 2017 00:39:34 +0100
> 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  ]


signature.asc
Description: Digital signature
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Documentation format philosophies

2017-11-12 Thread Hendrik Boom 
On Sun, Nov 12, 2017 at 12:13:11PM +0100, Didier Kryn wrote:
> Le 12/11/2017 à 00:39, Svante Signell a écrit :
> >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.
>     First of all, LaTeX is meant to produce paged documents while HTML
> hasn't the notion of a page. latex2html can be used to initiate the
> translation, but you will need to carefully edit the result.

And converting mathematics to images is significantly nonideal.

-- hendrik
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Documentation format philosophies

2017-11-12 Thread Didier Kryn 

Le 12/11/2017 à 00:39, Svante Signell a écrit :

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.
    First of all, LaTeX is meant to produce paged documents while HTML 
hasn't the notion of a page. latex2html can be used to initiate the 
translation, but you will need to carefully edit the result.


    Didier

___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Documentation format philosophies

2017-11-11 Thread Svante Signell 
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?
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Documentation format philosophies

2017-11-11 Thread Haines Brown 
On Sat, Nov 11, 2017 at 01:33:28PM -0500, Steve Litt wrote:
> On Sat, 11 Nov 2017 12:15:44 +

> 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.

Conversion of TeX to HTML etc. is a challenge.

These did not work very well for me:

  $ htlatex universal.tex "xhtml,ooffice" "ooffice/! -cmozhtf" "-coo"
  "-cvalidate"

  $ latex2html source

  $ tex4ht ...

I had better luck with the lwarp TeX package. It stumbled on some
aspects of my TeX document, but that was a year ago, and at that point
it was still under early development. I believe today it does better,
but have not checked.

Haines Brown
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Documentation format philosophies

2017-11-11 Thread Steve Litt 
On Sat, 11 Nov 2017 12:15:44 +
jack da  wrote:

> Steve Litt:  these days I write all my personal documents with
> Leafpad, which adds word-wrap capability to what can be achieved with
> plain text editors ex, nano, etc.

If you include Vim in that list, Vim has at least one Zencoding plugin.
With Zencoding, you can set up a start/end tag pair, with the cursor
resting where you're supposed to type, with one keystroke.
> 
> I discovered that I cannot access the raw MarkDown text of the
> original Alternative Init .. document [copy+paste from the
> talk.devuan.org web site strips the markup directives].  Just as well
> I will write the new paper from scratch.

Markdown,  Asciidoc, and Asciidoctor are wonderful *for what they do*.
They're not a documentation be all and end all.

> 
> I was once fluent in HTML, and XHTML seems to just to be a strict
> version thereof.

Yes. And as far as fluency,  when you use Bluefish, it makes
suggestions for what tags to put and what to put in the tags, making
Xhtml open to the less than fluent.



>  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.

LaTeX is the best around if you know the page size, line width, and
margins at compile time.

> and I can
> quickly become fluent in any sensible markup language [including
> MarkDown].

Yes. Markdown and Asciidoc are dead bang simple.

> 
> The question to ask is:  are the documentation tools widely
> available;  are they open source;  can they be built without many
> dependent packages/libraries?


Let me answer your questions, in the context of the Bluefish editor,
which I think is superior for HTML,  Xhtml, and probably several other
languages:

* Widely available? : Yes. Most distros have a Bluefish package, and
  you can compile the code straight from the Bluefish authors. I had to
  do this when the Void Linux version of Bluefish went bad.

* Open Source? : Yes. GNU General Public License, version 3,  or at
  your option, later.

* Few dependent packaes/libraries? : No. Bluefish has lots of
  dependencies. It's a GUI program useful in many human languages,
  capable of understanding many computer languages. Its realtime
  semi-authoring of code makes it both a huge timesaver and a program
  with serious dependencies. The following is a list of its direct
  dependencies:

===
[slitt@mydesk ~]$ xbps-query -x bluefish
hicolor-icon-theme>=0
desktop-file-utils>=0
xmlcatmgr>=0
python>=0
glibc>=2.8_1
gtk+3>=3.0.0_1
pango>=1.24.0_1
cairo>=1.8.6_1
gdk-pixbuf>=2.22.0_1
glib>=2.18.0_1
libxml2>=2.7.0_1
enchant>=1.4.2_1
gucharmap>=3.0.0_1
[slitt@mydesk ~]$


Unless you've managed to live without GTk all these years, none of
these direct dependencies look particularly harmful to me. As far as I
can tell, no KDE libs, no Gnome libs,  no systemd.

My advice would be to try Bluefish for a couple weeks, then decide
whether to keep it or throw it away and uninstall all auto-installed
packages no longer necessary.
 
SteveT

Steve Litt 
October 2017 featured book: Rapid Learning for the 21st Century
http://www.troubleshooters.com/rl21
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng