[bug#58812] [PATCH 0/5] Add --symlink option to 'guix shell'.

[Maxim Cournoyer]

Hello,

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Ludo!
>
> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hi Maxim!
>>
>> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>>
>>>> We should refrain from using @ref in sentences (info "(texinfo) @ref").
>>>> Instead, I’d write:
>>>>
>>>>   documented for @command{guix pack} (@pxref{pack-symlink-option}).
>>>
>>> I've heard that from you before, but is there a reason against?  I like
>>> to know the rationale for doing things a certain way, lest I forget :-).
>>> From info '(texinfo) @ref':
>>
>> It’s right below the bit you quoted:
>>
>>      The '@ref' command can tempt writers to express themselves in a
>>   manner that is suitable for a printed manual but looks awkward in the
>>   Info format.  Bear in mind that your audience could be using both the
>>   printed and the Info format.  For example: […]
>
> Yes, and I don't get it :-)

To be more concrete, this is what it looks currently:

--8<---------------cut here---------------start------------->8---
‘--symlink=SPEC’
‘-S SPEC’
     For containers, create the symbolic links specified by SPEC, as
     documented in *note pack-symlink-option::.
--8<---------------cut here---------------end--------------->8---

This is what it'd look if I use (see: @pxref ...) instead:
--8<---------------cut here---------------start------------->8---
‘--symlink=SPEC’
‘-S SPEC’
     For containers, create the symbolic links specified by SPEC (see:
     *note pack-symlink-option::).
--8<---------------cut here---------------end--------------->8---

Contrary to what the Texinfo manual says, pxref seems to be the one
introducing the awkward "*note" verb in the resulting info.

-- 
Thanks,
Maxim