[gentoo-commits] proj/devmanual:master commit in: eclass-writing/

["Ulrich Müller" <ulm@gentoo.org>]

commit:     2db21f800191f00cafb5ce90f31e28041628d33c
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Jan  5 12:08:49 2025 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Jan  5 12:37:31 2025 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2db21f80

eclass-writing: Specify @BLURB more precisely

The @BLURB description appears in the NAME section of the generated
man page, and should therefore follow the rules from man-pages(7):

"All words in this line (including the word immediately following the
'\-') should be in lowercase, except where English or technical
terminological convention dictates otherwise."

Since it is a section heading, it should not end with a full stop
either.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 eclass-writing/text.xml | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index d115b8b..9af74ea 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -266,8 +266,9 @@ summarizes the available documentation tags:
   <ti>Yes</ti>
   <ti>Single line freetext</ti>
   <ti>
-    Contains a short description for the eclass. Must be on the same
-    line with the tag.
+    Contains a short description for the eclass. Must be on the same line
+    as the tag. All words, including the first, must be in lowercase, except
+    for proper nouns. The description must <e>not</e> end with a full stop.
   </ti>
 </tr>
 <tr>
@@ -578,13 +579,13 @@ a single function, <c>domacosapp</c>.
 </p>
 
 <codesample lang="ebuild">
-# Copyright 1999-2021 Gentoo Authors
+# Copyright 1999-2025 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: macosapp.eclass
 # @MAINTAINER:
 # Ciaran McCreesh &lt;ciaranm@gentoo.org&gt;
-# @BLURB: install macos .app files to the relevant location.
+# @BLURB: install macos .app files to the relevant location
 
 # @FUNCTION: domacosapp
 # @USAGE: &lt;app-file&gt; [new-file]
@@ -746,14 +747,14 @@ for an eclass to invoke die from the global scope.  For example:
 </p>
 
 <codesample lang="ebuild">
-# Copyright 1999-2022 Gentoo Authors
+# Copyright 1999-2025 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: eapi-die.eclass
 # @MAINTAINER:
 # Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
 # @SUPPORTED_EAPIS: 7 8
-# @BLURB: Calls die when used with an invalid EAPI.
+# @BLURB: call die when used with an invalid EAPI
 
 case ${EAPI} in
 	7|8) ;;
@@ -775,7 +776,7 @@ functions.
 </p>
 
 <codesample lang="ebuild">
-# Copyright 1999-2022 Gentoo Authors
+# Copyright 1999-2025 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: jmake.eclass
@@ -783,7 +784,7 @@ functions.
 # Gentoo Devmanual Project &lt;devmanual@gentoo.org&gt;
 # @AUTHOR:
 # Ciaran McCreesh &lt;ciaranm@gentoo.org&gt;
-# @BLURB: Demonstrate a simple build system eclass.
+# @BLURB: demonstrate a simple build system eclass
 # @DESCRIPTION:
 # Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the
 # (hypothetical) jmake build system along with default src_configure and