gentoo · arthurzam · Sep 17, 2025 · ulm · Sep 17, 2025
diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml
@@ -55,10 +55,10 @@ for those who prefer to submit patches using pull requests.
 
 <p>
 To build the devmanual, simply run <c>make</c> in the top directory of
-the repository. You need <c>xsltproc</c> (from <c>dev-libs/libxslt</c>)
-for the XML to HTML conversion, <c>xmllint</c> (from <c>dev-libs/libxml2</c>)
-for validation, and <c>rsvg-convert</c> (from <c>gnome-base/librsvg</c>) for
-the SVG to PNG conversion used in some of the figures throughout the document.
+the repository. You need <c>xsltproc</c> (from <pkg>dev-libs/libxslt</pkg>)
+for the XML to HTML conversion, <c>xmllint</c> (from <pkg>dev-libs/libxml2</pkg>)
+for validation, and <pkg>rsvg-convert</pkg> (from <pkg>gnome-base/librsvg</pkg>)
+for the SVG to PNG conversion used in some of the figures throughout the document.
 </p>
 
 <p>

diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
@@ -501,6 +501,12 @@ The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
 <sub>subscript</sub> and <sup>superscript</sup>.
 </p>
 
+<p>
+Use the <c>&lt;pkg&gt;</c> element to reference Gentoo packages, such as
+<c>&lt;pkg&gt;app-doc/pms&lt;/pkg&gt;</c>, which renders as <pkg>app-doc/pms</pkg>.
+This tag automatically creates a link to the package information page.
+</p>
+
 </body>
 </subsection>
 <subsection>

diff --git a/appendices/editor-configuration/emacs/text.xml b/appendices/editor-configuration/emacs/text.xml
@@ -64,13 +64,13 @@ activated by <c>(setq x-select-enable-clipboard t)</c>.
 
 <p>
 For easy editing of ebuilds an Emacs mode has been created, which is
-found in the package <c>app-emacs/ebuild-mode</c>.
+found in the package <pkg>app-emacs/ebuild-mode</pkg>.
 It supports ebuilds and eclasses, highlights keywords and also
 provides a hook for your own customisation.
 </p>
 
 <p>
-Package <c>app-emacs/nxml-gentoo-schemas</c> improves editing of
+Package <pkg>app-emacs/nxml-gentoo-schemas</pkg> improves editing of
 Gentoo specific XML files (e.g., <c>metadata.xml</c>). It provides
 auto-completion and on-the-fly validation, using a RELAX NG schema
 for each document type.

diff --git a/appendices/editor-configuration/vim/text.xml b/appendices/editor-configuration/vim/text.xml
@@ -7,7 +7,7 @@
 <p>
 For full whitespace, character set, syntax highlighting and indent settings for
 all of Gentoo's file-types in <c>vim</c> and <c>gvim</c>, emerge the
-<c>app-vim/gentoo-syntax</c> package.
+<pkg>app-vim/gentoo-syntax</pkg> package.
 </p>
 
 <p>

diff --git a/bin/gen-eclass-html.sh b/bin/gen-eclass-html.sh
@@ -177,7 +177,7 @@ cat << 'EOF' > "${OUTPUTDIR}"/text.xml || exit 1
 <p>
 This section provides a reference for some of the more commonly used eclasses.
 Note that most eclasses have an accompanying manual page. These man pages can be
-installed by emerging <c>app-doc/eclass-manpages</c>.
+installed by emerging <pkg>app-doc/eclass-manpages</pkg>.
 </p>
 
 EOF

diff --git a/devbook.rnc b/devbook.rnc
@@ -1,4 +1,4 @@
-# Copyright 2022-2024 Gentoo Authors
+# Copyright 2022-2025 Gentoo Authors
 # Distributed under the terms of the MIT license
 # or the CC-BY-SA-4.0 license (dual-licensed)
 
@@ -123,6 +123,7 @@ e = element e { inline }
 sub = element sub { inline }
 sup = element sup { inline }
 d = element d { empty }
+pkg = element pkg { text }
 
 uri = element uri {
   # uri can have either a URI in the body text or a link attribute

diff --git a/devbook.rng b/devbook.rng
@@ -2,7 +2,7 @@
 <!-- Auto-generated from devbook.rnc; do not edit! -->
 <grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
   <!--
-    Copyright 2022-2024 Gentoo Authors
+    Copyright 2022-2025 Gentoo Authors
     Distributed under the terms of the MIT license
     or the CC-BY-SA-4.0 license (dual-licensed)
   -->
@@ -408,6 +408,11 @@
       <empty/>
     </element>
   </define>
+  <define name="pkg">
+    <element name="pkg">
+      <text/>
+    </element>
+  </define>
   <define name="uri">
     <element name="uri">
       <choice>

diff --git a/devbook.xsl b/devbook.xsl
@@ -337,6 +337,11 @@
   </xsl:choose>
 </xsl:template>
 
+<xsl:template match="pkg">
+  <a href="https://packages.gentoo.org/packages/{.}"><xsl:value-of select="."/></a>
+  <span class="fa fa-hdd-o fa-fw pkg-icon"/>
+</xsl:template>
+
 <xsl:template match="uri">
   <xsl:choose>
     <!-- Intra-document reference -->

diff --git a/devmanual.css b/devmanual.css
@@ -66,6 +66,12 @@ h4:hover > a.permalink {
     max-width: 200px;
 }
 
+.pkg-icon {
+    color: grey;
+    margin-left: 0.1em;
+    font-size: 70%;
+}
+
 /* compatible to Bootstrap 4 for future migration */
 .d-inline-block {
     display: inline-block;

diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
@@ -34,7 +34,7 @@ This section provides usage and descriptions of the different EAPIs.
 An overview about the important features of each EAPI is provided in the
 appendix of the Package Manager Specification.  The two-page leaflet
 can be printed out, consulted for reference and is available
-as <c>app-doc/pms</c> in the main tree.
+as <pkg>app-doc/pms</pkg> in the main tree.
 </important>
 
 <p>
@@ -1400,7 +1400,7 @@ $(usev foo --enable-foo)
 
     <p>
     Obviously, adding a second argument to <c>hasv</c> was not possible, so its
-    behaviour would have become inconsistent with <c>usev</c> in EAPI 8. Since 
+    behaviour would have become inconsistent with <c>usev</c> in EAPI 8. Since
     <c>hasv</c> was not used in the Gentoo repository, it has been removed,
     along with <c>hasq</c> and <c>useq</c> which were considered deprecated
     since 2011.

diff --git a/ebuild-writing/functions/src_compile/building/text.xml b/ebuild-writing/functions/src_compile/building/text.xml
@@ -94,8 +94,8 @@ would break its syntax.
 <p>
 Portage performs a QA check which verifies if LDFLAGS are respected. This QA check
 is enabled only when <c>LDFLAGS</c> variable contains <c>-Wl,--hash-style=gnu</c>.
-(This flag can be used only on systems which use <c>sys-libs/glibc</c> except for
-machines with a MIPS CPU.)
+(This flag can be used only on systems which use <pkg>sys-libs/glibc</pkg> except
+for machines with a MIPS CPU.)
 </p>
 
 </body>

diff --git a/ebuild-writing/functions/src_unpack/other-formats/text.xml b/ebuild-writing/functions/src_unpack/other-formats/text.xml
@@ -19,7 +19,7 @@ If a package is supplied as a .zip file, you should:
 </p>
 
 <ul>
-   <li><c>BDEPEND</c> upon <c>app-arch/unzip</c></li>
+   <li><c>BDEPEND</c> upon <pkg>app-arch/unzip</pkg></li>
    <li>Use <c>unpack</c> as normal</li>
 </ul>
 

diff --git a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml
@@ -60,7 +60,7 @@ following reasons:
 
 <p>
 It is safer (and better for the user) to make a snapshot instead. For example,
-<c>app-editors/emacs</c> snapshots are made using:
+<pkg>app-editors/emacs</pkg> snapshots are made using:
 </p>
 
 <pre>

diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml
@@ -104,8 +104,8 @@ metadata.xml:
 <tr>
   <ti><c>&lt;description&gt;</c></ti>
   <ti>
-    The description tag contains a description of the maintainership, or for 
-    example a remark that someone interested can take over the maintainership. 
+    The description tag contains a description of the maintainership, or for
+    example a remark that someone interested can take over the maintainership.
     It is optional.
   </ti>
 </tr>
@@ -330,7 +330,7 @@ There are also some attributes that can be used with these tags:
   <ti>
     A string identifying the type of upstream source. A list of valid strings are kept in
     <uri link="https://www.gentoo.org/dtd/metadata.dtd">metadata.dtd</uri>.
-    Developers should email the gentoo-dev mailing list before using a new type value. 
+    Developers should email the gentoo-dev mailing list before using a new type value.
   </ti>
 </tr>
 <tr>
@@ -364,7 +364,7 @@ For developers' convenience, a skeleton file is provided in the
 Gentoo tree with the name
 <uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.metadata.xml">
 skel.metadata.xml</uri>. The metadata file can also be created
-using the <c>app-portage/metagen</c> tool.
+using the <pkg>app-portage/metagen</pkg> tool.
 </p>
 
 <p>

diff --git a/keywording/maintenance/text.xml b/keywording/maintenance/text.xml
@@ -34,8 +34,8 @@ When demoting an entire architecture from stable (<c>arch</c>) to testing
     <c>qkeyword --all "${ARCH}" | cut -f1 -d" " | xargs -n 250 qatom
     -F "%{CATEGORY}/%{PN}/%{PF}.ebuild" | xargs ekeyword "~${ARCH}"</c>
     (<c>qkeyword</c> and <c>qatom</c> are tools from
-    <c>app-portage/portage-utils</c>, while <c>ekeyword</c> is provided by
-    <c>app-portage/gentoolkit</c>).
+    <pkg>app-portage/portage-utils</pkg>, while <c>ekeyword</c> is provided by
+    <pkg>app-portage/gentoolkit</pkg>).
   </li>
   <li>
     Update any eclasses that define shared <c>KEYWORDS</c> variables. Currently,
-Original file line number
+Diff line change
@@ Expand Up / @@ -19,7 +19,7 @@ If a package is supplied as a .zip file, you should: @@
     </p>
     <ul>
-       <li><c>BDEPEND</c> upon <c>app-arch/unzip</c></li>
+       <li><c>BDEPEND</c> upon <pkg>app-arch/unzip</pkg></li>
        <li>Use <c>unpack</c> as normal</li>
     </ul>
@@ Expand Down @@