[v2] manual: make @manpageurl more specific to each output
Checks
| Context |
Check |
Description |
| redhat-pt-bot/TryBot-apply_patch |
success
|
Patch applied to master at the time it was sent
|
| linaro-tcwg-bot/tcwg_glibc_build--master-arm |
success
|
Build passed
|
| redhat-pt-bot/TryBot-32bit |
success
|
Build for i686
|
| linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 |
success
|
Test passed
|
| linaro-tcwg-bot/tcwg_glibc_check--master-arm |
success
|
Test passed
|
| redhat-pt-bot/TryBot-still_applies |
warning
|
Patch no longer applies to master
|
Commit Message
Tweak the @manpageurl macro to customize the output for
each of html, info, and pdf output. HTML and PDF (at
least, these days) support clicking on the link title,
whereas info does not. Add text to the intro section
explaining which man pages are normative and which
aren't.
Comments
On 1/6/25 11:20 PM, DJ Delorie wrote:
>
> Tweak the @manpageurl macro to customize the output for
> each of html, info, and pdf output. HTML and PDF (at
> least, these days) support clicking on the link title,
> whereas info does not. Add text to the intro section
> explaining which man pages are normative and which
> aren't.
This includes Florian's feedback and LGTM with the fix that removes the leading
dash on the man invocation which should be "man <section> <page>" with no dash.
OK to keep my RB if you make only that change when you commit.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
> diff --git a/manual/intro.texi b/manual/intro.texi
> index 879c1b38d9..1097dc8f1f 100644
> --- a/manual/intro.texi
> +++ b/manual/intro.texi
> @@ -966,13 +966,25 @@ functionality is available on commercial systems.
>
> @Theglibc{} includes by reference the Linux man-pages
> @value{man_pages_version} documentation to document the listed
> -syscalls for the Linux kernel. For reference purposes only the latest
> +syscalls for the Linux kernel. For reference purposes only, the latest
OK.
> @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
> documentation can be accessed from the
> @uref{https://www.kernel.org,Linux kernel} website. Where the syscall
> has more specific documentation in this manual that more specific
> documentation is considered authoritative.
>
> +Throughout this manual, when we refer to a man page, for example:
> +@quotation
> +@manpageurl{sendmsg,2}
> +@end quotation
> +@noindent
> +we are referring primarily to the specific version noted above (the
> +``normative'' version), typically accessed by running (for example)
> +@code{man -2 sendmsg} on a system with that version installed. For
Please remove the leading "-" which looks like a typo.
> +convenience, we will also link to the online latest copy of the man
> +pages, but keep in mind that version will almost always be newer than,
> +and thus different than, the normative version noted above.
OK. Clarifies our position and the convenience we're offering with the link.
> +
> Additional details on the Linux system call interface can be found in
> @xref{System Calls}.
>
> diff --git a/manual/macros.texi b/manual/macros.texi
> index f48dd4ec22..2003ce2678 100644
> --- a/manual/macros.texi
> +++ b/manual/macros.texi
> @@ -282,14 +282,22 @@ cwd\comments\
> @macro standardsx {element, standard, header}
> @end macro
>
> +@ifhtml
> @macro manpageurl {func, sec}
> -@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}
> +@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html,,\func\(\sec\)}
> +@xref{Linux Kernel}
> @end macro
> +@end ifhtml
> +@ifnothtml
> +@macro manpageurl {func, sec}
> +\func\(\sec\) (Latest, online: @url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html})
> +@xref{Linux Kernel}
> +@end macro
> +@end ifnothtml
OK.
> @macro manpagefunctionstub {func,sec}
> This documentation is a stub. For additional information on this
> function, consult the manual page @manpageurl{\func\,\sec\}.
> -@xref{Linux Kernel}.
> @end macro
>
> @end ifclear
> diff --git a/manual/resource.texi b/manual/resource.texi
> index 612520d4d9..99e4927226 100644
> --- a/manual/resource.texi
> +++ b/manual/resource.texi
> @@ -966,7 +966,6 @@ scheduling policies.
>
> For additional information about scheduling policies, consult consult
> the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}.
> -@xref{Linux Kernel}.
OK.
>
> @strong{Note:} Calling the @code{sched_setattr} function is incompatible
> with support for @code{PTHREAD_PRIO_PROTECT} mutexes.
> @@ -1000,7 +999,7 @@ Scheduling flags associated with the scheduling policy.
>
> In addition to the generic fields, policy-specific fields are available.
> For additional information, consult the manual page
> -@manpageurl{sched_setattr,2}. @xref{Linux Kernel}.
> +@manpageurl{sched_setattr,2}.
OK.
> @end deftp
>
> @deftypefun int sched_setaddr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags)
>
"Carlos O'Donell" <carlos@redhat.com> writes:
> This includes Florian's feedback and LGTM with the fix that removes the leading
> dash on the man invocation which should be "man <section> <page>" with no dash.
> OK to keep my RB if you make only that change when you commit.
That one change made and pushed. Thanks!
> Reviewed-by: Carlos O'Donell <carlos@redhat.com>
Dang it, I keep forgetting to add this. Can we do something to automate
such checks? Are we willing to globally enforce an RB or equivalent?
I know this can be scripted locally, and I've installed such a script
before, but it doesn't seem to be willing to propogate to all my other
repos...
@@ -966,13 +966,25 @@ functionality is available on commercial systems.
@Theglibc{} includes by reference the Linux man-pages
@value{man_pages_version} documentation to document the listed
-syscalls for the Linux kernel. For reference purposes only the latest
+syscalls for the Linux kernel. For reference purposes only, the latest
@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
documentation can be accessed from the
@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
has more specific documentation in this manual that more specific
documentation is considered authoritative.
+Throughout this manual, when we refer to a man page, for example:
+@quotation
+@manpageurl{sendmsg,2}
+@end quotation
+@noindent
+we are referring primarily to the specific version noted above (the
+``normative'' version), typically accessed by running (for example)
+@code{man -2 sendmsg} on a system with that version installed. For
+convenience, we will also link to the online latest copy of the man
+pages, but keep in mind that version will almost always be newer than,
+and thus different than, the normative version noted above.
+
Additional details on the Linux system call interface can be found in
@xref{System Calls}.
@@ -282,14 +282,22 @@ cwd\comments\
@macro standardsx {element, standard, header}
@end macro
+@ifhtml
@macro manpageurl {func, sec}
-@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}
+@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html,,\func\(\sec\)}
+@xref{Linux Kernel}
@end macro
+@end ifhtml
+@ifnothtml
+@macro manpageurl {func, sec}
+\func\(\sec\) (Latest, online: @url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html})
+@xref{Linux Kernel}
+@end macro
+@end ifnothtml
@macro manpagefunctionstub {func,sec}
This documentation is a stub. For additional information on this
function, consult the manual page @manpageurl{\func\,\sec\}.
-@xref{Linux Kernel}.
@end macro
@end ifclear
@@ -966,7 +966,6 @@ scheduling policies.
For additional information about scheduling policies, consult consult
the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}.
-@xref{Linux Kernel}.
@strong{Note:} Calling the @code{sched_setattr} function is incompatible
with support for @code{PTHREAD_PRIO_PROTECT} mutexes.
@@ -1000,7 +999,7 @@ Scheduling flags associated with the scheduling policy.
In addition to the generic fields, policy-specific fields are available.
For additional information, consult the manual page
-@manpageurl{sched_setattr,2}. @xref{Linux Kernel}.
+@manpageurl{sched_setattr,2}.
@end deftp
@deftypefun int sched_setaddr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags)