Re: [OT] Links to PDF manual

Yes, everyone who does serious math likes LaTeX. But as far as I can tell, that is its
only virtue. I once submitted a paper for an academic publication, and they told me they
wanted it in Tex format; I explained that I no longer programmed in punched cards, and I
no longer formatted documents in non-WYSIWYG editors. I had only superscripts and
subscripts in my paper. Academics love LaTeX because it is free, and like most free
software, I can't afford it (I had to hire a TeX expert back in 1989 because we simply
could not get some features to work. My co-author had to recompile the source because our
600-page book had more cross-references than Tex was designed to support, and more index
entries than Tex was designed to support, and a couple other things; it wasn't helped by
the fact that the Pascal compiler he had to use was buggy).

Remeber that the reason TeX was invented was that no publisher had the technology to
format Knuth's projected third volume, or if they did, to be able to produce a book that
did not cost at least five times what an ordinary book of that era would cost. He was
told that while his other books sold for $30, the one he was proposing would probably have
to sell for $150 to recover the cost of the typesetting.

As far as a "user manual"? I once got an error from TeX, went to the index of the book,
looked it up, and was referred to page N. I read page N. I read page N-1 and N+1.
Nothing. But, as it turns out, there was an *exercise* in which he asked "I just did this
and got the following error. What did I do wrong?" Cute. So I turned to the
answers-in-the-back-of-the-book, and the answer was completely unrelated to what I was
doing. My hired TeX expert had to *read the source code* to figure out what was creating
that error, and it truly had nothing to do with what the TeX book said. Is this a serious
"product"? I don't think so.

A friend, an academic, typeset his Ph.D. dissertation in LaTeX. I pointed out several
serious formatting errors (I was one of the readers for his thesis, last year). He said
"That's just TeX or LaTeX formatting problems, and they are too hard to fix, so I'll just
leave them in the final copy". Is this a serious "product"? When a TeX expert decides
that problems in formatting are too hard to fix, I don't think so.

As far as my paper: it turned out that the publisher could accept RTF files. Nobody had
ever approached the publisher before that with other than TeX. They didn't even
understand that systems other than TeX existed!

PDF, however, is largely user-hostile in terms of documentation. I know this because the
FrameMaker documentation is a PDF file, and it is some of the hardest-to-use documentation
around (I've now done two major books in FrameMaker). Because it cannot reflow text, you
can't have your document and the documentation both up on a single screen and both
readable. PDF files are designed to give the same physical appearance on every device,
and if the device cannot accomodate the text because it has a small window, well, that's
just tough. You can scale, but you can't reflow. PDF files have many roles, but they
have to rank among the worst possible solutions for online help. I use and depend upon
PDF files a *lot*, but their role is limited to those things which you want to print out
on a page, with precisely the same layout on every machine, on every printer. They are
suboptimal for reading.

I once encountered a Web site where all the pages were PDF files. It was nearly unusable
because I had to keep doing horizontal scrolling to read them (for some reason, I couldn't
cause them to rescale, not that I would have been able to read them, being over 50 and
therefore intrinsically "vision-impaired").

I actually pay for the full Adobe PDF support programs, and use them for certain classes
of documents. But if one of my clients came to me with the idea of using TeX and PDF to
produce Help files, I would do my best to talk them out of it. TeX has too much of a
learning curve, and shows no advantage until you start typesetting complex math, and PDF
is too rigid to give the display flexibility that user-friendly help demands.

By the way, I was doing hyperlinked documentation a year before Tim Berners-Lee submitted
his proposal for what became HTML. We delivered hyperlinked documentation as part of the
Personal Composer product. I developed the hypertext viewer, wrote 1300 pages of
hypertext documentation, and used Borland's Sprint product to create the output (calling
the hypertext format I invented a new kind of "printer"). We could have colored and
underlined text (it was text-only) and hyperlinks were highlighted; we used the tab key or
the mouse to move among the hyperlinks. When Sprint failed because we hit some internal
limits, we seriously considered moving to Tex, in which I had written the 600-page user
manual, but it could not be adapted readily. The terminal illness of the owner of the
company ultimately did that project in (we were also working on scanning sheets of music
in instead of having to transcribe them by hand). So I have even evaluated the utility of
Tex as a help-file generator, and found it wanting in another context. My experience with
FrameMaker has convinced me that PDF is not a viable help-file representation.

My ideas for hypertext were based on the Zog system which Alan Newell et. al. had
developed in the late 1970s at CMU. A commercial version of this system (from a company
called "KMS" for Knowledge Management Systems, a lot of ex-CMU Zog project people) was
used to create a hypertext system for the aircraft carrier U.S.S. Carl Vinson in the early
1980s. It had both passive text, forms-filling, and what we would call today "client-side
scripting". One of their critical issues was to allow reflow of the text based on the
size windows chosen by the user of the information. PDF does not allow for this
capability.

So these are not random off-the-wall opinions, they are based on my actual experience.
Programs like TeX are seductive, but you have to evaluate the entire workflow process to
judge their utility. PDF looks cool, if you ignore the reality of help files, which is
that the user may need to see both the file and the program at the same time. The
combination seems deadly.

Note that the ideas of HTML had roots going back quite a distance (and this is one of the
reasons that the idiots who tried to patent hyperlinks in the early 1990s lost the patent,
which had been granted. The ideas had been in the literature for over a decade before
HTML was first proposed!)
joe
On Thu, 09 Apr 2009 06:04:11 -0400, Joseph M. Newcomer <newcomer@xxxxxxxxxxxx> wrote:

So sad. I last used LaTex in 1989, and it had been a horrible experience. I fail to find
the continuing fascination with punched-card software.

PDF is a truly LOUSY way to represent help pages, because they cannot dynamically reformat
to fit the available space.

It sounds like a choice of the worst possible tool to create the worst possible
representation for the information.
joe

On Tue, 07 Apr 2009 12:55:01 -0400, David Wilkinson <no-reply@xxxxxxxxxxxx> wrote:

A bit OT, but..

A few years back I wrote an MFC application for a client, and he wrote an HTML
Help user manual for it using (I think) Doc2Help.

We have recently updated the program and we need to update the manual. My client
is very into LaTeX these days, and so he wants to create the new manual using
LateX and PDF rather than Word and CHM.

He thinks he knows how to do this, but how do I link the program to the
generated PDF file?

Right now the links to the CHM are all done with ::HtmlHelp() with
HH_DISPLAY_TOPIC and a page reference like "Path\xxx.chm::/yyy.htm. I think the
page names yyy are derived from the section names in the original Word document.

Is there some Adobe API for linking to Sections of the PDF document?

Can we do this without using a third party help application?
Joseph M. Newcomer [MVP]
email: newcomer@xxxxxxxxxxxx
Web: http://www.flounder.com
MVP Tips: http://www.flounder.com/mvp_tips.htm
Joseph M. Newcomer [MVP]
email: newcomer@xxxxxxxxxxxx
Web: http://www.flounder.com
MVP Tips: http://www.flounder.com/mvp_tips.htm
.

Loading