HTML Documentation... Was: RE: Eclipse, eclipsenetrexx and Windowbuilder

[Dave Woodman]

Bill wrote thusly:-

"I think well done HTML versions of the documents would be very useful, and
that the Open Document Format is more appropriate than Latex (originally
designed for typesetting mathematical equations), but that is just my
opinion.  I'm sure that Latex is wonderful, but who has time to learn it?
I believe that Rene is doing all the documentation and prefers Latex, so
presumably that won't change - a good workman gets to choose his tools :)."

This puts me in mind of TtH - a (La)TeX to HTML converter. Would that fit
the bill, Bill?

        http://hutchinson.belmont.ma.us/tth/

I'll have a play later and see how it does with the relevant docs.

                Dave.

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Mike Cowlishaw]

fwiw .. the source format of the NetRexx documents delivered to RexxLA is Open
Office format (.odt files) .. i.e., plain text XML.  Generated from the original
GML using Rexx (of course).

Unfortunately each translation loses some information (page numbers in
cross-references and keeps in going from GML -> ODT, for example).


Mike

> -----Original Message-----
> Bill wrote thusly:-
>
> "I think well done HTML versions of the documents would be
> very useful, and that the Open Document Format is more
> appropriate than Latex (originally designed for typesetting
> mathematical equations), but that is just my opinion.  I'm
> sure that Latex is wonderful, but who has time to learn it?
> I believe that Rene is doing all the documentation and
> prefers Latex, so presumably that won't change - a good
> workman gets to choose his tools :)."

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[billfen]

Dave, I'll be interested to hear what you discover.

My experience with file conversion programs (PDF, HTML, odf and Latex) has
not been positive.  Latex or odf convert to PDF reasonably well, but just
about every other pairing seems to have problems or doesn't exist.

If there are conversion programs between odf and Latex which can
effectively go Latex (1) -> odf (1) -> Latex (2) -> odf (2) so that Latex
(1) == Latex (2) and odf (1) == odf (2), I would consider the document
source problem solved.

HTML conversions may be OK to generate a single HTML page, but effective
conversions to indexed, multi-page HTML files don't seem to be available.
Note that I said "well done HTML", meaning something more than an HTML file
which is nothing more than a PDF wrapper.

Original email:
-----------------
From: Dave Woodman [hidden email]
Date: Mon, 16 Sep 2013 11:41:36 +0100
To: [hidden email], [hidden email]
Subject: HTML Documentation... Was: RE: [Ibm-netrexx] Eclipse,
eclipsenetrexx  and Windowbuilder


Bill wrote thusly:-

"I think well done HTML versions of the documents would be very useful, and
that the Open Document Format is more appropriate than Latex (originally
designed for typesetting mathematical equations), but that is just my
opinion.  I'm sure that Latex is wonderful, but who has time to learn it?
I believe that Rene is doing all the documentation and prefers Latex, so
presumably that won't change - a good workman gets to choose his tools :)."

This puts me in mind of TtH - a (La)TeX to HTML converter. Would that fit
the bill, Bill?

        http://hutchinson.belmont.ma.us/tth/

I'll have a play later and see how it does with the relevant docs.

                Dave.


--------------------------------------------------------------------
mail2web LIVE – Free email based on Microsoft® Exchange technology -
http://link.mail2web.com/LIVE


_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

For the NRL I did a new translation from GML to LaTeX, which keeps all of the info in the GML. Tagged text is the only way keep consistency, and the text-only format enables us to have more persons editing the the sources. The new versions of the books have contributions by Dave Woodman and Tom Maynard already; other contributions, like Bill's, were easily adaptable. Initially, I was planning to go with ODT, but the not-easily mergeable format made pessimistic locking in version management mandatory, and we managed to lose Kermit's parts on the changed method lookups twice, for example, in the process. Also, editing NRL alone made various versions of libreoffice and open office crash, on mac and linux. Simple things like inserting a page before the start of a chapter in the GUI are an absolute pain; in this respect I even prefer Word, and that is quite some statement coming from me.

ODT being XML is one particular view; one needs the GUI editor to edit it, and editing the XML as text would be much more complicated and a lot less straightforward than editing the GML or TeX tagged versions; I am certain that anyone who casts a look will agree to that.

I have seriously looked into DocBook and its variants, but there are still no freely available processors can that make all parts of a book with the ease that TeX can do it; and then still, the DocBook XML looks more ugly than the TeX tags. I am not sure why the TeX format is looked upon as difficult or having a learning curve by people who can write (sometimes parsers for -), i.e, PL/I; it is not, and it performs consistently; it has solved most problems of page composition and fonts, also the ones the makers of open office did not think about yet; (for example, look at the extremely poor letter spacing in the Open Office generated PDF- it just seems not to pick up the font spacing hinting) its output is aimed for consistent production of high resolution output, where in open office this always remains a guess - look at most of the documentation produced with it. And, I can call and include the output of Rexx programs in the text easier than I can do with BSF4ooRexx.

If you have a look at the source (and I urge you to do so) it will become clear that any of us will be able to contribute to it right away. In my view, there is no role for ODF for the above mentioned reasons.

HTML was never meant to produce books, and has no notion of citations, index, front- and back-matter, and layout and font handling is bolted on using CSS - and poor, and browser-inconsistent. I can see JavaDoc-like documentation for NetRexx, but for books, HTML has no contributing role; there can be conversions, but those will be necessarily much poorer than their sources in both layout and facilities. The are enough converters around, and writing our own would not be too hard either. If someone wants to do work, probably HTML in its role as e-book source would be useful. But then again, look at any e-book and count all the items that still separate them from real books, including the ones in PDF. As even mobile devices are handling PDF perfectly, the need diminishes - the current set of books has the page dimensions adapted for optimal readability on iPad's and other tablets.

best regards,

René.

On 16 sep. 2013, at 14:28, "Mike Cowlishaw" <[hidden email]> wrote:

> fwiw .. the source format of the NetRexx documents delivered to RexxLA is Open
> Office format (.odt files) .. i.e., plain text XML.  Generated from the original
> GML using Rexx (of course).
>
> Unfortunately each translation loses some information (page numbers in
> cross-references and keeps in going from GML -> ODT, for example).
>
>
> Mike
>
>> -----Original Message-----
>> Bill wrote thusly:-
>>
>> "I think well done HTML versions of the documents would be
>> very useful, and that the Open Document Format is more
>> appropriate than Latex (originally designed for typesetting
>> mathematical equations), but that is just my opinion.  I'm
>> sure that Latex is wonderful, but who has time to learn it?
>> I believe that Rene is doing all the documentation and
>> prefers Latex, so presumably that won't change - a good
>> workman gets to choose his tools :)."
>
> _______________________________________________
> Ibm-netrexx mailing list
> [hidden email]
> Online Archive : http://ibm-netrexx.215625.n3.nabble.com/
>

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Rony G. Flatscher (wu-wien)]

On 9/16/2013 3:17 PM, René Jansen wrote:

... cut ...
> And, I can call and include the output of Rexx programs in the text easier than I can do with BSF4ooRexx.
Please elaborate, what your problem is w.r.t. Rexx program output vs Rexx program output using the
BSF4ooRexx external function package?

---

Ad odt vs. Tex: I once wrote my dissertation thesis with LaTex as this was the thing to do in
academia. Having been forced to learn how to create macros, fighting manually underfull and overfull
and the like. TeX IMHO shines in dealing with mathematical formulas (which was the original
motivation for Donald Knuth to create it, in order to not get mistakes introduced into his books by
the typesetters in the early days) and tables. The learning curve to master LaTex such that one
could become able to write macros and understand the implications was extremely high, and I have
forgone using it, if I do not have to (some conferences, magazines prefer Tex-based articles in
certain niches).

Ad ODF (the entire set of standards, of which odt is a part): this is a much, much wider adopted
standard in the meantime (based on the number of users) and there are manyfold editors (including
Word nowadays) available to edit it. It is XML and can be processed with XSLT. A "little"
introduction to the markup of odt would even allow one to edit the XML text directly, given a
structured XML editor at hand. One even could create scripts and macros in ooRexx to interact,
change, add text to ODF files (cf. e.g. <http://wi.wu.ac.at:8002/rgf/diplomarbeiten/>).

If I had a choice, I would use odt for documentation purposes, even though I would be able to use
LaTex as a user (not as a LaTex/Tex programmer anymore, would have to relearn).

---

In this project everyone is free to chose the best set of tools.

Changing from ODF to Tex has been put up to discussion, if I remember correctly, and given the fact
that René took on the burden to update and extend the documentation and the like and communicated,
that he would be more productive with Tex, and no one objected, I feel fine with that decision. As
long as documentation writers are not forced to create macros on their own, the productivity should
be good for them as well. (Should there ever be a need in the future to turn the documentation from
Tex into ODF/XML, there will be some effort needed, but it would be possible and feasible,
especially for a group of fine programmers as can be found on this list.)

---rony

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Mike Cowlishaw]

A tagged format is the 'way to go', to be sure.

On HTML conversion -- yes, I agree it can really only be another output format,
and not as rich as PDF/books.  I have a GML->HTML Rexx program somewhere.  It
produces the HTML options of the manuals at http://speleotrove.com/decimal/, for
example.  The HTML pages are handy for giving somone a direct link to a
particular subsection.

Mike

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Tom Maynard]

Ø  I am not sure why the TeX format is looked upon as difficult or having a learning curve

 

If TeX is found to be that difficult, there are several WYSIWYM editors in addition to plain text (with highlighting) versions.  Wikipedia compares them conveniently.

 

With those, TeX is no more difficult than Word or OpenOffice Writer, but profoundly more capable.

 

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Dave Woodman]

Well, mixed results, but not enough to recommend.

When using the Programmer's Guide as input, I found that page reference
links worked (the page numbers were replaced by "pageref"). In contract, the
TOC was a complete failure. On a positive note the output was "pure" HTML,
so these things could be fixed if anyone had the inclination, patience and
time.

In summary, functional but far from optimal.

        Dave

-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of [hidden email]
Sent: 16 September 2013 13:56
To: [hidden email]
Subject: Re: [Ibm-netrexx] HTML Documentation... Was: RE: Eclipse,
eclipsenetrexx and Windowbuilder

Dave, I'll be interested to hear what you discover.

My experience with file conversion programs (PDF, HTML, odf and Latex) has
not been positive.  Latex or odf convert to PDF reasonably well, but just
about every other pairing seems to have problems or doesn't exist.

If there are conversion programs between odf and Latex which can effectively
go Latex (1) -> odf (1) -> Latex (2) -> odf (2) so that Latex
(1) == Latex (2) and odf (1) == odf (2), I would consider the document
source problem solved.

HTML conversions may be OK to generate a single HTML page, but effective
conversions to indexed, multi-page HTML files don't seem to be available.
Note that I said "well done HTML", meaning something more than an HTML file
which is nothing more than a PDF wrapper.

Original email:
-----------------
From: Dave Woodman [hidden email]
Date: Mon, 16 Sep 2013 11:41:36 +0100
To: [hidden email], [hidden email]
Subject: HTML Documentation... Was: RE: [Ibm-netrexx] Eclipse,
eclipsenetrexx  and Windowbuilder


Bill wrote thusly:-

"I think well done HTML versions of the documents would be very useful, and
that the Open Document Format is more appropriate than Latex (originally
designed for typesetting mathematical equations), but that is just my
opinion.  I'm sure that Latex is wonderful, but who has time to learn it?
I believe that Rene is doing all the documentation and prefers Latex, so
presumably that won't change - a good workman gets to choose his tools :)."

This puts me in mind of TtH - a (La)TeX to HTML converter. Would that fit
the bill, Bill?

        http://hutchinson.belmont.ma.us/tth/

I'll have a play later and see how it does with the relevant docs.

                Dave.


--------------------------------------------------------------------
mail2web LIVE - Free email based on MicrosoftR Exchange technology -
http://link.mail2web.com/LIVE


_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/


_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[billfen]

Tom, I looked at the Wikipedia chart you pointed to.  Of the 36 Latex editors, only 4 were listed as WYSIWYM, and only 2 were free (Fidus - "almost  WYSIWYM" and LyX).  When I have bandwidth and time, I will check them out.

To each his own.  I'm very much in the minority - while most of you see beauty in tagged text, I do not.  I prefer not using last generation technology (i.e. primitive text editors and a jumble of text, arcane tags, macros and other kinds of embedded language), be it Latex, HTML, XML, GML, SGML or whatever.  Been-there-done-that, and it's not how I want to spend my time.  As Rene pointed out, I'd rather spend my time writing a parser than writing a spec to pretty print it.  . 

But don't get me wrong, I'm not dissing those who care about irregular character spacing in PDFs and those kinds of issues.  To the contrary, I genuinely appreciate Rene's dedicated efforts, and I have no objection to his use of Latex since he is doing most of the work.  (But document formatting is just not my thing.) 

On the other hand, I still believe that ODF (or Word) versions of the documents would be more comfortable and familiar for other contributors.  Clearly the bulk of document prep in this world is done with Word, and Latex is apparently more geared for those who care about the proper rendering of square root signs.

Bill

Original email:
-----------------
From: Tom Maynard [hidden email]
Date: Mon, 16 Sep 2013 12:27:51 -0500
To: [hidden email]
Subject: Re: [Ibm-netrexx] HTML Documentation... Was: RE: Eclipse,eclipsenetrexx and Windowbuilder


* I am not sure why the TeX format is looked upon as difficult or having a learning curve If TeX is found to be that difficult, there are several WYSIWYM editors in addition to plain text (with highlighting) versions. Wikipedia compares them conveniently. With those, TeX is no more difficult than Word or OpenOffice Writer, but profoundly more capable.

---

mail2web - Check your email from the web at
http://mail2web.com/ .

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Tom Maynard]

Of the 36 Latex editors, only 4 were listed as WYSIWYM, and only 2 were free

 

That’s unfortunate, because TeXworks ships with TeX Live, and TeXnicCenter is also available.  I’ve tried both, and while I prefer a more “hands on” style, both work perfectly well.

 

while most of you see beauty in tagged text, I do not

 

What do you suppose the “X” in the “DOCX” file extension stands for?  Why, “XML” of course.  Even the newer versions Microsoft Word are crafting tagged text behind the curtains (and Zip’d as well).  Crack open a DOCX file with your archiver of choice and see for yourself.

 

From the DocX website:

 

The docx file format is a completely open standards based file format used natively by Microsoft Office 2007, and the soon to be released MS Office 2010, and with plugins can be used by MS Office 2003, and even MS Office 2000. Other major office software such as Sun StarOffice, the free OpenOffice suite, Abiword, and future versions of Corel Wordperfect are also capable of opening and saving files in docx format.

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Jeff Hennick]

I agree with Bill's sentiments.

I would add to this discussion that the "book" format is of less use to
me compared to a searchable HTML now.  The future, IMHO, will be more
online as the "primary" and paper "secondary."  But that said, I don't
know of any current browser that does a good job of HTML --> paper.  And
trying to make (and keep) a Table of Contents or Index in HTML is a pure
manual mess.

The IBM manuals have been beautiful works.  But also very expensive in
editing and publishing costs.  We need to keep our total "costs" down.  
And our usefulness, and timelessness up.

(I, personally, find PDF to be the worst of them all for working from.  
Although this depends somewhat on how it was constructed. Reformatting
the window to work alongside an editor window is at best nasty.  Copy
and paste of code snippets or larger batches is much easier from HTML &
browser than any of the other formats and special readers.)

TeX appears to be overkill for our application: we have little need for
integral signs or even square roots.

The author should be able to concentrate on the contents, and the reader
to be able to format to his needs.  [My old eyes like a larger font than
many of you younger people.]

For what it is worth:  Open Office, Word, etc. can save in a usable HTML
page, but is is inefficient and inelegant HTML.  But the lower cost of
(multi-) authoring may make it worthwhile.  My vote between those two
would be "open source tools and formats for open source products."

  On 9/16/2013 4:12 PM, [hidden email] wrote:

> Tom, I looked at the Wikipedia chart you pointed to. Of the 36 Latex
> editors, only 4 were listed as WYSIWYM, and only 2 were free (Fidus -
> "almost  WYSIWYM" and LyX).  When I have bandwidth and time, I will
> check them out.
>
> To each his own.  I'm very much in the minority - while most of you
> see beauty in tagged text, I do not.  I prefer not using last
> generation technology (i.e. primitive text editors and a jumble of
> text, arcane tags, macros and other kinds of embedded language), be it
> Latex, HTML, XML, GML, SGML or whatever.  Been-there-done-that, and
> it's not how I want to spend my time.  As Rene pointed out, I'd rather
> spend my time writing a parser than writing a spec to pretty print it.  .
>
> But don't get me wrong, I'm not dissing those who care about irregular
> character spacing in PDFs and those kinds of issues.  To the contrary,
> I genuinely appreciate Rene's dedicated efforts, and I have no
> objection to his use of Latex since he is doing most of the work.  
> (But document formatting is just not my thing.)
>
> On the other hand, I still believe that ODF (or Word) versions of the
> documents would be more comfortable and familiar for other
> contributors.  Clearly the bulk of document prep in this world is done
> with Word, and Latex is apparently more geared for those who care
> about the proper rendering of square root signs.
>
> Bill

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/