gnuplot-beta — Developers and beta testers of new gnuplot code

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

On Mon, Feb 28, 2011 at 18:39, Ethan A Merritt wrote:
> On Monday, February 28, 2011 09:16:55 am Mojca Miklavec wrote:
>> > That sound possible, but it has little to
>> > do with PDF vs HTML vs CHM.
>>
>> Not entirely, but it still kind of does. I cannot use "help something"
>> to open PDF viewer on "(x,y) coordinate of page z".
>
> Try:
>                 ${pdfviewer} mydoc.pdf#page=10
>
> PDF files can have internal anchor points, just like HTML files.

Mac doesn't understand that syntax.

> open -a Skim.app gnuplot.pdf#page=10
The file /tmp/gnuplot/docs/gnuplot.pdf#page=10 does not exist.

(None of my pdf viewers is in PATH.)

There probably is some way to do that with some AppleScript or maybe
synctex, but none of them really elegant.

Mojca

Re: How to build new html help on mac?

[Ethan A M. <sf...@us...>]

On Monday, February 28, 2011 09:16:55 am Mojca Miklavec wrote:
> > That sound possible, but it has little to
> > do with PDF vs HTML vs CHM.
> 
> Not entirely, but it still kind of does. I cannot use "help something"
> to open PDF viewer on "(x,y) coordinate of page z".

Try:
		 ${pdfviewer} mydoc.pdf#page=10 

PDF files can have internal anchor points, just like HTML files.

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

On Sun, Feb 27, 2011 at 22:14, Bastian Maerkisch 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).

On the other hand, clicking on 'rgbimage' link in 'image' page results
in "Selection is not associated with any topics. Please try another
selection." (And the same happens in many other cases.) I doubt that
this is the desirable behaviour. (I have problem opening chm from
external drive, but that is probably unrelated to gnuplot itself and
might have to do with a bug in VMWare.)

The awk command didn't work for me and I didn't take time to write a
script on my own to check where duplicates may be found, so I wasn't
able to try how duplicates work.

Mojca

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

On Mon, Feb 28, 2011 at 17:27, Ethan Merritt wrote:
> On Monday, February 28, 2011, Mojca Miklavec wrote:
>
>> > Ethan asked this already: PDF really is cross-platform. What don't you use
>> > that?
>>
>> 1.) It lacks figures. (Well, there is an option to create PDF with
>> figures. But it works a bit bad. I can send screenshots, but I don't
>> know how to fix the problem in LaTeX. LaTeX is very user unfriendly
>> when it comes to creating floating text around figures.
>
> I find this kind of ironic.  I thought you were the LaTeX guru,

(More ConTeXt than LaTeX. I hated the way LaTeX deals with layout in
general since day one.)

But even if I was a LaTeX guru, this doesn't change the fact that TeX
is very badly suited for this particular job. It is much better with
ConTeXt or LuaTeX (even though not exactly perfect).

> sending me complex instructions about re-installing everything in
> sight that I can't ever seem to get working.  But now you're having
> trouble with something that works out of the box for me.

I does work here too. It is just that it works very very bad.

> So - what's wrong with the document produced by your system using
> the current "make pdffigures" target?  How is it different from
> the pre-prepared one in the distribution?

I need to find the pre-prepared one first to compare. But see the
attachment for a single example (there are many others). Some figures
are fine, but many of them are weird. They:

- overlap with one another (if two figures are close to each other,
the second one will just overlap the first one)
- destroy height of footer (text goes way too low into footer)
- floats take space on next page (where they don't even show up)
- it happens that title stays on previous page and paragraph with
figure starts on next page
- if there is some verbatim code, it overlaps with the figure (see attachment)

- Not to mention that one author of package gnuplot uses is dead and
the other cannot be tracked down; they haven't used any licence at the
time when they wrote the package long ago (and nobody knows how to ask
the author if there is a chance to fix the licence), so the package
used for placing figures is not even available in tex distributions
any more (that is not to say that one cannot fetch it from ctan, but
it is still a bit inconvenient).

Unless there is a strong reason not to (I admit there are advantages
of current approach, but it is simply too buggy), I would prefer to
make the figures span over 70 or 80% of textwidth and make them
centered. In particula if one would use TikZ, text would have to be
slightly bigger.

One could add some macros to header to avoid dependency on picins, but
LaTeX has close-to-zero support for floating text around figures and
any given solution would be a very dirty one.

>> I would like
>> to suggest to switch to TikZ for graphics in the manual, but that is
>> lower on priority list.)
>
> How would TikZ help at all?

By creating nicer plots (with fonts that blend nicer into document for
example). It wouldn't solve the problem I was complaining about.

> I could switch the script to use TikZ
> rather than pdfcairo, but the figures still need to get included
> into the document.

I didn't say that switching terminal would solve the problem of
including floating images.

>> 2.) chm is really handy with its one-page-per-topic structure, it
>> resizes nicely (rewraps text) when I resize the window, it has a very
>> very very user-friendly user interface, better search etc.
>
> Better search than PDF?  Maybe you need to switch PDF viewers.

Maybe searching is not so much different, but resizing and
"one-page-per-topic" are.

I just want to say that CHM viewer is astonishing good for its job
(and displays the contents on mac much nicer than it does on windows -
a bit of an irony ...). It has excellent typography, text rewraps when
I resize the window (major difference) ... and I can search the
content on just the page I'm reading. Not for everything, but for this
particular task it does the job better than PDF, and it does it much
better than the viewer on windows.

> Are you saying that you want an option to compile gnuplot such that
> "help foo" triggers an external viewer rather than invoking the
> internal help system?

Yes.

> That sound possible, but it has little to
> do with PDF vs HTML vs CHM.

Not entirely, but it still kind of does. I cannot use "help something"
to open PDF viewer on "(x,y) coordinate of page z". I need HTML to
create "a mac version of what chm does for windows". And I need HTML
source for that.

Mojca

Re: How to build new html help on mac?

[Ethan M. <merritt@u.washington.edu>]

On Monday, February 28, 2011, Mojca Miklavec wrote:

> > Ethan asked this already: PDF really is cross-platform. What don't you use
> > that?
> 
> 1.) It lacks figures. (Well, there is an option to create PDF with
> figures. But it works a bit bad. I can send screenshots, but I don't
> know how to fix the problem in LaTeX. LaTeX is very user unfriendly
> when it comes to creating floating text around figures. 

I find this kind of ironic.  I thought you were the LaTeX guru, 
sending me complex instructions about re-installing everything in
sight that I can't ever seem to get working.  But now you're having
trouble with something that works out of the box for me.

So - what's wrong with the document produced by your system using
the current "make pdffigures" target?  How is it different from
the pre-prepared one in the distribution?


> I would like
> to suggest to switch to TikZ for graphics in the manual, but that is
> lower on priority list.)

How would TikZ help at all?  I could switch the script to use TikZ
rather than pdfcairo, but the figures still need to get included
into the document.
 
> 2.) chm is really handy with its one-page-per-topic structure, it
> resizes nicely (rewraps text) when I resize the window, it has a very
> very very user-friendly user interface, better search etc.

Better search than PDF?  Maybe you need to switch PDF viewers.
 
> 3.) In reality (in slightly longer run) I want to figure out how to
> create native help for mac. And that one has no way to compare to PDF
> in any way. (I want help window to pop up when I type "help
> something", just like it does on windows.)

Are you saying that you want an option to compile gnuplot such that
"help foo" triggers an external viewer rather than invoking the
internal help system?   That sound possible, but it has little to
do with PDF vs HTML vs CHM.

Re: How to build new html help on mac?

[Allin C. <cot...@wf...>]

In relation to Mojca's project: if the primary gnuplot
documentation were in docbook XML rather than the current ad hoc
format, that would make it easy to convert to pretty much any
format via XSLT.

Admittedly the initial conversion to XML would be expensive in
time, but IMO in the long run it would be more useful than writing
another ad hoc convertor for gnuplot.doc.

Allin Cottrell

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

2011/2/28 Bastian Märkisch wrote:
>
>> 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?

Thanks a lot for explanation.

>> 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'm sorry. I now see that it is completely confusing.

1.) In HTML document (created with the command you pointed me to), I get

    2.14 image
    The `image`, _rgbimage_, and _rgbalpha_ plotting styles all /.../

That is: image is in ugly `quotation marks` instead of being a link or
at least a bold keyword.

    2.22 rgbimage
    See `image`.

which is entirely useless since `image` should be a link here (but
that is HTML, not your CHM file).

2.) In PDF:

    37 Image
    The {\bf image}, {\bf rgbimage}, and {\bf rgbalpha} plotting
styles all /.../

where it would be handy to have hyperlinks to rgbimage and rgbalpha.

    45 Rgbimage
    See image (p. _49_).

which is perfectly ok (includes hyperlink; hyperlinks are marked with "_").

3.) In CHM it is
    image
    The <b>image</b>, _rgbimage_ and _rgbalpha_ plotting styles all /.../
but I have noticed later that you consistently don't provide any
self-links anywhere, so that may be the clue of why I thought the link
was missing. The rgbimage example links to image as expected (I'm
curious to know if it will still link if I try to compile the file
with hardlinks).

> So in fact, it would be rather unlikely that the average gnuplot user has a
> program to view CHM files already installed?

Yes. But it is even more unlikely that he would come to the perverse
idea to download the zip for windows for stealing help from there.

> Anyway, there's now a compile time option for hard links, just define
> HTML_HARDLINKS.

Great, thanks a lot. I will try to figure out how to compile gnuplot
on windows despite some of very bad experiences from the past.

>>>> (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?

1.) It lacks figures. (Well, there is an option to create PDF with
figures. But it works a bit bad. I can send screenshots, but I don't
know how to fix the problem in LaTeX. LaTeX is very user unfriendly
when it comes to creating floating text around figures. I would like
to suggest to switch to TikZ for graphics in the manual, but that is
lower on priority list.)

2.) chm is really handy with its one-page-per-topic structure, it
resizes nicely (rewraps text) when I resize the window, it has a very
very very user-friendly user interface, better search etc.

3.) In reality (in slightly longer run) I want to figure out how to
create native help for mac. And that one has no way to compare to PDF
in any way. (I want help window to pop up when I type "help
something", just like it does on windows.)

>>>> 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.
>
> You got a point there. Now included.

Thanks a lot.

Mojca

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

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

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

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

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

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

> 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

Re: How to build new html help on mac?

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

On 27.02.2011 00:30, Mojca Miklavec wrote:
> 2011/2/26 Tatsuro MATSUOKA wrote:
>> Hello
>>
>> The example of wgnuplot.chm can be obtained in the gnuplot cvs version packages for windows.
>> http://www.tatsuromatsuoka.com/gnuplot/Eng/winbin/
>
> Thanks a lot.
>
> However there seems to be something weird. (I'm using ArCHMock to read
> the chm file. Maybe it is a problem/bug in that application, but I
> didn't have a problem opening any other chm file with the same program
> until now.)
>
> 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).

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?


> I can send a screenshot if needed, but it is probably reproducible on
> any other mac. External hyperlinks are working, just the internal ones
> are broken, but maybe only on macs.

They do work as they should on the target platform, Windows.

>
> (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.)
>
> 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. See 
gnuplot.pdf or even better gnuplot.doc. If you want this is an artifact 
of the fact that we produce printed docs and online help from the same 
source. So there's still room for improvements.

>
>> Perhaps you know that the html help workshop working on windows is required to generate chm format
>> help file.
>> You can use it if you install windows in your Apple PC.
>> (Windows can be installed in the Apple PC.)
>
> Compiling gnuplot on windows is a nightmare (I managed to do it once,
> but without any library included). I have windows installed, but I
> don't want to touch it.

That is just untrue. It's plain easy for bare gnuplot. It took me 15min 
including an install of MinGW using the available Makefile. You find a 
nice explanation of the process on Tatsuro's web page.
>
> I was not interested in compiling the chm file, but in getting just
> the html before it compiles into chm. I would like to use html files
> to create help for Mac.
>
>> Another possible way, you will try to use wine for Mac OS.
>> http://wiki.winehq.org/MacOSX
>>
>> I do not know the html help workshop can be executed in the wine on MacOS.
>
> I don't need or even want wine. All I was looking for were html files.
> But now that you pointed me to a ready chm file, I'm considering using
> it as my main source for gnuplot help, even on a mac, at least until I
> figure out how to compile native osx help.
>
> Mojca
>
> PS: it is really nice to see graphical examples present in help. A
> pitty there are not more of them.

Thanks to Ethan who made the plots in the first place!


Bastian

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

2011/2/27 Hans-Bernhard Bröker <HBB...@t-...>:
> On 27.02.2011 11:33, Mojca Miklavec wrote:
>>
>> 2011/2/26 Hans-Bernhard Bröker<HBB...@t-...>:
>
>>> doc2html.c is similar enough to the existing doc2{something}.c programs
>>> we
>>> already have.  It should build on MacOS, too.
>
>> I have tried, but I don't manage to build it. The best I can do is the
>> following (inside docs/Makefile):
>>
>> doc2html: doc2html.o termdoc.o xref.o
>>   $(LINK) doc2html.o termdoc.o $(LIBS)
>
> Compare this with the compilation rule for doc2html in config/makefile.mgw.
>  You're missing modules version and xref in the link.

I added xref.o now, but I'm missing version.o and I have no idea how
to create a rule for that one.

>>> Why not just use makeinfo on the texinfo rendition of gnuplot.doc?
>>> There's a
>>> ready-made target in docs/Makefile.in for that, already.  Just drop the
>>> --no-split and it'll generate one file per node just fine.
>
>> And what if I want figures as well
>
> Then you're probably in for a rough ride.    With a little coercion, it
> should be possible to convince doc2texi to keep HTML fragments in the
> output, enclosed in @ifhtml for makeinfo, so they end up in the generated
> html.

... or write my own script (substitute doc2texi.el) to create html
files out of gnuplot.doc.

I wanted to build from the existing chm effort, but it seems that it
will be easier to start from scratch.

Thank you,
    Mojca

Re: How to build new html help on mac?

[Hans-Bernhard B. <HBB...@t-...>]

On 27.02.2011 11:33, Mojca Miklavec wrote:
> 2011/2/26 Hans-Bernhard Bröker<HBB...@t-...>:

>> doc2html.c is similar enough to the existing doc2{something}.c programs we
>> already have.  It should build on MacOS, too.

> I have tried, but I don't manage to build it. The best I can do is the
> following (inside docs/Makefile):
>
> doc2html: doc2html.o termdoc.o xref.o
>    $(LINK) doc2html.o termdoc.o $(LIBS)

Compare this with the compilation rule for doc2html in 
config/makefile.mgw.  You're missing modules version and xref in the link.

>> Why not just use makeinfo on the texinfo rendition of gnuplot.doc? There's a
>> ready-made target in docs/Makefile.in for that, already.  Just drop the
>> --no-split and it'll generate one file per node just fine.

> And what if I want figures as well

Then you're probably in for a rough ride.    With a little coercion, it 
should be possible to convince doc2texi to keep HTML fragments in the 
output, enclosed in @ifhtml for makeinfo, so they end up in the 
generated html.

> (and don't want the "previous", "up", "next", even though this second
> one is probably easier than getting images)?

It is.  Makeinfo has the option --no-headers for that.

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

2011/2/26 Hans-Bernhard Bröker <HBB...@t-...>:
> On 26.02.2011 22:45, Mojca Miklavec wrote:
>
>> Would it be
>> possible to get that html-like content somehow, that is the last step
>> before the final chm file is created?
>
> doc2html.c is similar enough to the existing doc2{something}.c programs we
> already have.  It should build on MacOS, too.

I have tried, but I don't manage to build it. The best I can do is the
following (inside docs/Makefile):

doc2html: doc2html.o termdoc.o xref.o
  $(LINK) doc2html.o termdoc.o $(LIBS)

doc2html.o: windows/doc2html.c $(BUILT_SOURCES)
  $(COMPILE) -DALL_TERM_DOC -c $(srcdir)/windows/doc2html.c

gnuplotx.html: doc2html $(srcdir)/gnuplot.doc
  ./windows/doc2html $(srcdir)/gnuplot.doc
$(srcdir)/windows/wgnuplot.html $(srcdir)/windows/wgnuplot.hhc

But it misses version data:

gcc -g -O2 -ObjC -L/opt/local/lib -L/opt/local/lib -L/opt/local/lib
-L/opt/local/lib -L/opt/local/lib -o doc2html doc2html.o termdoc.o
-laquaterm  -framework Foundation -L/opt/local/lib -lz
-lpangocairo-1.0 -lcairo -lpangoft2-1.0 -lpango-1.0 -lm -lfreetype
-lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lglib-2.0
-lintl
Undefined symbols:
  "_gnuplot_patchlevel", referenced from:
      _convert in doc2html.o
  "_parse", referenced from:
      _main in doc2html.o
  "_gnuplot_version", referenced from:
      _convert in doc2html.o
  "_list_free", referenced from:
      _convert in doc2html.o
  "_lookup", referenced from:
      _process_line in doc2html.o
ld: symbol(s) not found
collect2: ld returned 1 exit status
make: *** [doc2html] Error 1

>> Would it be possible to generalize the code to the extent that one
>> would also get one html page per help item when requested?
>
> Maybe you're trying too hard.
>
> Why not just use makeinfo on the texinfo rendition of gnuplot.doc? There's a
> ready-made target in docs/Makefile.in for that, already.  Just drop the
> --no-split and it'll generate one file per node just fine.

And what if I want figures as well (and don't want the "previous",
"up", "next", even though this second one is probably easier than
getting images)?

Unrelated question: why doesn't `image` (for example on rgbimage)
point anywhere?

Thanks,
    Mojca

Re: build breakage without lua?

[Ethan M. <merritt@u.washington.edu>]

On Saturday, February 26, 2011, Allin Cottrell wrote:
> I just did the following in my gnuplot source tree:
> 
> cvs update -d -P
> sh prepare
> configure --prefix=/opt/gnuplot
> make <no errors reported>
> make install
> 
> And got this on the install:
> 
> Making install in share
> make[1]: Entering directory `/usr/src/gnuplot-cvs/share'
> Making install in LaTeX
> make[2]: Entering directory `/usr/src/gnuplot-cvs/share/LaTeX'
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> make[3]: Entering directory `/usr/src/gnuplot-cvs/share/LaTeX'
> make[3]: Nothing to be done for `install-exec-am'.
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
> test -z "" || lua ../../term/lua/gnuplot-tikz.lua style

so far so good, it knows not to try to run lua if it doesn't exist.

> test -z "/opt/gnuplot/share/texmf/tex/latex/gnuplot" || /bin/mkdir
> -p "/opt/gnuplot/share/texmf/tex/latex/gnuplot"
>  /usr/bin/install -c -m 644 gnuplot.cfg ./gnuplot-lua-tikz.sty
> ./gnuplot-lua-tikz-common.tex ./gnuplot-lua-tikz.tex
> ./t-gnuplot-lua-tikz.tex
> '/opt/gnuplot/share/texmf/tex/latex/gnuplot'
> /usr/bin/install: cannot stat `./gnuplot-lua-tikz.sty': No such
> file or directory

But then having not built them, it tries to install them anyhow.
OK. I know how to fix that.

> My last "make install," with CVS as of 2011-01-17, went OK.

Right. But we just replaced the lua terminal with a new version,
and the build process is now somewhat more complicated.

[time passes]
OK. Fixed now.

Re: How to build new html help on mac?

[Allin C. <cot...@wf...>]

On Sat, 26 Feb 2011, Mojca Miklavec wrote:

> I already started writing doc2html script, but if there is code
> that already supports HTML output, it would be preferrable to
> use that one.

As Hans-Berhard said:

cd docs
makeinfo --html gnuplot.texi

This gives you a subdirectory called gnuplot, filled with
per-topic html files and a top-level index.html. No nice pictures
though.

Allin Cottrell

build breakage without lua?

[Allin C. <cot...@wf...>]

I just did the following in my gnuplot source tree:

cvs update -d -P
sh prepare
configure --prefix=/opt/gnuplot
make <no errors reported>
make install

And got this on the install:

Making install in share
make[1]: Entering directory `/usr/src/gnuplot-cvs/share'
Making install in LaTeX
make[2]: Entering directory `/usr/src/gnuplot-cvs/share/LaTeX'
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
make[3]: Entering directory `/usr/src/gnuplot-cvs/share/LaTeX'
make[3]: Nothing to be done for `install-exec-am'.
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "" || lua ../../term/lua/gnuplot-tikz.lua style
test -z "/opt/gnuplot/share/texmf/tex/latex/gnuplot" || /bin/mkdir
-p "/opt/gnuplot/share/texmf/tex/latex/gnuplot"
 /usr/bin/install -c -m 644 gnuplot.cfg ./gnuplot-lua-tikz.sty
./gnuplot-lua-tikz-common.tex ./gnuplot-lua-tikz.tex
./t-gnuplot-lua-tikz.tex
'/opt/gnuplot/share/texmf/tex/latex/gnuplot'
/usr/bin/install: cannot stat `./gnuplot-lua-tikz.sty': No such
file or directory
/usr/bin/install: cannot stat `./gnuplot-lua-tikz-common.tex': No
such file or directory
/usr/bin/install: cannot stat `./gnuplot-lua-tikz.tex': No such
file or directory
/usr/bin/install: cannot stat `./t-gnuplot-lua-tikz.tex': No such
file or directory
make[3]: *** [install-texDATA] Error 1

My last "make install," with CVS as of 2011-01-17, went OK.

The configure script said it couldn't find lua, which is quite
correct, the lua libraries are not installed:

configure:14103: result:   cairo-based pdf and png terminals: yes
configure:14114: result:   lua/TikZ terminal: no
configure:14122: result:   Qt terminal: no (requires C++, Qt >=
4.5)

-- 
Allin Cottrell
Department of Economics
Wake Forest University

Re: How to build new html help on mac?

[sfeam (E. Merritt) <eam...@gm...>]

On Saturday, February 26, 2011, Mojca Miklavec wrote:
> I don't need or even want wine. All I was looking for were html files.
> But now that you pointed me to a ready chm file, I'm considering using
> it as my main source for gnuplot help, even on a mac, at least until I
> figure out how to compile native osx help.
> 
> Mojca
> 
> PS: it is really nice to see graphical examples present in help. A
> pity there are not more of them.

Any particular reason you don't like using the PDF help file?
It has the figures, the hyperlinks, and all that other good stuff
that isn't quite working right in HTML.  The only down-side I know
of is that it's harder to provide an external viewer with a URL
that jumps in to a particular place in the PDF file.  The PDF file
format allows this, but it seems many viewers don't support it.

I spent a lot of time looking for a usable PDF->HTML converter,
but I gave up.  There doesn't appear to be such a thing - just
a few minimal implementations that handle text only and disregard
document structure.

	Ethan

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

2011/2/26 Tatsuro MATSUOKA wrote:
> Hello
>
> The example of wgnuplot.chm can be obtained in the gnuplot cvs version packages for windows.
> http://www.tatsuromatsuoka.com/gnuplot/Eng/winbin/

Thanks a lot.

However there seems to be something weird. (I'm using ArCHMock to read
the chm file. Maybe it is a problem/bug in that application, but I
didn't have a problem opening any other chm file with the same program
until now.)

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.

I can send a screenshot if needed, but it is probably reproducible on
any other mac. External hyperlinks are working, just the internal ones
are broken, but maybe only on macs.

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

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.

> Perhaps you know that the html help workshop working on windows is required to generate chm format
> help file.
> You can use it if you install windows in your Apple PC.
> (Windows can be installed in the Apple PC.)

Compiling gnuplot on windows is a nightmare (I managed to do it once,
but without any library included). I have windows installed, but I
don't want to touch it.

I was not interested in compiling the chm file, but in getting just
the html before it compiles into chm. I would like to use html files
to create help for Mac.

> Another possible way, you will try to use wine for Mac OS.
> http://wiki.winehq.org/MacOSX
>
> I do not know the html help workshop can be executed in the wine on MacOS.

I don't need or even want wine. All I was looking for were html files.
But now that you pointed me to a ready chm file, I'm considering using
it as my main source for gnuplot help, even on a mac, at least until I
figure out how to compile native osx help.

Mojca

PS: it is really nice to see graphical examples present in help. A
pitty there are not more of them.

Re: How to build new html help on mac?

[Tatsuro M. <tma...@ya...>]

Hello

The example of wgnuplot.chm can be obtained in the gnuplot cvs version packages for windows.
http://www.tatsuromatsuoka.com/gnuplot/Eng/winbin/

Perhaps you know that the html help workshop working on windows is required to generate chm format
help file.
You can use it if you install windows in your Apple PC. 
(Windows can be installed in the Apple PC.)

Another possible way, you will try to use wine for Mac OS.
http://wiki.winehq.org/MacOSX

I do not know the html help workshop can be executed in the wine on MacOS.

Reference (Html help workshop download site)
http://go.microsoft.com/fwlink/?LinkId=154968

Regards

Tatsuro

--- Mojca Miklavec  wrote:

> 2011/2/26 Hans-Bernhard Br旦ker <HBB...@t-...>:
> > On 26.02.2011 16:52, Mojca Miklavec wrote:
> >
> >> I don't have enough insight into development internals, this is why I
> >> would like to ask how I could build the new HTML help on mac.
> >
> > I wouldn't bother. &#65533;It's no use on a Mac.
> >
> > It's called "HTML help", but that doesn't mean it's plain old HTML ---
> > Microsoft would never follow any standard but their own. &#65533;The help file
> > built is so-called compressed HTML (*.chm),
> 
> There are Mac viewers for reading chm files, so it is not entirely
> true that the file is useless to Mac users.
> 
> However that is besides the point. (It may be that chm files cannot be
> created under Mac in which case it makes no sense to insist.)
> 
> >> But to start with I would like to know how I can build the new html
> >> help in the first place.
> >
> > On a mac, you quite certainly can't.
> 
> Does the new code generate any HTML-like content at all? Would it be
> possible to get that html-like content somehow, that is the last step
> before the final chm file is created? Would it be possible to
> generalize the code to the extent that one would also get one html
> page per help item when requested? (I already started writing doc2html
> script, but if there is code that already supports HTML output, it
> would be preferrable to use that one.)
> 
> Thanks,
>     Mojca
> 
> ------------------------------------------------------------------------------
> Free Software Download: Index, Search & Analyze Logs and other IT data in 
> Real-Time with Splunk. Collect, index and harness all the fast moving IT data 
> generated by your applications, servers and devices whether physical, virtual
> or in the cloud. Deliver compliance at lower cost and gain new business 
> insights. http://p.sf.net/sfu/splunk-dev2dev 
> _______________________________________________
> gnuplot-beta mailing list
> gnu...@li...
> https://lists.sourceforge.net/lists/listinfo/gnuplot-beta
> 

Re: How to build new html help on mac?

[Hans-Bernhard B. <HBB...@t-...>]

On 26.02.2011 22:45, Mojca Miklavec wrote:

> Does the new code generate any HTML-like content at all?

Of course it does.  That's what docs/windows/doc2html.c is doing.

But the HTML this generates isn't really meant for any other use except 
as input to the HTML Help compiler.

> Would it be
> possible to get that html-like content somehow, that is the last step
> before the final chm file is created?

doc2html.c is similar enough to the existing doc2{something}.c programs 
we already have.  It should build on MacOS, too.

> Would it be possible to generalize the code to the extent that one
> would also get one html page per help item when requested?

Maybe you're trying too hard.

Why not just use makeinfo on the texinfo rendition of gnuplot.doc? 
There's a ready-made target in docs/Makefile.in for that, already.  Just 
drop the --no-split and it'll generate one file per node just fine.

Re: How to build new html help on mac?

[Mojca M. <moj...@gm...>]

2011/2/26 Hans-Bernhard Bröker <HBB...@t-...>:
> On 26.02.2011 16:52, Mojca Miklavec wrote:
>
>> I don't have enough insight into development internals, this is why I
>> would like to ask how I could build the new HTML help on mac.
>
> I wouldn't bother.  It's no use on a Mac.
>
> It's called "HTML help", but that doesn't mean it's plain old HTML ---
> Microsoft would never follow any standard but their own.  The help file
> built is so-called compressed HTML (*.chm),

There are Mac viewers for reading chm files, so it is not entirely
true that the file is useless to Mac users.

However that is besides the point. (It may be that chm files cannot be
created under Mac in which case it makes no sense to insist.)

>> But to start with I would like to know how I can build the new html
>> help in the first place.
>
> On a mac, you quite certainly can't.

Does the new code generate any HTML-like content at all? Would it be
possible to get that html-like content somehow, that is the last step
before the final chm file is created? Would it be possible to
generalize the code to the extent that one would also get one html
page per help item when requested? (I already started writing doc2html
script, but if there is code that already supports HTML output, it
would be preferrable to use that one.)

Thanks,
    Mojca

Re: How to build new html help on mac?

[Hans-Bernhard B. <HBB...@t-...>]

On 26.02.2011 16:52, Mojca Miklavec wrote:

> I don't have enough insight into development internals, this is why I
> would like to ask how I could build the new HTML help on mac.

I wouldn't bother.  It's no use on a Mac.

It's called "HTML help", but that doesn't mean it's plain old HTML --- 
Microsoft would never follow any standard but their own.  The help file 
built is so-called compressed HTML (*.chm), I'm not aware of that being 
usable in anything but the Windows HTML help viewer.

> But to start with I would like to know how I can build the new html
> help in the first place.

On a mac, you quite certainly can't.

How to build new html help on mac?

[Mojca M. <moj...@gm...>]

Dear list,

I don't have enough insight into development internals, this is why I
would like to ask how I could build the new HTML help on mac. (In the
long run Mac could also use HTML help instead of inline help in
terminal, depending on user configuration. But for that one would need
one-page-per-help-request as opposed to a single huge HTML file, so
that I could say "help term postscript" and get just the HTML page
describing postscript terminal.)

But to start with I would like to know how I can build the new html
help in the first place. I somehow see that there is
    -../src/$(TARGET) -e "winhelp=1" $(D)plotstyles.gnu
in makefile for windows, but I cannot call that makefile from osx. There is also
    docs/plotstyles.gnu:if (winhelp==1) out = "./windows/"
but I'm not sure if name "windows" is in the place. HTML files are
much more generic than just for windows. As I said, there is a great
chance that Mac OS X could use them as well (if some skilled mac
developer steps forward and tells how to proceed).

I would only like to ask for instructions for building the help
(ideally being available out-of-the-box as a target in Makefile), and
maybe to rename "windows" to something more generic/html-ish. The
final file is only for windows of course, but the HTML files are more
generic.

Mojca

Re: funny behavior at making wgnuplot.chm on mingw from cvs source

[Tatsuro M. <tma...@ya...>]

Hello 

Perhaps what I met concerning '-' was environmental dependent.
Using PC in my home (win XP 32 bit), '-' worked as Hans and you explained.
The funny behavior for '-' was happened at PC in the University (win 7 64bit).

I will confirm at university on Monday.

Thank you for detailed explanations.

Regards

Tatsuro 


--- Bastian Maerkisch  wrote:

> Just an explanation why the '-' is there: to create the images for html 
> help we need the png(cairo) terminal. And I don't include cairo nor 
> libgd in my MinGW builds right now. But it is puzzling why this would 
> stop your make from working.
> 
> Assuming make is irritated by the relative path, you could try to define
> 	GNUPLOTEXE = ../src/$(TARGET)
> end replace the offending line by
> 	-$(GNUPLOTEXE) -e "winhelp=1" $(D)plotstyles.gnu
> Just a wild guess, though. Could you please tell us the exact error 
> message?
> 
> Bastian
> 
> On 26.02.2011 07:26, Tatsuro MATSUOKA wrote:
> >
> >
> > --- Hans-Bernhard Brセュ．稾er<HBB...@t-...>  wrote:
> >
> >> On 24.02.2011 22:12, Tatsuro MATSUOKA wrote:
> >>>>> -	-../src/$(TARGET) -e "winhelp=1" $(D)plotstyles.gnu
> >>>>> +	../src/$(TARGET) -e "winhelp=1" $(D)plotstyles.gnu
> >>>
> >>> -../src/$(TARGET)
> >>> '-' before ../src/$(TARGET) gives error in my make system.
> >>
> >> Then maybe your make system must be broken beyond repair.  'make'
> >> implementations do have their differences from each other, but
> >> prepending '-' to mean "ignore error states from the following command"
> >> is almost universally valid.
> > Character '-' is not recognized. The line expanded -../src/....... . The character '-' is
> remained and
> > gives error.
> >
> >> You didn't way: what error does that give, anyway?
> >>
> >>> I think it should be corrected.
> >>
> >> Like I said before, there is nothing wrong with that line, thus nothing
> >> to be corrected.
> > OK. I will make my local temporal patch to avoid 'make' bug.
> >
> > Thanks for the instruction.
> >
> > Regards
> >
> > Tatsuro
> >
> > ------------------------------------------------------------------------------
> > Free Software Download: Index, Search&  Analyze Logs and other IT data in
> > Real-Time with Splunk. Collect, index and harness all the fast moving IT data
> > generated by your applications, servers and devices whether physical, virtual
> > or in the cloud. Deliver compliance at lower cost and gain new business
> > insights. http://p.sf.net/sfu/splunk-dev2dev
> > _______________________________________________
> > gnuplot-beta mailing list
> > gnu...@li...
> > https://lists.sourceforge.net/lists/listinfo/gnuplot-beta
> 
> -- 
> Dr. Bastian M将」rkisch
> Physikalisches Institut, Universit将」t Heidelberg
> Philosophenweg 12
> 69120 Heidelberg
> Tel.: +49-6221-549214
> Fax: +49-6221-549343
> 

Re: funny behavior at making wgnuplot.chm on mingw from cvs source

[Tatsuro M. <tma...@ya...>]

--- Hans-Bernhard Br将モker <HBB...@t-...> wrote:

> On 24.02.2011 22:12, Tatsuro MATSUOKA wrote:
> >>> -	-../src/$(TARGET) -e "winhelp=1" $(D)plotstyles.gnu
> >>> +	../src/$(TARGET) -e "winhelp=1" $(D)plotstyles.gnu
> >
> > -../src/$(TARGET)
> > '-' before ../src/$(TARGET) gives error in my make system.
> 
> Then maybe your make system must be broken beyond repair.  'make' 
> implementations do have their differences from each other, but 
> prepending '-' to mean "ignore error states from the following command" 
> is almost universally valid.
Character '-' is not recognized. The line expanded -../src/....... . The character '-' is remained and
gives error. 
 
> You didn't way: what error does that give, anyway?
> 
> > I think it should be corrected.
> 
> Like I said before, there is nothing wrong with that line, thus nothing 
> to be corrected.
OK. I will make my local temporal patch to avoid 'make' bug.

Thanks for the instruction.

Regards

Tatsuro