[patch v1] manual: make @manpageurl more specific to each output

[Carlos O'Donell]

On 12/17/24 12:51 AM, Florian Weimer wrote:
> * DJ Delorie:
> 
>> Florian Weimer <fweimer@redhat.com> writes:
>>>> +``\func\(\sec\)'' (@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html,,Latest: \func\(\sec\)})
>>>
>>> Would it make sense to move the Latest: out of the linked part?
>>
>> It works either way; the user could click on the word "latest" to jump
>> to the latest version.  I prefer giving the user a larger target to
>> hit.

My goal is to avoid confusion between the normative version of the Linux man pages
that is included in the manual via the configure argument and the link to the
online version which may be arbitrarily new.

> The current Info version reads like this:
> 
>   This documentation is a stub.  For additional information on this
>   function, consult the manual page "poll(2)" (Latest:
>   <https://man7.org/linux/man-pages/man2/poll.2.html>).  *Note Linux
>   Kernel::.
> 
> The quotes seem redundant, the poll(2) looks like sufficient markup to
> me.  Maybe use this instead?
> 
>   This documentation is a stub.  For additional information on this
>   function, consult the manual page poll(2) (online:
>   <https://man7.org/linux/man-pages/man2/poll.2.html>).  *Note Linux
>   Kernel::.

I'm OK for this to be made into one link to poll(2) if we add text to the
@subsection Linux (The Linux Kernel) that explains that the online links are
all to the latest version that might not match the version your glibc is
including by normative reference.

> The HTML version looks like this:
> 
>   This documentation is a stub. For additional information on this
>   function, consult the manual page “poll(2)” (Latest: poll(2)). See
>   Linux (The Linux Kernel).
> 
> Where the “Latest: poll(2)” is the hyperlink.  This too looks redundant.
> I think readers of a web page expect an unversioned link.  We can
> explain that the online links always go to the latest in the Linux
> section.  So maybe this?

I agree, we can explain that in the @subsection Linux (The Linux Kernel).

DJ and I discussed this and DJ's suggestion is to move the "@xref{Linux Kernel}"
into the manpageurl that way it simplifies the creation of references.

In the future if we add GNU Hurd documentation here then it can be adjusted to
just talk about kernel interfaces.

> 
>   This documentation is a stub. For additional information on this
>   function, consult the manual page poll(2). See Linux (The Linux
>   Kernel).
> 
> Or maybe clarify that this is an external source, like this?
> 
>   This documentation is a stub. For additional information on this
>   function, consult the manual page poll(2) (external
>   specification). See Linux (The Linux Kernel).
> 
> (The last part is just what the @xref macro does, even though it is a
> bit awkward.)

This should all look better with the above cleanups.
 
> The PDF version looks like this:
> 
>   int poll (struct pollfd *fds, nfds t nfds, int timeout)          [Function]
>     This documentation is a stub. For additional information on this function,
>     consult the manual page “poll(2)” (Latest: poll(2)).  See Section 1.2.6
>     [Linux (The Linux Kernel)], page 12.
> 
> I think we should include the URL there.  I think the same construct as
> the info version should be used.

That works for me, printing the URL *and* the man page is OK.

> 
> This means that the HTML version is the outlier, and you could use
> @ifhtml and @ifnothtml to produce the different linking style there.

That's up to DJ.

I think we have consensus here after DJ and I discussed the proposed solution.

Looking forward to a v2 that includes the above changes.

-- 
Cheers,
Carlos.