[PATCH 0/3] Add documentation-files argument to emacs build system.

  • Open
  • quality assurance status badge
Details
2 participants
  • Andrew Tropin
  • Liliana Marie Prikler
Owner
unassigned
Submitted by
Andrew Tropin
Severity
normal
A
A
Andrew Tropin wrote on 18 Aug 2022 20:35
(address . guix-patches@gnu.org)(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)
87mtc18ko9.fsf@trop.in
This patch adds a handy way for generating info documentation for emacs
packages from texinfo or org files.

Andrew Tropin (3):
build-system: emacs: Add documentation-files argument.
gnu: emacs-orderless: Use documentation-files argument.
gnu: emacs-consult: Use documentation-files argument.

gnu/packages/emacs-xyz.scm | 11 +++--------
guix/build-system/emacs.scm | 11 +++++++++++
guix/build/emacs-build-system.scm | 17 +++++++++++++++++
3 files changed, 31 insertions(+), 8 deletions(-)

--
2.37.1
From 74b671b94d16db2f21c1df02672fef0b5228a08a Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Thu, 18 Aug 2022 17:43:14 +0300
Subject: [PATCH 1/3] build-system: emacs: Add documentation-files argument.

Allows to build info files from texinfo or org.

* guix/build-system/emacs.scm (default-texinfo): New variable.
* guix/build-system/emacs.scm (lower): New arguments.
* guix/build/emacs-build-system.scm (generate-docs): New variable.
---
guix/build-system/emacs.scm | 11 +++++++++++
guix/build/emacs-build-system.scm | 17 +++++++++++++++++
2 files changed, 28 insertions(+)

Toggle diff (82 lines)
diff --git a/guix/build-system/emacs.scm b/guix/build-system/emacs.scm
index 3df68789ff..632ba2ddb3 100644
--- a/guix/build-system/emacs.scm
+++ b/guix/build-system/emacs.scm
@@ -56,8 +56,16 @@ (define (default-emacs)
(let ((emacs-mod (resolve-interface '(gnu packages emacs))))
(module-ref emacs-mod 'emacs-minimal)))
+(define (default-texinfo)
+ "Return the default texinfo package."
+ ;; Lazily resolve the binding to avoid a circular dependency.
+ (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
+ (module-ref texinfo-mod 'texinfo)))
+
(define* (lower name
#:key source inputs native-inputs outputs system target
+ documentation-files
+ (texinfo (default-texinfo))
(emacs (default-emacs))
#:allow-other-keys
#:rest arguments)
@@ -77,6 +85,7 @@ (define private-keywords
;; Keep the standard inputs of 'gnu-build-system'.
,@(standard-packages)))
(build-inputs `(("emacs" ,emacs)
+ ,@(if (null? documentation-files) '() `(("texinfo" ,texinfo)))
,@native-inputs))
(outputs outputs)
(build emacs-build)
@@ -87,6 +96,7 @@ (define* (emacs-build name inputs
(tests? #f)
(parallel-tests? #t)
(test-command ''("make" "check"))
+ (documentation-files ''())
(phases '%standard-phases)
(outputs '("out"))
(include (quote %default-include))
@@ -109,6 +119,7 @@ (define builder
#:test-command #$test-command
#:tests? #$tests?
#:parallel-tests? #$parallel-tests?
+ #:documentation-files #$documentation-files
#:phases #$phases
#:outputs #$(outputs->gexp outputs)
#:include #$include
diff --git a/guix/build/emacs-build-system.scm b/guix/build/emacs-build-system.scm
index 6a6918bfdd..08c61ddfd8 100644
--- a/guix/build/emacs-build-system.scm
+++ b/guix/build/emacs-build-system.scm
@@ -274,6 +274,22 @@ (define (match-stripped-file action regex)
(install-file? file stat #:verbose? #t)))
#f))))
+(define* (generate-docs #:key outputs documentation-files #:allow-other-keys)
+ "Convert texinfo or org files specified in DOCUMENTATION-FILES argument to
+info files."
+ (map
+ (lambda (path)
+ (if (or (string-suffix? ".texi" path)
+ (string-suffix? ".texinfo" path)
+ (string-suffix? ".txi" path))
+ (invoke "makeinfo" path)
+ (emacs-batch-script ; else org file
+ `(progn
+ (require 'ox-texinfo)
+ (find-file ,path)
+ (org-texinfo-export-to-info)))))
+ documentation-files))
+
(define* (move-doc #:key outputs #:allow-other-keys)
"Move info files from the ELPA package directory to the info directory."
(let* ((out (assoc-ref outputs "out"))
@@ -343,6 +359,7 @@ (define %standard-phases
(modify-phases gnu:%standard-phases
(replace 'unpack unpack)
(add-after 'unpack 'expand-load-path expand-load-path)
+ (add-after 'expand-load-path 'generate-docs generate-docs)
(delete 'bootstrap)
(delete 'configure)
(delete 'build)
--
2.37.1
From 6c8fb7d173c24ef6c00aca5a7697cf14d1353f37 Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Thu, 18 Aug 2022 17:49:18 +0300
Subject: [PATCH 2/3] gnu: emacs-orderless: Use documentation-files argument.

* gnu/packages/emacs-xyz.scm (emacs-orderless): Use documentation-files argument.
---
gnu/packages/emacs-xyz.scm | 9 +--------
1 file changed, 1 insertion(+), 8 deletions(-)

Toggle diff (22 lines)
diff --git a/gnu/packages/emacs-xyz.scm b/gnu/packages/emacs-xyz.scm
index 811e293c1d..f3d515b3c6 100644
--- a/gnu/packages/emacs-xyz.scm
+++ b/gnu/packages/emacs-xyz.scm
@@ -9045,14 +9045,7 @@ (define-public emacs-orderless
(file-name (git-file-name name version))))
(build-system emacs-build-system)
(arguments
- `(#:phases
- (modify-phases %standard-phases
- (add-after 'install 'makeinfo
- (lambda* (#:key outputs #:allow-other-keys)
- (invoke "makeinfo" "orderless.texi")
- (install-file "orderless.info"
- (string-append (assoc-ref outputs "out")
- "/share/info")))))))
+ (list #:documentation-files #~'("orderless.texi")))
(native-inputs
(list texinfo))
(home-page "https://github.com/oantolin/orderless")
--
2.37.1
From d3ad4d4446ba4275bec5f9ed2aaa7e74289727f2 Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Thu, 18 Aug 2022 17:50:00 +0300
Subject: [PATCH 3/3] gnu: emacs-consult: Use documentation-files argument.

* gnu/packages/emacs-xyz.scm (emacs-consult): Use documentation-files argument.
---
gnu/packages/emacs-xyz.scm | 2 ++
1 file changed, 2 insertions(+)

Toggle diff (15 lines)
diff --git a/gnu/packages/emacs-xyz.scm b/gnu/packages/emacs-xyz.scm
index f3d515b3c6..cab1ad9dee 100644
--- a/gnu/packages/emacs-xyz.scm
+++ b/gnu/packages/emacs-xyz.scm
@@ -9071,6 +9071,8 @@ (define-public emacs-consult
(base32 "0sy4rn1vjk1g50r8z14hzj8lds6s7ij2zkjqfi6mfash5il75wnq"))
(file-name (git-file-name name version))))
(build-system emacs-build-system)
+ (arguments
+ (list #:documentation-files #~'("README.org")))
(propagated-inputs (list emacs-compat))
(home-page "https://github.com/minad/consult")
(synopsis "Consulting completing-read")
--
2.37.1
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmL+UswACgkQIgjSCVjB
3rDHMg/+JsVmk6RTsi9dfGIa81j39FmUrS489YDxzPZ0A4xer7JSarBOWpw74/6k
66mfoEjkbVqVVb3TFX5GgPtEzJ9TVRWYYu1ojcHi5RK7UOkMMHJE7/D0Hb9wHSgf
o3Yh9+PIuoNf+WNsX6pka9ko42T2OHlKu7mu3nWDo5zNskjAFBcyKZbFnUEmBb5E
n7/fvlqiw1xBG5IfSEbnhCIXskKUTmwfgiTO3M7l2haY26E9Rlsb9/e6x1IFcUaC
DTb1n50CnARD2HrMI/cZoHclg3zG8ZAPYT10d9A2g0W/vFgglZ2AK8YdZLvcicbn
cu6hrWJQf2zsZxenkxaMT74ApGmk48qUIpqkiUcPp98tiqDn7TJdSbJuFuNJ6kj/
f2PFs+7QSJ2lCWKz2n6mE7CQV/w3rxqTYDIHYHxDhxhZ3Do/gkK1rjanyqO/57XT
W4PYDyue2B17l0rK72ii+gQ5u+MECfvrFsutH5yPMmuTCyDh69vNFOeK9Ysk+ru2
AK+8MBCaTtqRtM054quenIjSfwWP7toKcWcGaaXFRms9XcE0h3OoGFW6HNF42UHh
5tY0Xb3MquSy9JHeZYgl/8escoAm73UlgqH6OOCnoT0oKxE5s3hAaYbWARWb8sSn
hiwXPsIlx5BT0ZJ5++ugQ0nRNP/4yq4pRXfGHmYTdcciF4IRI9w=
=rBp9
-----END PGP SIGNATURE-----
L
L
Liliana Marie Prikler wrote on 18 Aug 2022 21:31
6ea43d7f4b9595d15404bdca462dd8dc71fefea7.camel@gmail.com
Hi Andrew,

again for the mailing list.

Am Donnerstag, dem 18.08.2022 um 17:50 +0300 schrieb Andrew Tropin:
Toggle quote (8 lines)
>
> This patch adds a handy way for generating info documentation for
> emacs packages from texinfo or org files.
>
> Andrew Tropin (3):
> build-system: emacs: Add documentation-files argument.
> gnu: emacs-orderless: Use documentation-files argument.
> gnu: emacs-consult: Use documentation-files argument.
Is it just those two packages that require this phase? If so, what
value is there in making it a "standard" phase?

Toggle quote (10 lines)
> +(define (default-texinfo)
> + "Return the default texinfo package."
> + ;; Lazily resolve the binding to avoid a circular dependency.
> + (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
> + (module-ref texinfo-mod 'texinfo)))
> +
> (define* (lower name
> #:key source inputs native-inputs outputs system
> target
> + documentation-files
I don't think hard-coding this list is useful. Instead, it would be
nice if we simply used find-files with the right pattern, and use a
binary switch as in meson-build-systems #:glib-or-gtk?
Toggle quote (12 lines)
> + (texinfo (default-texinfo))
> (emacs (default-emacs))
> #:allow-other-keys
> #:rest arguments)
> @@ -77,6 +85,7 @@ (define private-keywords
> ;; Keep the standard inputs of 'gnu-build-
> system'.
> ,@(standard-packages)))
> (build-inputs `(("emacs" ,emacs)
> + ,@(if (null? documentation-files) '()
> `(("texinfo" ,texinfo)))
> ,@native-inputs))
We should probably append rather than prepend implicit inputs. In
fact, doing so for emacs itself also means that people could prepend
their own emacs if emacs-minimal is not enough rather than needing a
transformer.

Toggle quote (17 lines)
> +(define* (generate-docs #:key outputs documentation-files #:allow-
> other-keys)
> + "Convert texinfo or org files specified in DOCUMENTATION-FILES
> argument to
> +info files."
> + (map
> + (lambda (path)
> + (if (or (string-suffix? ".texi" path)
> + (string-suffix? ".texinfo" path)
> + (string-suffix? ".txi" path))
> + (invoke "makeinfo" path)
> + (emacs-batch-script ; else org file
> + `(progn
> + (require 'ox-texinfo)
> + (find-file ,path)
> + (org-texinfo-export-to-info)))))
> + documentation-files))
(ice-9 match) is your friend.

Cheers
A
A
Andrew Tropin wrote on 19 Aug 2022 05:33
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)(address . 57280@debbugs.gnu.org)
87k074gb69.fsf@trop.in
On 2022-08-18 20:31, Liliana Marie Prikler wrote:

Toggle quote (4 lines)
> Hi Andrew,
>
> if this ought to have went to a mailing list, it didn't.

Yep, I missed To:, resent it yesterday.

Toggle quote (14 lines)
>
> Am Donnerstag, dem 18.08.2022 um 17:50 +0300 schrieb Andrew Tropin:
>>
>> This patch adds a handy way for generating info documentation for
>> emacs packages from texinfo or org files.
>>
>> Andrew Tropin (3):
>>   build-system: emacs: Add documentation-files argument.
>>   gnu: emacs-orderless: Use documentation-files argument.
>>   gnu: emacs-consult: Use documentation-files argument.
> Is it just those two packages that require this phase? If so, what
> value is there in making it a "standard" phase?
>

It's just two examples, I think there is much more packages.

Toggle quote (14 lines)
>> +(define (default-texinfo)
>> + "Return the default texinfo package."
>> + ;; Lazily resolve the binding to avoid a circular dependency.
>> + (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
>> + (module-ref texinfo-mod 'texinfo)))
>> +
>> (define* (lower name
>> #:key source inputs native-inputs outputs system
>> target
>> + documentation-files
> I don't think hard-coding this list is useful. Instead, it would be
> nice if we simply used find-files with the right pattern, and use a
> binary switch as in meson-build-systems #:glib-or-gtk?

It's not clear how to find a documentation file heuristically, it can be
README, DOCUMENTATION, README.org, docs/MANUAL.org docs/PACKAGE.texi or
anything else, morevover a few of them can be present at the same time
and I'm afraid it will be a very tough task to understand which of them
to use.

The idea is inspired by :doc keyword from elpa and the fact that some of
emacs-xyz packages either miss documentation or have custom build phases
for it:

Toggle quote (18 lines)
>> + (texinfo (default-texinfo))
>> (emacs (default-emacs))
>> #:allow-other-keys
>> #:rest arguments)
>> @@ -77,6 +85,7 @@ (define private-keywords
>> ;; Keep the standard inputs of 'gnu-build-
>> system'.
>> ,@(standard-packages)))
>> (build-inputs `(("emacs" ,emacs)
>> + ,@(if (null? documentation-files) '()
>> `(("texinfo" ,texinfo)))
>> ,@native-inputs))
> We should probably append rather than prepend implicit inputs. In
> fact, doing so for emacs itself also means that people could prepend
> their own emacs if emacs-minimal is not enough rather than needing a
> transformer.
>

I thought #:emacs and #:texinfo arguments are enough to specify custom
emacs/texinfo inputs.

Toggle quote (19 lines)
>> +(define* (generate-docs #:key outputs documentation-files #:allow-
>> other-keys)
>> + "Convert texinfo or org files specified in DOCUMENTATION-FILES
>> argument to
>> +info files."
>> + (map
>> + (lambda (path)
>> + (if (or (string-suffix? ".texi" path)
>> + (string-suffix? ".texinfo" path)
>> + (string-suffix? ".txi" path))
>> + (invoke "makeinfo" path)
>> + (emacs-batch-script ; else org file
>> + `(progn
>> + (require 'ox-texinfo)
>> + (find-file ,path)
>> + (org-texinfo-export-to-info)))))
>> + documentation-files))
> (ice-9 match) is your friend.

That's right, I thought about it when was writting this code :) Will
wait for a few more comments and will refactor in the next revision.

--
Best regards,
Andrew Tropin
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmL/BG4ACgkQIgjSCVjB
3rDV2Q//axhYE3GFe/ejo5yZ0j7PxHJuBWFf5hnuH3ZAhWWRzSLDEcps2LAbH8SC
xkMRqxWns9prWhE76IfAOy4IJ1Hb7aYdMu3T9lL3iQSQRlx880VAGC5uRnviPLvG
BTaKrpxsMD+QVg5Xeb47vy0RTYknEOmtiCwmJ/bWWmv6p90jAp25Hqg9W0sPsWld
fM7yN5TAqKTHgPGtL9aIqAvSeLTr4Q0T3WFL+st5Vd6pqcX06HJZ1aV5ppaFTfBI
K6SC5dymQ0ccEczpeLxFiKR3dvpm4ckhpTGrgC2GYtM+lq0C0eC+lLKbH/7dYkxa
aaciEem/iH9/rmHKZlIIBJBEY1Dq9Z8ZyP4W751LN6FIzYk5VGq2rB7ycJc+orSi
VpmnwcRB0OFLmeaI5a3qv1S9vOyKltqtVjadYulBTJWXUihcM0wp0LGNxAN4Tfc9
TPke8952Fp5sewdlXtaihaUUvhyOJP6UoN1kyHvBW2oCvtzcwG9mccMjnaRSvv8P
VanHx4+C4OA3EW7hWbGk80VPUeOMZo50hXBBWwycUk2VUwEE024hqYMDFWtUUheL
6S2g02MYAC3yllvoV+PUnZFlig4ML6CnUOk6acyBEJ5dholP1pIEvf+rUecQ6vTc
u39ez7/9/YUr5k3hxAcFoUR0yp9TqWk7uI0WCdUinohLXSL14vQ=
=PVaN
-----END PGP SIGNATURE-----

L
L
Liliana Marie Prikler wrote on 19 Aug 2022 06:19
(name . Andrew Tropin)(address . andrew@trop.in)(address . 57280@debbugs.gnu.org)
0f6169482efaaf9f0caac9810841e38c9c569e66.camel@gmail.com
Am Freitag, dem 19.08.2022 um 06:33 +0300 schrieb Andrew Tropin:
Toggle quote (24 lines)
> On 2022-08-18 20:31, Liliana Marie Prikler wrote:
> [...]
> > Am Donnerstag, dem 18.08.2022 um 17:50 +0300 schrieb Andrew Tropin:
> >
> [...]
> > > +(define (default-texinfo)
> > > +  "Return the default texinfo package."
> > > +  ;; Lazily resolve the binding to avoid a circular dependency.
> > > +  (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
> > > +    (module-ref texinfo-mod 'texinfo)))
> > > +
> > >  (define* (lower name
> > >                  #:key source inputs native-inputs outputs system
> > > target
> > > +                documentation-files
> > I don't think hard-coding this list is useful.  Instead, it would be
> > nice if we simply used find-files with the right pattern, and use a
> > binary switch as in meson-build-systems #:glib-or-gtk?
>
> It's not clear how to find a documentation file heuristically, it can
> be README, DOCUMENTATION, README.org, docs/MANUAL.org docs/PACKAGE.texi
> or anything else, morevover a few of them can be present at the same
> time and I'm afraid it will be a very tough task to understand which of
> them to use.
I think it's possible to cover most of those with heuristics. For the
rest, we can still override the phase or just rename the file to
something our heuristics handle.

Toggle quote (22 lines)
> >
> > > +                (texinfo (default-texinfo))
> > >                  (emacs (default-emacs))
> > >                  #:allow-other-keys
> > >                  #:rest arguments)
> > > @@ -77,6 +85,7 @@ (define private-keywords
> > >                          ;; Keep the standard inputs of 'gnu-
> > > build-
> > > system'.
> > >                          ,@(standard-packages)))
> > >           (build-inputs `(("emacs" ,emacs)
> > > +                         ,@(if (null? documentation-files) '()
> > > `(("texinfo" ,texinfo)))
> > >                           ,@native-inputs))
> > We should probably append rather than prepend implicit inputs.
> > In fact, doing so for emacs itself also means that people could
> > prepend their own emacs if emacs-minimal is not enough rather than
> > needing a transformer.
> >
>
> I thought #:emacs and #:texinfo arguments are enough to specify
> custom emacs/texinfo inputs.
And what if any of the documentations needs emacs-org rather than the
org included by emacs-minimal? Spamming keywords is not helpful.

Cheers
Toggle quote (1 lines)
> >
A
A
Andrew Tropin wrote on 19 Aug 2022 08:21
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)(address . 57280@debbugs.gnu.org)
87wnb47nz9.fsf@trop.in
On 2022-08-19 06:19, Liliana Marie Prikler wrote:

Toggle quote (30 lines)
> Am Freitag, dem 19.08.2022 um 06:33 +0300 schrieb Andrew Tropin:
>> On 2022-08-18 20:31, Liliana Marie Prikler wrote:
>> [...]
>> > Am Donnerstag, dem 18.08.2022 um 17:50 +0300 schrieb Andrew Tropin:
>> >
>> [...]
>> > > +(define (default-texinfo)
>> > > +  "Return the default texinfo package."
>> > > +  ;; Lazily resolve the binding to avoid a circular dependency.
>> > > +  (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
>> > > +    (module-ref texinfo-mod 'texinfo)))
>> > > +
>> > >  (define* (lower name
>> > >                  #:key source inputs native-inputs outputs system
>> > > target
>> > > +                documentation-files
>> > I don't think hard-coding this list is useful.  Instead, it would be
>> > nice if we simply used find-files with the right pattern, and use a
>> > binary switch as in meson-build-systems #:glib-or-gtk?
>>
>> It's not clear how to find a documentation file heuristically, it can
>> be README, DOCUMENTATION, README.org, docs/MANUAL.org docs/PACKAGE.texi
>> or anything else, morevover a few of them can be present at the same
>> time and I'm afraid it will be a very tough task to understand which of
>> them to use.
> I think it's possible to cover most of those with heuristics. For the
> rest, we can still override the phase or just rename the file to
> something our heuristics handle.
>

If there is an info file(s) do nothing.
If there are texinfo file build them.
If there are no texinfo files build README.org or README.

Something like that?

Will play around with it a little bit and will publish v2 next week.

Toggle quote (25 lines)
>> >
>> > > +                (texinfo (default-texinfo))
>> > >                  (emacs (default-emacs))
>> > >                  #:allow-other-keys
>> > >                  #:rest arguments)
>> > > @@ -77,6 +85,7 @@ (define private-keywords
>> > >                          ;; Keep the standard inputs of 'gnu-
>> > > build-
>> > > system'.
>> > >                          ,@(standard-packages)))
>> > >           (build-inputs `(("emacs" ,emacs)
>> > > +                         ,@(if (null? documentation-files) '()
>> > > `(("texinfo" ,texinfo)))
>> > >                           ,@native-inputs))
>> > We should probably append rather than prepend implicit inputs.
>> > In fact, doing so for emacs itself also means that people could
>> > prepend their own emacs if emacs-minimal is not enough rather than
>> > needing a transformer.
>> >
>>
>> I thought #:emacs and #:texinfo arguments are enough to specify
>> custom emacs/texinfo inputs.
> And what if any of the documentations needs emacs-org rather than the
> org included by emacs-minimal? Spamming keywords is not helpful.

This is a good point. I'll reorder inputs.

--
Best regards,
Andrew Tropin
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmL/K9oACgkQIgjSCVjB
3rDIdw/8CvqSiAfvJ/1PZ7z6P/PVq+6hbbNYOWTtWD/DKqfbdQ6PZubkQTwQ6pbk
njgkUvCic9J4hDHz8cOQQE32iOQxHVUka1Tv/eUDogOu/9briV9+e87WSjYx+qw/
QOIMWmzulsn2ddLHEu+GU7aO3/T7CSI0ogxu0Sr0a4EKt8+fJS6XnGwEWyThADnk
qm77Wzf9AjhASJxt2cbitutRynE2IL2Hy8wcIhxpQ+cKzGB3pCApus2MyQtGvyKz
I/aofunlakzdSvSCIDRWGnqfitXBnrgDsR6EVjCOZYkioxoFK2qzXqmJN9O0yAoJ
v4uBCAywqBX3t+m6kvq3shqVwfV4pk+kEyMeIKp9Nu8/hhXjIG7gy7UGZYXxfDxc
K8mO2vHGTbtNrblB8zwniZ5wtItbUmyUbZFpnqPO9uk/14WyaZKwCXCx36VP/F0o
/7PYHvyr1zN7bOcen56FgZ6n25b7ie1UqC6cEmCsJUBUxG8Qs4BHgjVQixseZdJb
fdvx3Bjyy1Mz81JwFT0yqg5TOfH0e9PmxWhfORYKIyDL933CUHl2/MDfggVjTOWR
SHKwgv6mXtfQsgLz9q4TSdUoopcYItJ2NJWfVDvvud4TyFGfXsnd7N7VYRpqX9/W
FbZiAKWCs9zKf1RSB4EgKT39ND0P+pEpNKU0SjbbdCmhFh8pTN4=
=1zUa
-----END PGP SIGNATURE-----

L
L
Liliana Marie Prikler wrote on 19 Aug 2022 17:39
(name . Andrew Tropin)(address . andrew@trop.in)(address . 57280@debbugs.gnu.org)
c76deb583d7ef2d9ecaa173c3c1cdf0a9280aa84.camel@gmail.com
Am Freitag, dem 19.08.2022 um 09:21 +0300 schrieb Andrew Tropin:
Toggle quote (13 lines)
> On 2022-08-19 06:19, Liliana Marie Prikler wrote:
> > I think it's possible to cover most of those with heuristics.  For
> > the rest, we can still override the phase or just rename the file
> > to something our heuristics handle.
> >
>
> If there is an info file(s) do nothing.
> If there are texinfo file build them.
> If there are no texinfo files build README.org or README.
>
> Something like that?
>
> Will play around with it a little bit and will publish v2 next week.
I'd word those in terms of for-each, i.e. "build all texinfo files and
org-mode files". Don't trust already compiled sources, i.e. if there's
both README.info and README.org, you still want to generate README.info
from README.org (though "README" doesn't sound like a particular good
heuristic for an org-file to makeinfo from).

Toggle quote (1 lines)
> > >
Cheers
A
A
Andrew Tropin wrote on 26 Aug 2022 16:33
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)(address . 57280@debbugs.gnu.org)
87mtbr13dd.fsf@trop.in
On 2022-08-19 17:39, Liliana Marie Prikler wrote:

Toggle quote (23 lines)
> Am Freitag, dem 19.08.2022 um 09:21 +0300 schrieb Andrew Tropin:
>> On 2022-08-19 06:19, Liliana Marie Prikler wrote:
>> > I think it's possible to cover most of those with heuristics.  For
>> > the rest, we can still override the phase or just rename the file
>> > to something our heuristics handle.
>> >
>>
>> If there is an info file(s) do nothing.
>> If there are texinfo file build them.
>> If there are no texinfo files build README.org or README.
>>
>> Something like that?
>>
>> Will play around with it a little bit and will publish v2 next week.
> I'd word those in terms of for-each, i.e. "build all texinfo files and
> org-mode files". Don't trust already compiled sources, i.e. if there's
> both README.info and README.org, you still want to generate README.info
> from README.org (though "README" doesn't sound like a particular good
> heuristic for an org-file to makeinfo from).
>
>> > >
> Cheers

I went through a few popular packages and came up with conclusion that
it's hard to make good heuristic for automatical documentation build:

1. I tried (find-files "." "\\.(texi|txi|texinfo)$") with consequent
for-each and it doesn't work in general case because it will build files
intended for inclusion, not standalone building. And it's not fixable
with auxiliary build phase. Examples: geiser, dash. It seems that we
need to decide manually for each package, which documentation files to
build.

2. Adding automatic documentation build phase also means that almost all
emacs packages will be rebuild and we don't know what documentation will
be shipped (if it useful doc compiled from texinfo or almost empty
README.org).

It seems that manual approach is more precise, less intrusive and helps
to get rid of many custom and non-uniform documentation build phases.

I'll check a few more emacs packages I use and will send updated
implementation of #:documentation-files argument.

--
Best regards,
Andrew Tropin
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmMI2a4ACgkQIgjSCVjB
3rAE7w/9EMMmMVurXQE0dETQPiikNEolzL3kEWgmZG+J9smv4fm0XHYfXpbJ9b+J
0aeeOH4SbCH3cn7Zfs5lCm4D1dXQ1WGTu14C/0+yqiHESoJXhzYTvsY3enWeRlXM
WSjPlPP2RGJlXGulCkBDPINUaLDCd7KHKlY/pp7KdX03WwEteMiM+Sr4r3PvB3DX
3dMmU0tte4EMjCDaSA3QKSJeay1MwJw4LAxG7wgeuiIuqQcGpYHLeJiMYc0vaqt3
poyryTCaOFU02d1iBvgt6b3fmpB7lkKsCRzhnd4u50YTc13Dx9n9ICjHWWUpmggp
nssnfGCx/5OzVSAstYBwL/YS+TLNwGVr4rBia/Gvqoc5f0bCK6WrpcRvrA7JMymL
mlThWzjm0s+dkYNRODRFTz9swSNZgmrm+D/iWISF+Np6aDphIXvSEOJ4KUB1g6dc
/9ROAJbUMzvPGtzx4zjh4/j95pj1aIesXkFstaQ0VHFAmd1crj8mQgFNi7a54Ca1
Jm0yP5sgqfSfdWuqm06ObbgIuOqkBrkfcZg3F1N/EMGy5P8R6y5X0lehnCAkr6EH
OuE0OO6M8GKJb1wjPkqOCw1T3dGrgxc9hCaalVL0/ekcYuDpoDumTXWGVgOBsN0+
Yf9rBVMxcAKIK0DYvPK+h9EpiPC+Rc8qX6906+tl6GCyFN2MkoA=
=uYib
-----END PGP SIGNATURE-----

L
L
Liliana Marie Prikler wrote on 29 Aug 2022 18:38
(name . Andrew Tropin)(address . andrew@trop.in)(address . 57280@debbugs.gnu.org)
6f1b7bc2361cd375ee54abbeb1e9c4091329283b.camel@gmail.com
Am Freitag, dem 26.08.2022 um 17:33 +0300 schrieb Andrew Tropin:

Toggle quote (10 lines)
> > > >
> > Cheers
>
> I went through a few popular packages and came up with conclusion
> that it's hard to make good heuristic for automatical documentation
> build:
>
> 1. I tried (find-files "." "\\.(texi|txi|texinfo)$") with consequent
> for-each and it doesn't work in general case because it will build
> files intended for inclusion, not standalone building.
Fair enough, there's probably similar issues with org etc. That said,
wouldn't the top-level info/org/whatever file share the package name?

Toggle quote (2 lines)
> 2. Adding automatic documentation build phase also means that almost
> all emacs packages will be rebuild
That's why I'm currently delaying native-comp until all other changes
to emacs-build-system are done.

Toggle quote (3 lines)
> It seems that manual approach is more precise, less intrusive and
> helps to get rid of many custom and non-uniform documentation build
> phases.
If you're going for a "manual" approach, I'd suggest instead making a
curried ((build-documentation #:texinfo-files #:texinfo-regexp ...)
#:outputs ...) so that the files can be written directly into the (add-
after ...) syntax.

Cheers
A
A
Andrew Tropin wrote on 30 Aug 2022 10:15
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)(address . 57280@debbugs.gnu.org)
87bks22lli.fsf@trop.in
On 2022-08-29 18:38, Liliana Marie Prikler wrote:

Toggle quote (16 lines)
> Am Freitag, dem 26.08.2022 um 17:33 +0300 schrieb Andrew Tropin:
>
>> > > >
>> > Cheers
>>
>> I went through a few popular packages and came up with conclusion
>> that it's hard to make good heuristic for automatical documentation
>> build:
>>
>> 1. I tried (find-files "." "\\.(texi|txi|texinfo)$") with consequent
>> for-each and it doesn't work in general case because it will build
>> files intended for inclusion, not standalone building.
> Fair enough, there's probably similar issues with org etc. That said,
> wouldn't the top-level info/org/whatever file share the package name?
>

In many cases, yes it would, but not always.

magit: ("docs/magit.texi" "docs/magit-section.texi")
geiser: ("doc/geiser.texi")
geiser-guile: ("geiser-guile.texi")
dash: ("dash.texi")
orderless: ("orderless.texi")
consult/cape/tempel: ("README.org")
cider: ("doc/modules/ROOT/nav.adoc")
all-the-icons: ("README.md")
citar: ("README.org")
org-roam: ("doc/org-roam.texi")
debbugs: ("debbugs.texi" "debbugs-ug.texi")
modus-themes: ("doc/modus-themes.org")

Toggle quote (13 lines)
>> 2. Adding automatic documentation build phase also means that almost
>> all emacs packages will be rebuild
> That's why I'm currently delaying native-comp until all other changes
> to emacs-build-system are done.
>
>> It seems that manual approach is more precise, less intrusive and
>> helps to get rid of many custom and non-uniform documentation build
>> phases.
> If you're going for a "manual" approach, I'd suggest instead making a
> curried ((build-documentation #:texinfo-files #:texinfo-regexp ...)
> #:outputs ...) so that the files can be written directly into the (add-
> after ...) syntax.

Do you mean to make a helper function, which can be used to generate a
closure of build phase, which can be added with replace/add-after?

Another idea is to make a separate functions for different documentation
type: build-{texinfo,markdown,org,etc}-documentation. Also, it seems
useful outside of emacs-build-system as well.

In such case user will need to accomplish following steps: 1. add
texinfo/pandoc/emacs-org dependency 2. use modify-phases to add
(build-{texinfo,whatever}-documentation #:texinfo-files
'("doc/manual.{texi,whatever}")), seems a little less convenient than
simple #:documentation-files #~(list "manual.{texi,whatever}"), but also
work, at least documentation will be built more uniformly for different
packages.

WDYT?

--
Best regards,
Andrew Tropin
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmMNxykACgkQIgjSCVjB
3rDvzBAAh7YpdzAatG8Ja8UWyB+jDUi4jFp8hXNX6nvdI+82so9cGAkzF4d0yRhV
vVOVi9JcJ9yliSdR1PiljIxvnTsZkIVe8WFWUl9RbC3FAJzdSjdtCf4I4JGs42B0
7TI9GiE4bb7mbCGR1ZEqIQ4GpFwHsIyHgnE+klz+CHx0haMczt8tuDWaQjOKtD2I
yTqV+PPsXmk3SOI9xiRF1f2jPG95ICGVk+/2kLXkYLA2MjR91syXYWM3q3XG7MGO
Xo5O66R4lAUqkktgb7TIG7huxghPvmlzP2IJRGths53Sfg2MkTmfUFWYew1dMSSU
soAxwXurjGt9K5XYZMZDRMd0ErwvoX47C+gG4HVBoM6/sJJMYEWlfgPpu/VgcXD/
3KDiW36l/AH3mt/EGmer5cQ7NGMleeP6igLMdfXmNVyAnjivefpWrUKUWsbyKOua
9llVbCgGdQQMkoj8qwmV5KJP84T9LGlWBQOm/r7UsI8rKnuaPi+q8ENIPfrBoRqR
33oFXOOJWXjom+ptzODJS7zo+/mM4rWZQu6vQuvqpJ1/NUXkbQSdIrFJ0Mhqo+ii
YUic9X44apaPjE6X8jSvdvZkaeFL60Kqua7b6sJ06az0HTO9tER1W6LLB/NSLWAZ
Rc9wKhKYzGcW/zREFJYbjzy2+hH9+LwrO6eJBvSJDowkM1Qt/k4=
=tJA0
-----END PGP SIGNATURE-----

L
L
Liliana Marie Prikler wrote on 30 Aug 2022 10:28
(name . Andrew Tropin)(address . andrew@trop.in)(address . 57280@debbugs.gnu.org)
4b09e4416d637e121a71a316c1eb5d8912b05430.camel@gmail.com
Am Dienstag, dem 30.08.2022 um 11:15 +0300 schrieb Andrew Tropin:
Toggle quote (26 lines)
> On 2022-08-29 18:38, Liliana Marie Prikler wrote:
>
> > Am Freitag, dem 26.08.2022 um 17:33 +0300 schrieb Andrew Tropin:
> >
> > > > > >
> > > > Cheers
> > >
> > > I went through a few popular packages and came up with conclusion
> > > that it's hard to make good heuristic for automatical
> > > documentation
> > > build:
> > >
> > > 1. I tried (find-files "." "\\.(texi|txi|texinfo)$") with
> > > consequent
> > > for-each and it doesn't work in general case because it will
> > > build
> > > files intended for inclusion, not standalone building.
> > Fair enough, there's probably similar issues with org etc.  That
> > said,
> > wouldn't the top-level info/org/whatever file share the package
> > name?
> >
>
> In many cases, yes it would, but not always.
>
> magit: ("docs/magit.texi" "docs/magit-section.texi")
Is magit-section a top-level file?

Toggle quote (1 lines)
> geiser: ("doc/geiser.texi")
I think trying docs?/whatever is good praxis, so I count that as a hit.

Toggle quote (1 lines)
> geiser-guile: ("geiser-guile.texi")
Hit.

Toggle quote (1 lines)
> dash: ("dash.texi")
Hit.

Toggle quote (1 lines)
> orderless: ("orderless.texi")
Hit.

Toggle quote (1 lines)
> consult/cape/tempel: ("README.org")
Hit for README.whatever

Toggle quote (1 lines)
> cider: ("doc/modules/ROOT/nav.adoc")
Miss.

Toggle quote (1 lines)
> all-the-icons: ("README.md")
Hit for README.whatever

Toggle quote (1 lines)
> citar: ("README.org")
Hit for README.whatever

Toggle quote (1 lines)
> org-roam: ("doc/org-roam.texi")
Hit.

Toggle quote (1 lines)
> debbugs: ("debbugs.texi" "debbugs-ug.texi")
Is debbugs-ug a top-level file?

Toggle quote (1 lines)
> modus-themes: ("doc/modus-themes.org")
Hit.

Toggle quote (19 lines)
> >
> >
> > > It seems that manual approach is more precise, less intrusive and
> > > helps to get rid of many custom and non-uniform documentation
> > > build
> > > phases.
> > If you're going for a "manual" approach, I'd suggest instead making
> > a curried ((build-documentation #:texinfo-files #:texinfo-regexp
> > ...)
> > #:outputs ...) so that the files can be written directly into the
> > (add-after ...) syntax.
>
> Do you mean to make a helper function, which can be used to generate
> a closure of build phase, which can be added with replace/add-after?
>
> Another idea is to make a separate functions for different
> documentation
> type: build-{texinfo,markdown,org,etc}-documentation.  Also, it seems
> useful outside of emacs-build-system as well.
Hmm, if we wanted to make that even more generic than just emacs, it'd
go to core-updates.

Toggle quote (9 lines)
> In such case user will need to accomplish following steps: 1. add
> texinfo/pandoc/emacs-org dependency 2. use modify-phases to add
> (build-{texinfo,whatever}-documentation #:texinfo-files
> '("doc/manual.{texi,whatever}")), seems a little less convenient than
> simple #:documentation-files #~(list "manual.{texi,whatever}"), but
> also work, at least documentation will be built more uniformly for
> different packages.
>
> WDYT?
I think if we want to go this more generic route, we'd have to redesign
this a little. For instance, (build-texinfo-documentation) should take
regular expressions as remaining arguments. As for the native-inputs
required, there has already been a precedent set with bash-minimal that
anything requiring extraneous inputs needs to declare them explicitly.

Cheers
A
A
Andrew Tropin wrote on 31 Aug 2022 11:36
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)(address . 57280@debbugs.gnu.org)
87v8q8u54p.fsf@trop.in
On 2022-08-30 10:28, Liliana Marie Prikler wrote:

Toggle quote (29 lines)
> Am Dienstag, dem 30.08.2022 um 11:15 +0300 schrieb Andrew Tropin:
>> On 2022-08-29 18:38, Liliana Marie Prikler wrote:
>>
>> > Am Freitag, dem 26.08.2022 um 17:33 +0300 schrieb Andrew Tropin:
>> >
>> > > > > >
>> > > > Cheers
>> > >
>> > > I went through a few popular packages and came up with conclusion
>> > > that it's hard to make good heuristic for automatical
>> > > documentation
>> > > build:
>> > >
>> > > 1. I tried (find-files "." "\\.(texi|txi|texinfo)$") with
>> > > consequent
>> > > for-each and it doesn't work in general case because it will
>> > > build
>> > > files intended for inclusion, not standalone building.
>> > Fair enough, there's probably similar issues with org etc.  That
>> > said,
>> > wouldn't the top-level info/org/whatever file share the package
>> > name?
>> >
>>
>> In many cases, yes it would, but not always.
>>
>> magit: ("docs/magit.texi" "docs/magit-section.texi")
> Is magit-section a top-level file?

Yes. In 3.3.0 it's Documentation/magit.texi and
Documentation/magit-section.texi, but in recent not yet released
version it's ("docs/magit.texi" "docs/magit-section.texi"), there are
also org counterparts of magit and magit-section files, but they are in
sync with texi files.

Toggle quote (31 lines)
>
>> geiser: ("doc/geiser.texi")
> I think trying docs?/whatever is good praxis, so I count that as a hit.
>
>> geiser-guile: ("geiser-guile.texi")
> Hit.
>
>> dash: ("dash.texi")
> Hit.
>
>> orderless: ("orderless.texi")
> Hit.
>
>> consult/cape/tempel: ("README.org")
> Hit for README.whatever
>
>> cider: ("doc/modules/ROOT/nav.adoc")
> Miss.
>
>> all-the-icons: ("README.md")
> Hit for README.whatever
>
>> citar: ("README.org")
> Hit for README.whatever
>
>> org-roam: ("doc/org-roam.texi")
> Hit.
>
>> debbugs: ("debbugs.texi" "debbugs-ug.texi")
> Is debbugs-ug a top-level file?

Yes, the second one is User Guide.

Toggle quote (39 lines)
>
>> modus-themes: ("doc/modus-themes.org")
> Hit.
>
>> >
>> >
>> > > It seems that manual approach is more precise, less intrusive and
>> > > helps to get rid of many custom and non-uniform documentation
>> > > build
>> > > phases.
>> > If you're going for a "manual" approach, I'd suggest instead making
>> > a curried ((build-documentation #:texinfo-files #:texinfo-regexp
>> > ...)
>> > #:outputs ...) so that the files can be written directly into the
>> > (add-after ...) syntax.
>>
>> Do you mean to make a helper function, which can be used to generate
>> a closure of build phase, which can be added with replace/add-after?
>>
>> Another idea is to make a separate functions for different
>> documentation
>> type: build-{texinfo,markdown,org,etc}-documentation.  Also, it seems
>> useful outside of emacs-build-system as well.
> Hmm, if we wanted to make that even more generic than just emacs, it'd
> go to core-updates.
>
>> In such case user will need to accomplish following steps: 1. add
>> texinfo/pandoc/emacs-org dependency 2. use modify-phases to add
>> (build-{texinfo,whatever}-documentation #:texinfo-files
>> '("doc/manual.{texi,whatever}")), seems a little less convenient than
>> simple #:documentation-files #~(list "manual.{texi,whatever}"), but
>> also work, at least documentation will be built more uniformly for
>> different packages.
>>
>> WDYT?
> I think if we want to go this more generic route, we'd have to redesign
> this a little. For instance, (build-texinfo-documentation) should take
> regular expressions as remaining arguments.

What can be a good place (module) for such build phases?

Toggle quote (4 lines)
> As for the native-inputs required, there has already been a precedent
> set with bash-minimal that anything requiring extraneous inputs needs
> to declare them explicitly.

I think it will work, need to experiment with (build-*-documentation) to
get the feeling.


Attaching the latest version of the documentation-files patch I have:
From a1534b2158c97986e1048379661ee9d250ad6c02 Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Thu, 18 Aug 2022 17:43:14 +0300
Subject: [PATCH v2 1/2] build-system: emacs: Add documentation-files argument.

Allows to build info files from texinfo or org.

* guix/build-system/emacs.scm (default-texinfo): New variable.
* guix/build-system/emacs.scm (lower): New arguments.
* guix/build/emacs-build-system.scm (generate-docs): New variable.
---
guix/build-system/emacs.scm | 16 ++++++++++++++--
guix/build/emacs-build-system.scm | 22 ++++++++++++++++++++++
2 files changed, 36 insertions(+), 2 deletions(-)

Toggle diff (92 lines)
diff --git a/guix/build-system/emacs.scm b/guix/build-system/emacs.scm
index 3df68789ff..02379ee54c 100644
--- a/guix/build-system/emacs.scm
+++ b/guix/build-system/emacs.scm
@@ -56,8 +56,16 @@ (define (default-emacs)
(let ((emacs-mod (resolve-interface '(gnu packages emacs))))
(module-ref emacs-mod 'emacs-minimal)))
+(define (default-texinfo)
+ "Return the default texinfo package."
+ ;; Lazily resolve the binding to avoid a circular dependency.
+ (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
+ (module-ref texinfo-mod 'texinfo)))
+
(define* (lower name
#:key source inputs native-inputs outputs system target
+ documentation-files
+ (texinfo (default-texinfo))
(emacs (default-emacs))
#:allow-other-keys
#:rest arguments)
@@ -76,8 +84,10 @@ (define private-keywords
;; Keep the standard inputs of 'gnu-build-system'.
,@(standard-packages)))
- (build-inputs `(("emacs" ,emacs)
- ,@native-inputs))
+ (build-inputs `(,@native-inputs
+ ("emacs" ,emacs)
+ ;; ,@(if (null? documentation-files) '() )
+ ("texinfo" ,texinfo)))
(outputs outputs)
(build emacs-build)
(arguments (strip-keyword-arguments private-keywords arguments)))))
@@ -87,6 +97,7 @@ (define* (emacs-build name inputs
(tests? #f)
(parallel-tests? #t)
(test-command ''("make" "check"))
+ (documentation-files ''())
(phases '%standard-phases)
(outputs '("out"))
(include (quote %default-include))
@@ -109,6 +120,7 @@ (define builder
#:test-command #$test-command
#:tests? #$tests?
#:parallel-tests? #$parallel-tests?
+ #:documentation-files #$documentation-files
#:phases #$phases
#:outputs #$(outputs->gexp outputs)
#:include #$include
diff --git a/guix/build/emacs-build-system.scm b/guix/build/emacs-build-system.scm
index 6a6918bfdd..3ffa196862 100644
--- a/guix/build/emacs-build-system.scm
+++ b/guix/build/emacs-build-system.scm
@@ -274,6 +274,27 @@ (define (match-stripped-file action regex)
(install-file? file stat #:verbose? #t)))
#f))))
+(define* (generate-documentation
+ #:key outputs documentation-files
+ #:allow-other-keys)
+ "Convert texinfo or org files specified in DOCUMENTATION-FILES argument to
+info files. And move info files site-lisp directory."
+ (for-each (lambda (f)
+ (if (regexp-exec
+ (make-regexp "\\.(txi|texi|texinfo)" regexp/icase)
+ f)
+ (invoke "makeinfo" f)
+ (emacs-batch-script ; else org file
+ `(progn
+ (require 'ox-texinfo)
+ (find-file ,f)
+ (org-texinfo-export-to-info)))))
+ documentation-files)
+ (for-each (lambda (f)
+ (install-file f (string-append (assoc-ref outputs "out")
+ %install-dir)))
+ (find-files "." "\\.info$")))
+
(define* (move-doc #:key outputs #:allow-other-keys)
"Move info files from the ELPA package directory to the info directory."
(let* ((out (assoc-ref outputs "out"))
@@ -343,6 +364,7 @@ (define %standard-phases
(modify-phases gnu:%standard-phases
(replace 'unpack unpack)
(add-after 'unpack 'expand-load-path expand-load-path)
+ (add-after 'expand-load-path 'generate-documentation generate-documentation)
(delete 'bootstrap)
(delete 'configure)
(delete 'build)
--
2.37.2
From 8adbef898ef80851753ba9d64b31eed727bb34de Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Wed, 31 Aug 2022 12:16:10 +0300
Subject: [PATCH v2 2/2] gnu: emacs-xyz: Add documentation-files example usage.

* gnu/packages/emacs-xyz.scm (emacs-geiser, emacs-geiser-guile, emacs-magit,
emacs-dash, emacs-consult, emacs-tempel): Add documentation-files example
usage.
---
gnu/packages/emacs-xyz.scm | 26 ++++++++++----------------
1 file changed, 10 insertions(+), 16 deletions(-)

Toggle diff (83 lines)
diff --git a/gnu/packages/emacs-xyz.scm b/gnu/packages/emacs-xyz.scm
index 90ee485f1e..df0570a4a1 100644
--- a/gnu/packages/emacs-xyz.scm
+++ b/gnu/packages/emacs-xyz.scm
@@ -262,7 +262,8 @@ (define-public emacs-geiser
(base32 "1pm33zlcq84h61xhplmrlicckrax1pv39zrmv8ryzhi9mqrb6bdg"))))
(build-system emacs-build-system)
(arguments
- '(#:phases
+ '(#:documentation-files (list "doc/geiser.texi")
+ #:phases
(modify-phases %standard-phases
;; Move the source files to the top level, which is included in
;; the EMACSLOADPATH.
@@ -271,12 +272,7 @@ (define-public emacs-geiser
(let ((el-files (find-files "./elisp" ".*\\.el$")))
(for-each (lambda (f)
(rename-file f (basename f)))
- el-files))))
- (add-before 'install 'make-info
- (lambda _
- (with-directory-excursion "doc"
- (invoke "makeinfo" "--no-split"
- "-o" "geiser.info" "geiser.texi")))))))
+ el-files)))))))
(native-inputs
(list texinfo))
(home-page "https://www.nongnu.org/geiser/")
@@ -311,6 +307,7 @@ (define-public emacs-geiser-guile
(arguments
(list
#:include #~(cons "^src/" %default-include)
+ #:documentation-files #~(list "geiser-guile.texi")
#:phases
#~(modify-phases %standard-phases
(add-after 'unpack 'patch-geiser-guile-binary
@@ -978,17 +975,11 @@ (define-public emacs-magit
#:exclude #~(cons* "magit-libgit.el"
"magit-libgit-pkg.el"
%default-exclude)
+ #:documentation-files #~(list "Documentation/magit.texi"
+ "Documentation/magit-section.texi")
#:phases
#~(modify-phases %standard-phases
- (add-after 'unpack 'build-info-manual
- (lambda _
- (invoke "make" "info")
- ;; Copy info files to the lisp directory, which acts as
- ;; the root of the project for the emacs-build-system.
- (for-each (lambda (f)
- (install-file f "lisp"))
- (find-files "Documentation" "\\.info$"))))
- (add-after 'build-info-manual 'set-magit-version
+ (add-after 'unpack 'set-magit-version
(lambda _
(make-file-writable "lisp/magit.el")
(emacs-substitute-variables "lisp/magit.el"
@@ -3909,6 +3900,7 @@ (define-public emacs-dash
(build-system emacs-build-system)
(arguments
(list #:tests? #t
+ #:documentation-files #~(list "dash.texi")
#:phases
#~(modify-phases %standard-phases
(add-after 'unpack 'disable-byte-compile-error-on-warn
@@ -9188,6 +9180,7 @@ (define-public emacs-consult
(sha256
(base32 "0sy4rn1vjk1g50r8z14hzj8lds6s7ij2zkjqfi6mfash5il75wnq"))
(file-name (git-file-name name version))))
+ (arguments (list #:documentation-files #~(list "README.org")))
(build-system emacs-build-system)
(propagated-inputs (list emacs-compat))
(home-page "https://github.com/minad/consult")
@@ -14145,6 +14138,7 @@ (define-public emacs-tempel
(base32
"0iyh6wxchqg83gpwvg6lz4qy4c2qh25iqjpjm56kif52346a99d2"))))
(build-system emacs-build-system)
+ (arguments (list #:documentation-files #~(list "README.org")))
(home-page "https://github.com/minad/tempel")
(synopsis "Simple templates for Emacs")
(description
--
2.37.2
--
Best regards,
Andrew Tropin
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmMPK4YACgkQIgjSCVjB
3rBWlBAAh59C6bqMbM7/Z8D/LjfUiibCfubL1TPZ2LUMrJ5nky8Kkvs62CehVQm1
cSdtAqfiJAHO4ru3xKSfOBYMsfutT0vNY0KI93H5KNVqzQVe26Mivd2aqvNzDRrz
UAVz/xQYucCWW4higWOnr5Q8tud7JS+b3umA79TDrRi8VF95huKs8iG2M/P+7gVJ
qBAa7u0HfKsoi8raVNXUKZm6c6KxPL6rTGmx+PWGi9m/b8cKBR9ZNIwMVKTYaegG
dueZZQQ0GijUxQ8CT50yNwzk9fW53oFYGV2UvlIn/N2RIj7ob0Q+UzoU1F7ldU0z
TpCGBYAS373VdxZoUWwkVsv9YkVYWekIUOjY42/SOa8CkB1POIVRa9ouhsoAf/jQ
741ESDyK2EskoK17x2G9d6bMUDqWjaguTj1ItaJyYHRUVOCyPxI5Fi/A8M+zRN+m
t8asNL66RXP7kuM7VzHVq7pyAktKQTPHB/7x77HrTAM91vHH1oQJ2/FoEc0OEk/M
UIWnQk/HaLI78E45YI1buIf0r6w2l9f3qgOmYfOI5b+/McgNcRlVNUa72S1PI1v5
ttdBViHmfnEGs+0qWqPR3XnljnfdJwOJwb5vDlK3oNeDz2XbeGFLcBNUWPn8KqBp
SVUkTh2Tdi7Wn9Xl51zQvYfmCZXqtPfrQpCs2q3fmGighpgF2L0=
=GLod
-----END PGP SIGNATURE-----

L
L
Liliana Marie Prikler wrote on 31 Aug 2022 12:07
(name . Andrew Tropin)(address . andrew@trop.in)(address . 57280@debbugs.gnu.org)
64cd6f7171047bfe95ba9621c4616b9288b7dba9.camel@gmail.com
Am Mittwoch, dem 31.08.2022 um 12:36 +0300 schrieb Andrew Tropin:
Toggle quote (6 lines)
> > I think if we want to go this more generic route, we'd have to
> > redesign this a little.  For instance, (build-texinfo-
> > documentation) should take
> > regular expressions as remaining arguments. 
>
> What can be a good place (module) for such build phases?
I was thinking (guix build utils). Of course, one could introduce a
new module, but doing that would come with even more downsides in terms
of UX (or PX if we're pedantic).

Toggle quote (1 lines)
> Attaching the latest version of the documentation-files patch I have
Looking at this patch, perhaps we'd also have to allow customizing
command line options. Also, as for installing, I think this should be
handled by the install phase, which already has includes
"^[^/]*\\.info$" and "^doc/.*\\.info$" by default. Thus, you only need
to build documentation before the install phase.

Cheers
A
A
Andrew Tropin wrote on 2 Sep 2022 16:02
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)(address . 57280@debbugs.gnu.org)
87czcd3md9.fsf@trop.in
On 2022-08-31 12:07, Liliana Marie Prikler wrote:

Toggle quote (11 lines)
> Am Mittwoch, dem 31.08.2022 um 12:36 +0300 schrieb Andrew Tropin:
>> > I think if we want to go this more generic route, we'd have to
>> > redesign this a little.  For instance, (build-texinfo-
>> > documentation) should take
>> > regular expressions as remaining arguments. 
>>
>> What can be a good place (module) for such build phases?
> I was thinking (guix build utils). Of course, one could introduce a
> new module, but doing that would come with even more downsides in terms
> of UX (or PX if we're pedantic).

Ok, I prepared more generic version of the patch.
Picked (guix build emacs-utils) for now, it's done to avoid huge
rebuilds, while testing, later we can move it to (guix build utils).

Also, temporary added pandoc and texinfo to native-inputs for
emacs-build-system, otherwise I would need to update inputs for almost
every emacs-* package. Need to figure out what to do with this.

Toggle quote (8 lines)
>
>> Attaching the latest version of the documentation-files patch I have
> Looking at this patch, perhaps we'd also have to allow customizing
> command line options. Also, as for installing, I think this should be
> handled by the install phase, which already has includes
> "^[^/]*\\.info$" and "^doc/.*\\.info$" by default. Thus, you only need
> to build documentation before the install phase.

That's right, but in the new iteration (v3) of build-documentation phase
I use find-root-library-file, which expects to be executed when elpa
directory is already available, so I can't do it before install phase
and need to manually install info files.

Also, current build phases order is a little confusing, a lot of builds
happens after install phase, directly in output directory:

`set-SOURCE-DATE-EPOCH'
`set-paths'
`install-locale'
`unpack'
`expand-load-path'
`patch-usr-bin-file'
`patch-source-shebangs'
`patch-generated-file-shebangs'
`check'
`install'
`make-autoloads'
`enable-autoloads-compilation'
`patch-el-files'
`ensure-package-description'
`build'
`validate-compiled-autoloads'
`build-documentation'
`move-doc'
`patch-shebangs'
`strip'
`validate-runpath'
`validate-documentation-location'
`delete-info-dir-file'
`patch-dot-desktop-files'
`make-dynamic-linker-cache'
`install-license-files'
`reset-gzip-timestamps'
`compress-documentation'

What if instead of install phase we will use
create-tmp-lisp-and-documentation-directories phase (or something more
meaningful) to make a temporary directory, where we will build all the
stuff and after that, at the end of the build process will install
everything from this temporary directory to the store? This way
emacs-build-system will become more usual and easier to understand and
predict.

--
Best regards,
Andrew Tropin
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmMSDQIACgkQIgjSCVjB
3rDC3w/8CZ4uWjdlz42ocrqmC4VfzurB26Snvrq344qMuuwjgyZneTCAnKfn54mF
VdRiB1WB2o0V8LWJK6XZLl19TJ/1X67BX9r84PQ2NLl39FEr3TTHt5iq1jDhW3jA
DGnQnkY5conf2Oq5NAEE5byZ3itUECroE4yJXmk0Nwvcu6uUzBKuEC65IF/Emm/d
8NN5mVrJnOBtddvokHhCx1InvOWD6925lkT7zZLkTVDkd3nI1LQulZKjBmSqwMtO
mnsfGZyHLG8wFH44WPQiUTUZE3LThE5rBfSMWqZmDZriDZocwDxvw7dPqelegRYU
AQXZeQtMefN5lJCKsNHn12biMT8xnZalUgI5TEeY+XzOLexqIEL4iW2gAEwV8LNP
nf9mAFqauD8HtGeaVjm20asXcb0mQdIepdZD0Ue5AbZkBKnkVuhc9jheOTQI5MBH
YODnvNkJHk5C2JTM2NHgZbCCOUgnwaU2XVwLcKbKE8RJfRjpe6KHmairMQ1ZRwGc
ZNtn5yzqYrzAWFx+IEG4MoOCYSWqc0E28mo8PQBnoknBuOesHTzJyohkPkJLzsIN
GJCI+YbWJ+/WT8095LyOE8WAE2vdV0g2GHZ9UndWQkQWOyC9SzayczYraLH1DegR
yR6T7dPMkqYhetzfhcr28B5K0S9zie9XSWvuJ4mPz+GFbg6K6cY=
=CSHW
-----END PGP SIGNATURE-----

L
L
Liliana Marie Prikler wrote on 2 Sep 2022 16:52
(name . Andrew Tropin)(address . andrew@trop.in)(address . 57280@debbugs.gnu.org)
c37a6706dc15cbb80b0f27122ce497e6f3f6b272.camel@gmail.com
Hi,

Am Freitag, dem 02.09.2022 um 17:02 +0300 schrieb Andrew Tropin:
Toggle quote (7 lines)
> Picked (guix build emacs-utils) for now, it's done to avoid huge
> rebuilds, while testing, later we can move it to (guix build utils).
>
> Also, temporary added pandoc and texinfo to native-inputs for
> emacs-build-system, otherwise I would need to update inputs for
> almost every emacs-* package.  Need to figure out what to do with
> this.
I still don't like that we need pandoc and texinfo as implicit inputs.
There ought to be a better solution than this.

Toggle quote (55 lines)
> >
> > > Attaching the latest version of the documentation-files patch I
> > > have
> > Looking at this patch, perhaps we'd also have to allow customizing
> > command line options.  Also, as for installing, I think this should
> > be
> > handled by the install phase, which already has includes
> > "^[^/]*\\.info$" and "^doc/.*\\.info$" by default.  Thus, you only
> > need
> > to build documentation before the install phase.
>
> That's right, but in the new iteration (v3) of build-documentation
> phase I use find-root-library-file, which expects to be executed when
> elpa directory is already available, so I can't do it before install
> phase and need to manually install info files.
>
> Also, current build phases order is a little confusing, a lot of
> builds happens after install phase, directly in output directory:
>
> `set-SOURCE-DATE-EPOCH'
> `set-paths'
> `install-locale'
> `unpack'
> `expand-load-path'
> `patch-usr-bin-file'
> `patch-source-shebangs'
> `patch-generated-file-shebangs'
> `check'
> `install'
> `make-autoloads'
> `enable-autoloads-compilation'
> `patch-el-files'
> `ensure-package-description'
> `build'
> `validate-compiled-autoloads'
> `build-documentation'
> `move-doc'
> `patch-shebangs'
> `strip'
> `validate-runpath'
> `validate-documentation-location'
> `delete-info-dir-file'
> `patch-dot-desktop-files'
> `make-dynamic-linker-cache'
> `install-license-files'
> `reset-gzip-timestamps'
> `compress-documentation'
>
> What if instead of install phase we will use create-tmp-lisp-and-
> documentation-directories phase (or something
> more meaningful) to make a temporary directory, where we will build
> all the stuff and after that, at the end of the build process will
> install everything from this temporary directory to the store?  This
> way emacs-build-system will become more usual and easier to
> understand andpredict.
I don't think we would need to do staged installations. As for why we
don't build in the temporary directory, I do not know, I merely
inherited that code.

Toggle quote (8 lines)
> +(define* (build-documentation-texinfo
> + #:key
> + (files '())
> + (command '("makeinfo" "--no-split")))
> + "Don't forget to add texinfo into list of inputs for the package."
> + (lambda* (#:key outputs #:allow-other-keys)
> + (for-each (lambda (f) (apply invoke (append command (list f))))
> files)))
This is hardly specific to emacs, is it?
Also, append is usually a code smell. Can't we (apply invoke
"makeinfo" file options)?

Toggle quote (11 lines)
> +(define* (convert-documentation
> + #:key
> + (mapping '())
> + (command '("pandoc")))
> + "Don't forget to add pandoc into list of inputs for the package."
> + (lambda* (#:key outputs #:allow-other-keys)
> + (for-each (lambda (p) (apply invoke
> + (append command
> + (list (car p) "-o" (cdr
> p)))))
> + mapping)))
As above.

Toggle quote (3 lines)
> +(define* (build-documentation-org
> + #:key
> + (files '()))
This one is emacs-specific due to emacs-batch-script and can remain
there.

Toggle quote (3 lines)
> + (add-after 'validate-compiled-autoloads 'move-doc move-doc)
> + (add-before 'move-doc 'build-documentation
> build-documentation)))
I don't think that we'll have to add this phase once we've added the
helpers. And as previously discussed, we'd have to build the
documentation before install.

Cheers
?