Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Bastien]

Hi Paul,

could you share some advice on how to port documentation to
Texinfo 5.0?  I've read your patch, but I'm unable to guess
what is related to this port and what is not.

Thanks for your help!

-- 
 Bastien

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> From: Bastien <bzg@altern.org>
> Date: Thu, 21 Feb 2013 09:14:23 +0100
> Cc: emacs-devel@gnu.org
> 
> could you share some advice on how to port documentation to
> Texinfo 5.0?  I've read your patch, but I'm unable to guess
> what is related to this port and what is not.

I'm not Paul, but I'm guessing he just looked at the warning/error
messages emitted by the new makeinfo and fixed whatever they told
needed fixing.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Paul Eggert]

On 02/21/13 09:25, Eli Zaretskii wrote:
> I'm guessing he just looked at the warning/error
> messages emitted by the new makeinfo and fixed whatever they told
> needed fixing.

That's pretty much it.  Mostly, Texinfo 5.0 is pickier about making sure
that subsections line up with the corresponding menus, which is
a good thing.

There's one remaining incompatibility between the Emacs trunk and
Texinfo 5.0, having to do with a macro in the TRAMP User Manual,
which I haven't fixed.  I recently filed a Texinfo bug report for that
<http://lists.gnu.org/archive/html/bug-texinfo/2013-02/msg00061.html>
with no response yet.

By the way, Texinfo 5.0 is *way* slower, so you probably don't want
to upgrade Texinfo unless you've got a fast machine.  On my last-year's
desktop (AMD Phenom II X4 910e) it takes over 3 minutes of CPU time
to make Emacs's info files.  See the thread starting at
<http://lists.gnu.org/archive/html/bug-texinfo/2013-02/msg00049.html>.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> Date: Thu, 21 Feb 2013 09:35:06 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: Bastien <bzg@altern.org>, emacs-devel@gnu.org
> 
> By the way, Texinfo 5.0 is *way* slower, so you probably don't want
> to upgrade Texinfo unless you've got a fast machine.  On my last-year's
> desktop (AMD Phenom II X4 910e) it takes over 3 minutes of CPU time
> to make Emacs's info files.

It took 5 minutes on a Core Duo, and 3 min on a Core i7 (vs 6 sec with
makeinfo 4.13).

> See the thread starting at
> <http://lists.gnu.org/archive/html/bug-texinfo/2013-02/msg00049.html>.

Very sad.

I keep the v4.13a makeinfo around (and renamed the v5.0 to
'makeinfo5').

Btw, I think this fixing of the manuals should have been done on the
release branch, because users _will_ try building the manuals with
Texinfo 5 when Emacs 24.3 is released.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Glenn Morris]

Eli Zaretskii wrote:

> Btw, I think this fixing of the manuals should have been done on the
> release branch, because users _will_ try building the manuals with
> Texinfo 5 when Emacs 24.3 is released.

I agree; could someone backport the needed changes please?

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Paul Eggert]

On 02/21/13 11:03, Glenn Morris wrote:
> I agree; could someone backport the needed changes please?

Done, by backporting trunk bzr 111300 and 111840 into emacs-24.

The problem with the TRAMP User Manual still remains in emacs-24,
just as it does in the trunk.  If an easy fix to that turns up
before the final pretest I assume it'll be OK to install it into
emacs-24; please let me know otherwise.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> Date: Thu, 21 Feb 2013 13:35:39 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: Eli Zaretskii <eliz@gnu.org>, bzg@altern.org, emacs-devel@gnu.org
> 
> On 02/21/13 11:03, Glenn Morris wrote:
> > I agree; could someone backport the needed changes please?
> 
> Done, by backporting trunk bzr 111300 and 111840 into emacs-24.
> 
> The problem with the TRAMP User Manual still remains in emacs-24,
> just as it does in the trunk.  If an easy fix to that turns up
> before the final pretest I assume it'll be OK to install it into
> emacs-24; please let me know otherwise.

The problem is with this macro:

  @macro trampfn {method, user, host, localname}@c
  @value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
  @end macro

It uses intermediate macros, because the manual calls this macro with
some of its arguments empty, e.g.:

  @trampfn{telnet, , , /usr/local/bin/etc}

and it wants the prefixes and postfixes (@ and :) not to appear when
the corresponding argument is empty.

I think the best way to fix this would be to introduce several macros,
one each for every number of non-empty arguments, and then use each
one as needed.  A bit less convenient, perhaps, but much more
straightforward.

The question is would Michael accept this solution.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Glenn Morris]

Eli Zaretskii wrote:

> I think the best way to fix this would be to introduce several macros,
> one each for every number of non-empty arguments, and then use each
> one as needed.  A bit less convenient, perhaps, but much more
> straightforward.

If it turns out to needs a non-trivial fix like this, I think it can go
in trunk only. The manuals are pre-built in the release tarfile, so it's
not a big deal if one doesn't build with the latest Texinfo.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: Paul Eggert <eggert@cs.ucla.edu>,  Michael Albinus <michael.albinus@gmx.de>,  bzg@altern.org,  emacs-devel@gnu.org
> Date: Fri, 22 Feb 2013 14:29:22 -0500
> 
> Eli Zaretskii wrote:
> 
> > I think the best way to fix this would be to introduce several macros,
> > one each for every number of non-empty arguments, and then use each
> > one as needed.  A bit less convenient, perhaps, but much more
> > straightforward.
> 
> If it turns out to needs a non-trivial fix like this, I think it can go
> in trunk only.

The fix, if it is accepted, involves changing some of the calls to
trampfn into calls to on of 2 or 3 other (new) macros.  I don't see
anything non-trivial here, certainly not something that could
potentially destabilize the branch.  But it's your call.

> The manuals are pre-built in the release tarfile, so it's
> not a big deal if one doesn't build with the latest Texinfo.

This argument goes both ways: since they are pre-built, any problems
with the non-trivial fix will be solved before the release is tarred.
The advantage is that users can modify the manual and still produce
the Info files.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

> The problem is with this macro:
>
>   @macro trampfn {method, user, host, localname}@c
>   @value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
>   @end macro
>
> It uses intermediate macros, because the manual calls this macro with
> some of its arguments empty, e.g.:
>
>   @trampfn{telnet, , , /usr/local/bin/etc}
>
> and it wants the prefixes and postfixes (@ and :) not to appear when
> the corresponding argument is empty.
>
> I think the best way to fix this would be to introduce several macros,
> one each for every number of non-empty arguments, and then use each
> one as needed.  A bit less convenient, perhaps, but much more
> straightforward.
>
> The question is would Michael accept this solution.

I haven't played with texinfo 5 yet, so I cannot say too much. But the
idea of @trampfn was to have just one unique macro with plays for
all. Before changing this, I would like to check with texinfo 5 whether
it is still possible. If I understand Glenn correctly, we have no rush
for the emacs-24 branch (please correct me if I'm wrong).

Best regards, Michael.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: Paul Eggert <eggert@cs.ucla.edu>,  rgm@gnu.org,  bzg@altern.org,  emacs-devel@gnu.org
> Date: Fri, 22 Feb 2013 21:34:40 +0100
> 
> > I think the best way to fix this would be to introduce several macros,
> > one each for every number of non-empty arguments, and then use each
> > one as needed.  A bit less convenient, perhaps, but much more
> > straightforward.
> >
> > The question is would Michael accept this solution.
> 
> I haven't played with texinfo 5 yet, so I cannot say too much. But the
> idea of @trampfn was to have just one unique macro with plays for
> all.

That part is clear from the macro definition and its use.

> Before changing this, I would like to check with texinfo 5 whether
> it is still possible.

What do you mean by "possible"?  That macro is the only reason of the
error messages tramp.texi triggers from Texinfo 5.0.  The new makeinfo
clearly does NOT support @set/@clear in the middle of text, and it
also doesn't support the @c trick of removing the newline from the
expansion of a macro.

While it is possible that Texinfo 5.0.1 or some such will be augmented
to support these tricks, it is IMO better to avoid them in the first
place: that way, the manual will build correctly with any Texinfo
version.  But it's your decision, eventually.

> If I understand Glenn correctly, we have no rush for the emacs-24
> branch (please correct me if I'm wrong).

Texinfo 5.0 is out, so if we release Emacs 24.3 with tramp.texi as it
is now, people who have Texinfo 5.0 installed will be unable to
rebuild the manual if they need to change it for some reason.  Not a
catastrophe, obviously, but IMO not nice, either: this is, after all,
Free Software.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> > I think the best way to fix this would be to introduce several macros,
>> > one each for every number of non-empty arguments, and then use each
>> > one as needed.  A bit less convenient, perhaps, but much more
>> > straightforward.
>> >
>> > The question is would Michael accept this solution.
>
>> Before changing this, I would like to check with texinfo 5 whether
>> it is still possible.
>
> What do you mean by "possible"?  That macro is the only reason of the
> error messages tramp.texi triggers from Texinfo 5.0.  The new makeinfo
> clearly does NOT support @set/@clear in the middle of text, and it
> also doesn't support the @c trick of removing the newline from the
> expansion of a macro.
>
> While it is possible that Texinfo 5.0.1 or some such will be augmented
> to support these tricks, it is IMO better to avoid them in the first
> place: that way, the manual will build correctly with any Texinfo
> version.  But it's your decision, eventually.

I have modified the macro and some of its calls(*) to be compatible with
Texinfo 5 (and also with Texinfo 4). There are still some warnings when
compiling with Texinfo 5, but the result looks fine.

Likely, I will go to the Texinfo ML and ask about the special problems
with the Tramp manual.

> Texinfo 5.0 is out, so if we release Emacs 24.3 with tramp.texi as it
> is now, people who have Texinfo 5.0 installed will be unable to
> rebuild the manual if they need to change it for some reason.  Not a
> catastrophe, obviously, but IMO not nice, either: this is, after all,
> Free Software.

I've installed it in the emacs-24 branch. I have compiled tramp.texi
with both Texinfo 4 and 5, and I have checked carefully the results. I
believe, the created info files are acceptable for both versions.

(*): The macro does not play well with @multitable and @item.

Best regards, Michael.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Glenn Morris]

Michael Albinus wrote:

> I have modified the macro and some of its calls(*) to be compatible with
> Texinfo 5 (and also with Texinfo 4). There are still some warnings when
> compiling with Texinfo 5, but the result looks fine.

Now the PDF looks worse with makeinfo 4.13. Eg

(add-to-list 'tramp-default-proxies-alist
             '("\\." nil "/ssh:bird@bastion.your.domain:
"))

With final ")) on a separate line.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Michael Albinus]

Glenn Morris <rgm@gnu.org> writes:

>> I have modified the macro and some of its calls(*) to be compatible with
>> Texinfo 5 (and also with Texinfo 4). There are still some warnings when
>> compiling with Texinfo 5, but the result looks fine.
>
> Now the PDF looks worse with makeinfo 4.13. Eg
>
> (add-to-list 'tramp-default-proxies-alist
>              '("\\." nil "/ssh:bird@bastion.your.domain:
> "))
>
> With final ")) on a separate line.

I'll check.

Best regards, Michael.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  eggert@cs.ucla.edu,  bzg@altern.org,  emacs-devel@gnu.org
> Date: Sun, 24 Feb 2013 21:13:31 +0100
> 
> Glenn Morris <rgm@gnu.org> writes:
> 
> >> I have modified the macro and some of its calls(*) to be compatible with
> >> Texinfo 5 (and also with Texinfo 4). There are still some warnings when
> >> compiling with Texinfo 5, but the result looks fine.
> >
> > Now the PDF looks worse with makeinfo 4.13. Eg
> >
> > (add-to-list 'tramp-default-proxies-alist
> >              '("\\." nil "/ssh:bird@bastion.your.domain:
> > "))
> >
> > With final ")) on a separate line.
> 
> I'll check.

If nothing better, you can always separate the PDF case with @iftex.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Michael Albinus]

Glenn Morris <rgm@gnu.org> writes:

> Michael Albinus wrote:
>
>> I have modified the macro and some of its calls(*) to be compatible with
>> Texinfo 5 (and also with Texinfo 4). There are still some warnings when
>> compiling with Texinfo 5, but the result looks fine.
>
> Now the PDF looks worse with makeinfo 4.13. Eg
>
> (add-to-list 'tramp-default-proxies-alist
>              '("\\." nil "/ssh:bird@bastion.your.domain:
> "))
>
> With final ")) on a separate line.

Should be fixed now in the emacs-24 branch. Finally, there are now two
versions of the macros, for Texinfo 4.13 and 5.0. I hope, we can improve
this in the trunk.

Best regards, Michael.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: eggert@cs.ucla.edu,  rgm@gnu.org,  bzg@altern.org,  emacs-devel@gnu.org
> Date: Sun, 24 Feb 2013 19:21:41 +0100
> 
> I have modified the macro and some of its calls(*) to be compatible with
> Texinfo 5 (and also with Texinfo 4). There are still some warnings when
> compiling with Texinfo 5, but the result looks fine.

Thanks.

> Likely, I will go to the Texinfo ML and ask about the special problems
> with the Tramp manual.

You should probably start by reading the thread at

  http://lists.gnu.org/archive/html/bug-texinfo/2013-02/msg00061.html

Unfortunately, the news are not too good, I hope the changes you made
already will overcome what that thread indicated is here to stay.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Michael Albinus]

Paul Eggert <eggert@cs.ucla.edu> writes:

> There's one remaining incompatibility between the Emacs trunk and
> Texinfo 5.0, having to do with a macro in the TRAMP User Manual,

I am very grateful for your silent fixing of my typos and bad English in
that manual. It's a good place to say THANK YOU (and the other guys,
like Glenn)!

Best regards, Michael.

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Bastien]

Michael Albinus <michael.albinus@gmx.de> writes:

> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> There's one remaining incompatibility between the Emacs trunk and
>> Texinfo 5.0, having to do with a macro in the TRAMP User Manual,
>
> I am very grateful for your silent fixing of my typos and bad English in
> that manual. It's a good place to say THANK YOU (and the other guys,
> like Glenn)!

Yeah, *thanks* for all the work Paul!  I learn a lot.

-- 
 Bastien

Re: /srv/bzr/emacs/trunk r111840: Port documentation to Texinfo 5.0.

[Bastien]

Paul Eggert <eggert@cs.ucla.edu> writes:

> On 02/21/13 09:25, Eli Zaretskii wrote:
>> I'm guessing he just looked at the warning/error
>> messages emitted by the new makeinfo and fixed whatever they told
>> needed fixing.
>
> That's pretty much it.  Mostly, Texinfo 5.0 is pickier about making sure
> that subsections line up with the corresponding menus, which is
> a good thing.

Thanks.  I just produced the Org manual with Texinfo 5.0 and there
were no warnings.  But yes, it's very slow :/

-- 
 Bastien