Skip to content

Commit

Permalink
eclass-writing: Specify @blurb more precisely
Browse files Browse the repository at this point in the history
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@gentoo.org>
  • Loading branch information
ulm committed Jan 5, 2025
1 parent e7f02b4 commit 2db21f8
Showing 1 changed file with 9 additions and 8 deletions.
17 changes: 9 additions & 8 deletions eclass-writing/text.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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) ;;
Expand All @@ -775,15 +776,15 @@ 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
# @MAINTAINER:
# 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
Expand Down

0 comments on commit 2db21f8

Please sign in to comment.