[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
|
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.
@@ -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)