eshell manual: texinfo question

eshell manual: texinfo question

[Gregor Zattler]

[-- Attachment #1: Type: text/plain, Size: 457 bytes --]

Hi emacs users,

the eshell.text file as of current emacs master contains the
following paragraph:


The command can be either an Elisp function or an external command.
Eshell looks first for an @ref{Aliases, alias} with the same name as the
command, then a @ref{Built-ins, built-in command} or a function with the
same name; if there is no match, it then tries to execute it as an
external command.


With makeinfo version 6.3 this renders nicely in html:

[-- Attachment #2: eshell.html.png --]
[-- Type: image/png, Size: 15938 bytes --]

[-- Attachment #3: Type: text/plain, Size: 25 bytes --]


but not so nice in pdf:

[-- Attachment #4: eshell.pdf.png --]
[-- Type: image/png, Size: 6571 bytes --]

[-- Attachment #5: Type: text/plain, Size: 18 bytes --]


and not in info:

[-- Attachment #6: eshell.info.png --]
[-- Type: image/png, Size: 14579 bytes --]

[-- Attachment #7: Type: text/plain, Size: 424 bytes --]



I changed this paragraph with the help of texinfo-insert-dwim-@ref to:


The command can be either an Elisp function or an external command.
Eshell looks first for an alias (@pxref{Aliases}) with the same name as the
command, then a built-in (@pxref{Built-ins}) or a function with the
same name; if there is no match, it then tries to execute it as an
external command.


Now this renders nicely (if a bit heavy) in html:

[-- Attachment #8: eshell-patched.html.png --]
[-- Type: image/png, Size: 10856 bytes --]

[-- Attachment #9: Type: text/plain, Size: 22 bytes --]


even heavier in pdf:

[-- Attachment #10: eshell-patched.pdf.png --]
[-- Type: image/png, Size: 6778 bytes --]

[-- Attachment #11: Type: text/plain, Size: 42 bytes --]


but in info the second "see" is missing:

[-- Attachment #12: eshell-patched.info.png --]
[-- Type: image/png, Size: 15083 bytes --]

[-- Attachment #13: Type: text/plain, Size: 318 bytes --]



I also played with further with 'online-label' and
'printed-label' as described in the manual, but this did not hel
either.  I'm mostly interested in the info output, but for files
distributed with Emacs it should look good in all output formats.


Any ideas, what to do in order to fix this issue?



Ciao; Gregor 

Re: eshell manual: texinfo question

[Jean-Christophe Helary]

Gregor,

You need to send this to the texinfo dev list. It is not an emacs issue.

The best way to deal with that is to change texinfo so that the output does not add arbitrary English strings to the links/references. Those should be added by the author (it's also l10n best practice).

Jean-Christophe 

> On Feb 14, 2019, at 6:40, Gregor Zattler <telegraph@gmx.net> wrote:
> 
> Hi emacs users,
> 
> the eshell.text file as of current emacs master contains the
> following paragraph:
> 
> 
> The command can be either an Elisp function or an external command.
> Eshell looks first for an @ref{Aliases, alias} with the same name as the
> command, then a @ref{Built-ins, built-in command} or a function with the
> same name; if there is no match, it then tries to execute it as an
> external command.
> 
> 
> With makeinfo version 6.3 this renders nicely in html:
> <eshell.html.png>
> but not so nice in pdf:
> <eshell.pdf.png>
> and not in info:
> <eshell.info.png>
> 
> I changed this paragraph with the help of texinfo-insert-dwim-@ref to:
> 
> 
> The command can be either an Elisp function or an external command.
> Eshell looks first for an alias (@pxref{Aliases}) with the same name as the
> command, then a built-in (@pxref{Built-ins}) or a function with the
> same name; if there is no match, it then tries to execute it as an
> external command.
> 
> 
> Now this renders nicely (if a bit heavy) in html:
> <eshell-patched.html.png>
> even heavier in pdf:
> <eshell-patched.pdf.png>
> but in info the second "see" is missing:
> <eshell-patched.info.png>
> 
> I also played with further with 'online-label' and
> 'printed-label' as described in the manual, but this did not hel
> either.  I'm mostly interested in the info output, but for files
> distributed with Emacs it should look good in all output formats.
> 
> 
> Any ideas, what to do in order to fix this issue?
> 
> 
> 
> Ciao; Gregor 

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: eshell manual: texinfo question

[Gavin Smith]

On 2/13/19, Jean-Christophe Helary <brandelune@gmail.com> wrote:
> Gregor,
>
> You need to send this to the texinfo dev list. It is not an emacs issue.
>
> The best way to deal with that is to change texinfo so that the output does
> not add arbitrary English strings to the links/references. Those should be
> added by the author (it's also l10n best practice).
>
> Jean-Christophe

>
>> On Feb 14, 2019, at 6:40, Gregor Zattler <telegraph@gmx.net> wrote:
>>
>> Hi emacs users,
>>
>> the eshell.text file as of current emacs master contains the
>> following paragraph:
>>
>>
>> The command can be either an Elisp function or an external command.
>> Eshell looks first for an @ref{Aliases, alias} with the same name as the
>> command, then a @ref{Built-ins, built-in command} or a function with the
>> same name; if there is no match, it then tries to execute it as an
>> external command.
>>
>>
>> With makeinfo version 6.3 this renders nicely in html:
>> <eshell.html.png>
>> but not so nice in pdf:
>> <eshell.pdf.png>
>> and not in info:
>> <eshell.info.png>

In the forwarded email, these images were not present, so we can't see
what the problem is. (I changing the mailing list to one which is more
read.)

The pdf output is the Texinfo project's problem, but how the output
appears in Emacs Info is very likely the Emacs project's problem.

Re: eshell manual: texinfo question

[Gavin Smith]

On 2/14/19, Gavin Smith <gavinsmith0123@gmail.com> wrote:
>>> With makeinfo version 6.3 this renders nicely in html:
>>> <eshell.html.png>
>>> but not so nice in pdf:
>>> <eshell.pdf.png>
>>> and not in info:
>>> <eshell.info.png>
>
> In the forwarded email, these images were not present, so we can't see
> what the problem is. (I changing the mailing list to one which is more
> read.)
>
> The pdf output is the Texinfo project's problem, but how the output
> appears in Emacs Info is very likely the Emacs project's problem.
>

I went looking and found
https://lists.gnu.org/archive/html/help-gnu-emacs/2019-02/msg00206.html.

Basically, cross-references in PDF have to be "heavier" than in HTML
and Info because they have to be meaningful when printed on paper.

It looks like the Emacs handling of the "*note" and "*Note" strings in
the Info viewer could be improved. If doing this kind of hiding or
transforming text in Info files, "*Note" should always be converted to
"See", but "*note" is usually best hidden. The manual author has the
option of writing "see @ref{Node}" (yielding "see *note Node::") if
they want to indicate that there should be a "see" there. IIRC the
only time when "*note" is changed to "see" is when it is inside
parentheses, as "(@pxref{Node})" (yielding "(*note Node::)") is a very
common idiom. There is no simple way I know of to indicate that a bare
cross-reference (without "see") should occur within parentheses.

Re: eshell manual: texinfo question

[Glenn Morris]

Gregor Zattler wrote:

> I changed this paragraph with the help of texinfo-insert-dwim-@ref to:
>
> The command can be either an Elisp function or an external command.
> Eshell looks first for an alias (@pxref{Aliases}) with the same name as the
> command, then a built-in (@pxref{Built-ins}) or a function with the
> same name; if there is no match, it then tries to execute it as an
> external command.

That change looks right to me.

> but in info the second "see" is missing:

Seems to be something to do with Emacs's Info-hide-note-references option.

(I'm not sure help-gnu-emacs is the right place to discuss things like
this; emacs-devel is probably better.)

Re: eshell manual: texinfo question

[Glenn Morris]

>> command, then a built-in (@pxref{Built-ins}) or a function with the
[...]
>> but in info the second "see" is missing:
>
> Seems to be something to do with Emacs's Info-hide-note-references option.

I guess it is a bug in Info-fontify-node, where "\\<in" happens to
(unintentionally) match against "built-in".