Bug 916628 – Keywords for ebuild syntax highlighting should be updated

• Product: Documentation
• Status: RESOLVED FIXED

[Description Ulrich Müller 2023-11-01 16:02:12 UTC]

lang.highlight.ebuild.xsl contains an extensive list of package manager and eclass commands, which are outdated.

In all instances of <codesample lang="ebuild"> in the Devmanual, only the following keywords from the existing lists are used:

   complete          (bash-completion-r1.eclass)
   doicon            (desktop.eclass)
   domenu            (desktop.eclass)
   epatch            (epatch.eclass)
   append-flags      (flag-o-matic.eclass)
   append-ldflags    (flag-o-matic.eclass)
   filter-flags      (flag-o-matic.eclass)
   replace-cpu-flags (flag-o-matic.eclass)
   replace-flags     (flag-o-matic.eclass)
   strip-flags       (flag-o-matic.eclass)
   rpm_src_unpack    (rpm.eclass)
   tc-getCC          (toolchain-funcs.eclass)
   enewgroup         (former user.eclass)
   enewuser          (former user.eclass)

The following also occur, but aren't highlighted because they're missing from the lists:

   assert            (EAPI 0)
   eaclocal          (autotools.eclass)
   eautoconf         (autotools.eclass)
   eautoreconf       (autotools.eclass)
   dobashcomp        (bash-completion-r1.eclass)
   virtx             (virtualx.eclass)
   xdg_desktop_database_update  (xdg-utils.eclass)
   xdg_mimeinfo_database_update (xdg-utils.eclass)

I think the following courses of action would be possible:

1. Update eclass keywords with the help of a script. To that end, most of the code from https://gitweb.gentoo.org/proj/ebuild-mode.git/tree/keyword-generation.sh could be borrowed. However, this would generate very long lists (about 1400 keywords), most of which would never be used. As a matter of fact, only 22 keywords are currently used, see above.

2. Limit lang.highlight.ebuild.xsl to package manager commands, plus commands from the most widely used eclasses. Other commands that are used in codesamples could be added on a case-by-case basis.

[Comment 1 Larry the Git Cow 2023-11-06 18:11:34 UTC]

The bug has been closed via the following commit(s):

https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7393d9b055bf655e0c1b12067de0d18537786ed3

commit 7393d9b055bf655e0c1b12067de0d18537786ed3
Author:     Ulrich Müller <[e-mail]>
AuthorDate: 2023-11-04 18:44:31 +0000
Commit:     Ulrich Müller <[e-mail]>
CommitDate: 2023-11-06 18:08:43 +0000

    lang.highlight.ebuild.xsl: Update keyword lists
    
    Update list of package manager commands up to EAPI 8.
    
    Include eclasses that are:
    - used in an existing example in the Devmanual, or
    - general purpose eclasses and inherited by more than 1000 ebuilds
      in the Gentoo repository.
    
    The lists of commands are taken from ebuild-mode.
    
    Closes: https://bugs.gentoo.org/916628
    Signed-off-by: Ulrich Müller <[e-mail]>

 xsl/lang.highlight.ebuild.xsl | 337 +++++++++++-------------------------------
 1 file changed, 89 insertions(+), 248 deletions(-)