Re: How to build new html help on mac?

[Bastian M. <bma...@we...>]

Am 28.02.2011 00:59, schrieb Mojca Miklavec:
> On Sun, Feb 27, 2011 at 22:14, Bastian Maerkisch wrote:
>> On 27.02.2011 00:30, Mojca Miklavec wrote:
>>>
>>> Instead of hyperlinks I get big white squares saying "Missing Plug-in"
>>> and then something that seems like a symlink, but clicking on it
>>> doesn't do anything.
>>
>> The reason for this is probably that this app does not support the ActiveX
>> control which is used for linking. We use so-called K-links, aka a real
>> look-up in the index instead of hard links. This helps in case of ambiguous
>> references (multiply defined targets).
>
> Did you ever notice any link that would return you multiple hits? I
> somehow have a feeling that gnuplot would not even generate a link in
> such cases (or that something weird would happen).

There are a few. Most of them because we currently put both '?' and '=' 
entries in gnuplot.doc into the index.
Try:

awk "/^=|^?/ {key=substr(\$0,2); if (a[key]==1) print \"duplicate:\", 
key; a[key]=1;} " gnuplot.doc | wc -l

It gives 45 duplicates for =|?, 0 for '?' only, and 18 for '=' only. So 
in a strict sense ('?' only) there are really non duplicate interactive 
help entries. But I wanted to make use of the additional index entries. 
And why shouldn't we?

>
> Out of curiosity: why is "image" not a link (not even in other
> documents, not just in chm)?

'image' is a interactive help entry. Which topics miss the link?

>
>> I realize that ActiveX is Windows technology, but so is CHM and this is a
>> standard control of the Windows HTML help workshop.
>>
>> Btw. how widespread is ArCHMock amongst Mac users?
>
> Google code claims 34.000 downloads since 2008 (but there are other
> sources that don't mention any number, like the official apple page
> http://www.apple.com/downloads/macosx/unix_open_source/archmock_vyacheslavzakovyrya.html)
> and there are other readers such as iChm (70.000 downloads since Oct.
> 2009 from Google Code).
>
> I would say that an average user doesn't have it until (s)he stumbles
> upon a document that doesn't come in any other format (and is eager
> enough to search for solutions to read it). I first did that when I
> received a book that only came in that format.
>
> chm is really exposed on windows since that is the default way to get any help.
>
> I'm not sure how many mac users would come to idea to download zip for
> windows, get chm from there and try to open it. On the other hand, I
> don't know how it is implemented on windows, but on mac searching in a
> chm document is very handy&  natural. I would prefer hard links
> myself, but if it has many advantages on windows, it is better to make
> sure that windows users have a better experience.
>

So in fact, it would be rather unlikely that the average gnuplot user 
has a program to view CHM files already installed?
Anyway, there's now a compile time option for hard links, just define 
HTML_HARDLINKS.

> Out of curiosity: what is supposed to happen in terminal when somebody asks for
>> help multiple-times-defined-keyword
> ? How does it decide which one to show? I somehow think that it might
> be much better if links were not defined multiple times, but rather
> properly linked (with 'see also' etc.).
>
>>> (If that bug is fixed I might start using that chm file on mac for
>>> gnuplot help before I manage to create native mac help ... it is much
>>> more useful and easy to read&    search than inline help, in particular
>>> when reading larger portions of help.)
>>>

Ethan asked this already: PDF really is cross-platform. What don't you 
use that?

>>> Just a question: is it a mac-specific thing or does it also happen on
>>> windows that subtopics are missing? For example "Terminal types" has
>>> no text at all and "complete list of terminals" doesn't list any
>>> terminal either. It is true that they are there in "bookmarks", but it
>>> would be very useful to have a list of subtopics with hyperlinks.
>>
>> That is normal. There is not text or table of terminals there.
>
> I know. But there are subtopics. If you type
>> help set
> under linux you will get
>
> Subtopics available for set:
>      angles            arrow             autoscale         bars
>      bmargin           border            boxwidth          cbdata
>      cbdtics           cblabel           cbmtics           cbrange
>      cbtics            clabel            clip              cntrparam
>      colorbox          contour           data              datafile
>      date_specifiers   decimalsign       dgrid3d           dummy
>      encoding          fit               fontpath          format
> Press return for more:
>
> and that list was also present in the old help for windows (from what
> I can remember).
>
>> See gnuplot.pdf or even better gnuplot.doc.
>
> gnuplot.doc contains enough information. But I agree that it is not
> just straightforward to dig it out with C code ...
>

You got a point there. Now included.

Bastian

>> If you want this is an artifact of
>> the fact that we produce printed docs and online help from the same source.
>
> This particular problem can be solved with a few more tricks. (I need
> to figure out how the "online" help for gnuplot is generated.)
>
> Mojca