bug#57280: closed ([PATCH 0/3] Add documentation-files argument to emacs build system.)

[GNU bug Tracking System]

Your message dated Wed, 26 Apr 2023 08:40:56 +0400
with message-id <87ildjdzmv.fsf@trop.in>
and subject line Re: [PATCH 0/3] Add documentation-files argument to emacs 
build system.
has caused the debbugs.gnu.org bug report #57280,
regarding [PATCH 0/3] Add documentation-files argument to emacs build system.
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs@gnu.org.)


-- 
57280: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=57280
GNU Bug Tracking System
Contact help-debbugs@gnu.org with problems

--- Begin Message --- Subject: [PATCH 0/3] Add documentation-files argument to emacs build system. Date: Thu, 18 Aug 2022 21:35:02 +0300

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(+)

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

0002-gnu-emacs-orderless-Use-documentation-files-argument.patch
Description: Text Data

0003-gnu-emacs-consult-Use-documentation-files-argument.patch
Description: Text Data

signature.asc
Description: PGP signature

--- End Message ---

--- Begin Message --- Subject: Re: [PATCH 0/3] Add documentation-files argument to emacs build system. Date: Wed, 26 Apr 2023 08:40:56 +0400

On 2022-09-02 16:52, Liliana Marie Prikler wrote:

> Hi,
>
> Am Freitag, dem 02.09.2022 um 17:02 +0300 schrieb Andrew Tropin:
>> 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.
>
>> > 
>> > > 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.
>
>> +(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)?
>
>> +(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.
>
>> +(define* (build-documentation-org
>> +          #:key
>> +          (files '()))
> This one is emacs-specific due to emacs-batch-script and can remain
> there.
>
>> +    (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

I think we can consider this patch series as an thought experiment.

Manually adding documentation build phases works good enough and
probably there is no need to do something more generic like this.

Closing the ticket without merging.

Liliana, thank you for you time!

-- 
Best regards,
Andrew Tropin

signature.asc
Description: PGP signature

--- End Message ---