[gentoo-dev] [PATCH 0/3] *** SUBJECT HERE ***

[gentoo-dev] [PATCH 0/3] *** SUBJECT HERE ***

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 987 bytes --]

At present, the eclass-to-manpage.awk conversion script supports an
escape mechanism via the @ROFF tag, which allows to write groff commands
in eclass documentation. This makes direct conversion of eclass
documentation to any other format than a man page close to impossible,
because processing with groff is required.

The following series of commits will replace or remove all @ROFF tags
from eclass documentation. The conversion script was already updated:
https://github.com/mgorny/eclass-to-manpage/commit/2be88fd421c7549f659439a287bbb849418a3a3e

Ulrich Müller (3):
  eapi7-ver.eclass: Replace @ROFF in eclass documentation.
  elisp-common.eclass: Replace @ROFF in eclass documentation.
  savedconfig.eclass: Remove @ROFF from eclass documentation.

 eclass/eapi7-ver.eclass    |  8 +++-----
 eclass/elisp-common.eclass | 14 +++++---------
 eclass/savedconfig.eclass  | 20 ++++++++++----------
 3 files changed, 18 insertions(+), 24 deletions(-)

-- 
2.25.1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

[gentoo-dev] [PATCH 1/3] eapi7-ver.eclass: Replace @ROFF in eclass documentation.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 1188 bytes --]

Replace all @ROFF tokens by @SUBSECTION, because the former makes
conversion to any format other than a man page very difficult.

Signed-off-by: Ulrich Müller <ulm@gentoo.org>
---
 eclass/eapi7-ver.eclass | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/eclass/eapi7-ver.eclass b/eclass/eapi7-ver.eclass
index b7f9715bc42..8f13fc9af76 100644
--- a/eclass/eapi7-ver.eclass
+++ b/eclass/eapi7-ver.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2018 Gentoo Foundation
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: eapi7-ver.eclass
@@ -17,8 +17,7 @@
 #
 # https://bugs.gentoo.org/482170
 #
-# @ROFF .SS
-# Version strings
+# @SUBSECTION Version strings
 #
 # The functions support arbitrary version strings consisting of version
 # components interspersed with (possibly empty) version separators.
@@ -50,8 +49,7 @@
 #                  0 1  1
 # @CODE
 #
-# @ROFF .SS
-# Ranges
+# @SUBSECTION Ranges
 #
 # A range can be specified as 'm' for m-th version component, 'm-'
 # for all components starting with m-th or 'm-n' for components starting
-- 
2.25.1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

[gentoo-dev] [PATCH 2/3] elisp-common.eclass: Replace @ROFF in eclass documentation.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 2107 bytes --]

Replace all @ROFF tokens by @SUBSECTION, because the former makes
conversion to any format other than a man page very difficult.

Signed-off-by: Ulrich Müller <ulm@gentoo.org>
---
 eclass/elisp-common.eclass | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/eclass/elisp-common.eclass b/eclass/elisp-common.eclass
index b5ea21cb22b..6fa2bbea614 100644
--- a/eclass/elisp-common.eclass
+++ b/eclass/elisp-common.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: elisp-common.eclass
@@ -43,8 +43,7 @@
 # Please note that this should be done only for packages that are known
 # to fail with lower Emacs versions.
 #
-# @ROFF .SS
-# src_compile() usage:
+# @SUBSECTION src_compile() usage:
 #
 # An elisp file is compiled by the elisp-compile() function defined
 # here and simply takes the source files as arguments.  The case of
@@ -64,8 +63,7 @@
 # comments.  See the Emacs Lisp Reference Manual (node "Autoload") for
 # a detailed explanation.
 #
-# @ROFF .SS
-# src_install() usage:
+# @SUBSECTION src_install() usage:
 #
 # The resulting compiled files (.elc) should be put in a subdirectory of
 # /usr/share/emacs/site-lisp/ which is named after the first argument
@@ -132,8 +130,7 @@
 # "50${PN}-gentoo.el".  If your subdirectory is not named ${PN}, give
 # the differing name as second argument.
 #
-# @ROFF .SS
-# pkg_setup() usage:
+# @SUBSECTION pkg_setup() usage:
 #
 # If your ebuild uses the elisp-compile eclass function to compile
 # its elisp files (see above), then you don't need a pkg_setup phase,
@@ -149,8 +146,7 @@
 # When having optional Emacs support, you should prepend "use emacs &&"
 # to above call of elisp-check-emacs-version().
 #
-# @ROFF .SS
-# pkg_postinst() / pkg_postrm() usage:
+# @SUBSECTION pkg_postinst() / pkg_postrm() usage:
 #
 # After that you need to recreate the start-up file of Emacs after
 # emerging and unmerging by using
-- 
2.25.1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

[gentoo-dev] [PATCH 3/3] savedconfig.eclass: Remove @ROFF from eclass documentation.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 1826 bytes --]

Remove all @ROFF tokens, because they make conversion to any format
other than a man page very difficult. Replace the numbered list by
explicitly numbered paragraphs.

Signed-off-by: Ulrich Müller <ulm@gentoo.org>
---
 eclass/savedconfig.eclass | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/eclass/savedconfig.eclass b/eclass/savedconfig.eclass
index 8f64c5b8edd..e90a9b618d6 100644
--- a/eclass/savedconfig.eclass
+++ b/eclass/savedconfig.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: savedconfig.eclass
@@ -14,21 +14,21 @@
 # so users can modify these config files and the ebuild will take it
 # into account as needed.
 #
-# @ROFF .nr R 1 1
 # Typically you can create your own configuration files quickly by
 # doing:
-# @ROFF .IP \nR 3
-# Build the package with FEATURES=noclean USE=savedconfig.
-# @ROFF .IP \n+R
-# Go into the build dir and edit the relevant configuration system
+#
+# 1. Build the package with FEATURES=noclean USE=savedconfig.
+#
+# 2. Go into the build dir and edit the relevant configuration system
 # (e.g. `make menuconfig` or `nano config-header.h`).  You can look
 # at the files in /etc/portage/savedconfig/ to see what files get
 # loaded/restored.
-# @ROFF .IP \n+R
-# Copy the modified configuration files out of the workdir and to
+#
+# 3. Copy the modified configuration files out of the workdir and to
 # the paths in /etc/portage/savedconfig/.
-# @ROFF .IP \n+R
-# Emerge the package with just USE=savedconfig to get the custom build.
+#
+# 4. Emerge the package with just USE=savedconfig to get the custom
+# build.
 
 inherit portability
 
-- 
2.25.1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] [PATCH 0/3] *** SUBJECT HERE ***

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1187 bytes --]

On Thu, 2020-02-20 at 17:54 +0100, Ulrich Müller wrote:
> At present, the eclass-to-manpage.awk conversion script supports an
> escape mechanism via the @ROFF tag, which allows to write groff commands
> in eclass documentation. This makes direct conversion of eclass
> documentation to any other format than a man page close to impossible,
> because processing with groff is required.
> 
> The following series of commits will replace or remove all @ROFF tags
> from eclass documentation. The conversion script was already updated:
> https://github.com/mgorny/eclass-to-manpage/commit/2be88fd421c7549f659439a287bbb849418a3a3e
> 
> Ulrich Müller (3):
>   eapi7-ver.eclass: Replace @ROFF in eclass documentation.
>   elisp-common.eclass: Replace @ROFF in eclass documentation.
>   savedconfig.eclass: Remove @ROFF from eclass documentation.
> 
>  eclass/eapi7-ver.eclass    |  8 +++-----
>  eclass/elisp-common.eclass | 14 +++++---------
>  eclass/savedconfig.eclass  | 20 ++++++++++----------
>  3 files changed, 18 insertions(+), 24 deletions(-)
> 

Thanks for doing this.  This is certainly going to improve readability.

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]