gnuplot-beta

gnuplot.texi missing postscript terminal docs

[Hans-Bernhard B. <br...@ph...>]

Ethan, (or whoever feels up to it), 

please fix the doc sections of term/post.trm such that they make it into
docs/gnuplot.texi (and other files built from it).  It looks like the
driver tries to be too clever, relying on C preprocessing tricks to
generate repeated text blocks, which doc2texi.el can't follow.

-- 
Hans-Bernhard Broeker (br...@ph...)
Even if all the snow were burnt, ashes would remain.

Re: gnuplot.texi missing postscript terminal docs

[Harald H. <h.h...@tu...>]

On Wed, 16 Mar 2005, Hans-Bernhard Broeker wrote:

> Ethan, (or whoever feels up to it),
>
> please fix the doc sections of term/post.trm such that they make it into
> docs/gnuplot.texi (and other files built from it).  It looks like the
> driver tries to be too clever, relying on C preprocessing tricks to
> generate repeated text blocks, which doc2texi.el can't follow.

This was my fault. Unfortunately, I don't have an idea how to fix it.
Should doc2texi.el be extended, or could term/post.trm be changed without
losing the feature of repeated text blocks?

Regards
Harald

-- 
Harald Harders
h.h...@tu...
http://www.harald-harders.de

Re: gnuplot.texi missing postscript terminal docs

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

On Thursday 17 March 2005 10:43 am, Harald Harders wrote:
> On Wed, 16 Mar 2005, Hans-Bernhard Broeker wrote:
> 
> > Ethan, (or whoever feels up to it),
> >
> > please fix the doc sections of term/post.trm such that they make it into
> > docs/gnuplot.texi (and other files built from it).  It looks like the
> > driver tries to be too clever, relying on C preprocessing tricks to
> > generate repeated text blocks, which doc2texi.el can't follow.
> 
> This was my fault. Unfortunately, I don't have an idea how to fix it.
> Should doc2texi.el be extended, or could term/post.trm be changed without
> losing the feature of repeated text blocks?

I have no idea either.  I do not understand the "texi" process at all.
Sorry. Can't help.




-- 
Ethan A Merritt       merritt@u.washington.edu
Biomolecular Structure Center
Mailstop 357742
University of Washington, Seattle, WA 98195

Re: gnuplot.texi missing postscript terminal docs

[Hans-Bernhard B. <br...@ph...>]

Harald Harders wrote:

> This was my fault.  Unfortunately, I don't have an idea how to fix 
> it.  Should doc2texi.el be extended, or could term/post.trm be 
> changed without losing the feature of repeated text blocks?

If you want to keep that feature, you'll have to extend the
functionality of doc2texi.el, or create a work-alike of the C 
preprocessor macro tricks, using TeX or texinfo macros.  OTOH, I don't 
really see why you have to have complete copies of text blocks repeated 
in various terminal driver doc sections, as opposed to just putting in 
references to a single instance.

Re: gnuplot.texi missing postscript terminal docs

[<wie...@we...>]

> > please fix the doc sections of term/post.trm such that they make it into
> > docs/gnuplot.texi (and other files built from it).  It looks like the
> > driver tries to be too clever, relying on C preprocessing tricks to
> > generate repeated text blocks, which doc2texi.el can't follow.
>
> This was my fault. Unfortunately, I don't have an idea how to fix it.
> Should doc2texi.el be extended, or could term/post.trm be changed without
> losing the feature of repeated text blocks?

The attached patch is a proof of concept for an extension of
doc2texi.el.  AFAICS it works.  It calls the preprocessor from within
doc2texi.el.  This could be done somewhat more portable than just
calling "cpp -DTERM_HELP", though.  But I don't know an easy way to
get the values of $(CPP) and $(CPPFLAGS) into the elisp processor
other than through the enviroment (which seems to be quite easy, but
not quite elegant).  How portable should this step be?  Will
gnuplot.info be prebuilt in releases?


Juergen

Re: gnuplot.texi missing postscript terminal docs

[Juergen W. <wie...@fr...>]

> > please fix the doc sections of term/post.trm such that they make it into
> > docs/gnuplot.texi (and other files built from it).  It looks like the
> > driver tries to be too clever, relying on C preprocessing tricks to
> > generate repeated text blocks, which doc2texi.el can't follow.
>
> This was my fault. Unfortunately, I don't have an idea how to fix it.
> Should doc2texi.el be extended, or could term/post.trm be changed without
> losing the feature of repeated text blocks?

The attached patch is a proof of concept for an extension of
doc2texi.el.  AFAICS it works.  It calls the preprocessor from within
doc2texi.el.  This could be done somewhat more portable than just
calling "cpp -DTERM_HELP", though.  But I don't know an easy way to
get the values of $(CPP) and $(CPPFLAGS) into the elisp processor
other than through the enviroment (which seems to be quite easy, but
not quite elegant).  How portable should this step be?  Will
gnuplot.info be prebuilt in releases?


Juergen

Re: gnuplot.texi missing postscript terminal docs

[Hans-Bernhard B. <br...@ph...>]

Juergen Wieferink wrote:

[Please try to stick with one email address --- so I don't have to
manually approve your postings from the "wrong" one, only to find that
you've re-posted them under the correct address in the meantime...]

> The attached patch is a proof of concept for an extension of 
> doc2texi.el.  AFAICS it works.  It calls the preprocessor from within
>  doc2texi.el.  This could be done somewhat more portable than just 
> calling "cpp -DTERM_HELP", though.

It quite probably must be, too.  For starters, the preprocessor isn't
called 'cpp' everywhere, and you'll almost certainly have to provide
some other macros to make *all* terminal help work correctly.

We used to process all terminal drivers through the preprocessor to
create files docs/term.h and docs/allterm.h, until I disabled that
mechanism --- it was causing problems elsewhere.

Having doc2texi.el invoke CPP doesn't exactly seem like the most elegant
solution possible.  But if it works, it's worth a shot.

> How portable should this step be?

As portable as it can possibly be.

 > Will gnuplot.info be prebuilt in releases?

No.  But gnuplot.texi, the direct output of doc2texi.el, will be.

But releases aren't the main point of concern here.  CVS checkins from 
non-GNUish platforms are.  gnuplot.texi itself is contained in CVS 
(although arguably, it shouldn't be), and rebuilt each time gnuplot.doc 
changes (it should be rebuilt if any terminal changes, too, but 
docs/Makefile.in fails to say so).  So a "cvs checkin" without a list of 
files to be checked in (so all new files will be checked in, including 
gnuplot.texi), done from a platform that doc2texi.el fails to run 
properly on could generate some nuisance.  As such, it's rather 
important that doc2texi.el behaves portably.

Re: gnuplot.texi missing postscript terminal docs

[Juergen W. <wie...@fr...>]

On Sunday 20 March 2005 16:09, Hans-Bernhard Broeker wrote:
> [Please try to stick with one email address --- so I don't have to
> manually approve your postings from the "wrong" one, only to find that
> you've re-posted them under the correct address in the meantime...]

I'm sorry.  I realized too late that I used a wrong address.  Then I
resent it with the right address.  I thought about sending you a
note not to put the first message on the list.  Would that have been
a good idea?

> > The attached patch is a proof of concept for an extension of
> > doc2texi.el.  AFAICS it works.  It calls the preprocessor from within
> >  doc2texi.el.  This could be done somewhat more portable than just
> > calling "cpp -DTERM_HELP", though.
>
> It quite probably must be, too.  For starters, the preprocessor isn't
> called 'cpp' everywhere, and you'll almost certainly have to provide
> some other macros to make *all* terminal help work correctly.

Good point.  At first glance: x11.trm needs PM3D and USE_MOUSE...

> > How portable should this step be?
>
> As portable as it can possibly be.

I tried to get the values of $(CPP) and $(CPPFLAGS) from the
autotools into doc2texi.el.  Unfortunately "gcc -E" doesn't work in
this case because gcc doesn't recognize the suffix ".trm".

> Having doc2texi.el invoke CPP doesn't exactly seem like the most elegant
> solution possible.  But if it works, it's worth a shot.

Using CPP indeed seems to be the wrong way.

FYI: The epslatex patch breaks doc2texi.el for two reasons:
1) usage of "#define"s
2) having more then one START_HELP() ... END_HELP() in one file

My patch might still give an idea how to cope with the second one.


Juergen

Re: gnuplot.texi missing postscript terminal docs

[Hans-Bernhard B. <br...@ph...>]

Juergen Wieferink wrote:
> On Sunday 20 March 2005 16:09, Hans-Bernhard Broeker wrote:

> I'm sorry.  

No need to be.

[...]
> a good idea?

Possibly.  The important thing is that this doesn't happen on a regular 
basis.

> I tried to get the values of $(CPP) and $(CPPFLAGS) from the
> autotools into doc2texi.el.  Unfortunately "gcc -E" doesn't work in
> this case because gcc doesn't recognize the suffix ".trm".

You may profit from a look into how allterm.h is built.  Or maybe 
combine the second half of your proposal with using allterm.h right away 
--- that might also solve the maintenance problem of yet another copy of 
the terminal list currently being hardwired inside doc2texi.el.

Re: gnuplot.texi missing postscript terminal docs

[Juergen W. <wie...@fr...>]

On Monday 21 March 2005 20:12, Hans-Bernhard Broeker wrote:
> You may profit from a look into how allterm.h is built.  Or maybe
> combine the second half of your proposal with using allterm.h right away
> --- that might also solve the maintenance problem of yet another copy of
> the terminal list currently being hardwired inside doc2texi.el.

I think the most portable and maintainable way is to use the
functionality of termdoc.c to merge the terminal documentation with
gnuplot.doc.  I named the resulting file "gnuplot.tdc".  This file
is then loaded by doc2texi.el.

Thus doc2texi.el doesn't have to treat the terminals in a special
way (apart from two minor points: the terminal list and some change
in the hierarchy).

I did a quick diff on the resulting gnuplot.texi and could find two
major differences: The sequence of the terminal nodes has changed
and the cross reference detection.

I don't have too much experience with (e)lisp other than this, so it
would be a good idea to have this patch reviewed.  Is anyone in
contact with the original author of doc2texi.el?  Maybe he can even
find a better way to fix the (e)ps(la)tex terminal documention.

Juergen

Re: gnuplot.texi missing postscript terminal docs

[Hans-Bernhard B. <br...@ph...>]

Juergen Wieferink wrote:
> I think the most portable and maintainable way is to use the 
> functionality of termdoc.c to merge the terminal documentation with 
> gnuplot.doc.  I named the resulting file "gnuplot.tdc".  This file is
> then loaded by doc2texi.el.

That doesn't seem to address the issue of which terminals should be
documented in the texinfo documentation.  The philosophy used to be
that online help documents only what the accompanying gnuplot binary
actually supports, but printable docs should document everything.
So far, gnuplot.texi seems to have followed the "include all" strategy,
albeit with some quirks.

You should compile the new doc2tdc.c with -DALL_TERM_DOC, I guess.

> I did a quick diff on the resulting gnuplot.texi and could find two 
> major differences: The sequence of the terminal nodes has changed and
> the cross reference detection.

Erm... the cross reference detection ... did what?

> I don't have too much experience with (e)lisp other than this, so it 
> would be a good idea to have this patch reviewed.  Is anyone in 
> contact with the original author of doc2texi.el?

His mail address mentioned inside doc2texi.el should still work, I guess.

Re: gnuplot.texi missing postscript terminal docs

[Juergen W. <wie...@fr...>]

On Wednesday 30 March 2005 23:15, Hans-Bernhard Broeker wrote:
> That doesn't seem to address the issue of which terminals should be
> documented in the texinfo documentation.  The philosophy used to be
> that online help documents only what the accompanying gnuplot binary
> actually supports, but printable docs should document everything.
> So far, gnuplot.texi seems to have followed the "include all" strategy,
> albeit with some quirks.

I really should have read docs/README.

> You should compile the new doc2tdc.c with -DALL_TERM_DOC, I guess.

Hmm, ... actually I used to compile it with -DALL_TERM_DOC, this got
lost while rewriting the Makefile stuff. :-( But the dependencies
were there! ;-)

> > I did a quick diff on the resulting gnuplot.texi and could find two
> > major differences: The sequence of the terminal nodes has changed and
> > the cross reference detection.
>
> Erm... the cross reference detection ... did what?

Uups.  It changed its behaviour.  The the strings `windows`, `aqua`,
`epslatex`, `gif`, `ggi`, `pdf`, `jpeg`, `fig`, ... are
now detected as cross references, `postscript` is no more.  There
may be quite a lot of reasons for this.  The node naming and cross
referencing code is quite sensible to minor changes in gnuplot.doc.

AFAICS, the new gnuplot.texi is better than the old one.  The latter
had some doubled terminal entrys, some surplus quotes (") at the end
of terminal entrys, ...

Some problems with the naming of the nodes still remain.  I'm
wondering if there could be a nicer way to decide which nodes get 
trailing underscores to make their names unique.


> > I don't have too much experience with (e)lisp other than this, so it
> > would be a good idea to have this patch reviewed.  Is anyone in
> > contact with the original author of doc2texi.el?
>
> His mail address mentioned inside doc2texi.el should still work, I guess.

I'll contact him.


Juergen