From patchwork Tue Jan 7 04:20:48 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 104211 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2F187385840C for ; Tue, 7 Jan 2025 04:23:10 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 2F187385840C Authentication-Results: sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=MTzmrrn/ X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTP id 65CEF3858C5F for ; Tue, 7 Jan 2025 04:20:53 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 65CEF3858C5F Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 65CEF3858C5F Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1736223653; cv=none; b=qF24tijidnGbWv1U+obOxV3mhhDsj70IA64P1eQsCvp4H1acm1aJoGpiy2y40n7TaPgcl4SGx3ie8hSNzNBqor/3Mn+cEWcPP1zt4Htwom9y1Wbv98I+5PAJTYosXgQv2XVOp5D6ac6f8VVv493AZeRajIAN+YjAXm5r31DX0R0= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1736223653; c=relaxed/simple; bh=rSWX4zVVVKlcvfWeyisx909mfj5n2oqht6oK1XU2KIk=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=QmxrlQtXHQw7dnlkdWZTS7b4IX1wUa1zHijBLVnAsidbPgVeWMK0Wrd8SOxYaVPM3JsHaCLQJK+B1YohcLedjvxlyXGJ2HBaD8cG3k5aEoywCkZH7ctmnW1a/YoMpyyYMo2YdDeG41tzOyLyMj/bcVupcbx8FQaeKHAtS5yeRB8= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 65CEF3858C5F DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1736223653; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to; bh=2X4sOr06es1XfAt0VKLDv26nBjYF4wGwrY36TtBY8ks=; b=MTzmrrn/6rvoGLz/yPQTQDV8f0C9+DIQgJbZY4XphTXi8MQhUnAI0r8o/DYoY97g/slUm9 y3Px9kA1yTtNbpsg3aFxbsKTdkpo3foTmh+5XNU1bKOfLVG4wsSpK/h4Pq6lge0ZsjYH8H D69SX1LRgIyjZzkFrIwVU3ghUaP7AvY= Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-647-foNZ2KOhOCWoHR158mKuTA-1; Mon, 06 Jan 2025 23:20:51 -0500 X-MC-Unique: foNZ2KOhOCWoHR158mKuTA-1 X-Mimecast-MFC-AGG-ID: foNZ2KOhOCWoHR158mKuTA Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E51D41955F43 for ; Tue, 7 Jan 2025 04:20:50 +0000 (UTC) Received: from greed.delorie.com (unknown [10.22.88.99]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 9540F1956088; Tue, 7 Jan 2025 04:20:50 +0000 (UTC) Received: from greed.delorie.com.redhat.com (localhost [127.0.0.1]) by greed.delorie.com (8.16.1/8.16.1) with ESMTP id 5074KmNP161484; Mon, 6 Jan 2025 23:20:48 -0500 From: DJ Delorie To: "Carlos O'Donell" Cc: fweimer@redhat.com, libc-alpha@sourceware.org Subject: [patch v2] manual: make @manpageurl more specific to each output In-Reply-To: <90b1d1fc-d457-46f1-b5c6-6548ec6375be@redhat.com> (carlos@redhat.com) Date: Mon, 06 Jan 2025 23:20:48 -0500 Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: I9sgcJX1pcG7pMsr3JsCZv12xHw0c-9sBigcC5I2xOE_1736223651 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-10.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_SHORT, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org 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. Reviewed-by: Carlos O'Donell 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 @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}. 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 @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}. @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)