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

[Andrew Tropin <andrew@trop.in>]

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

On 2022-08-18 20:31, Liliana Marie Prikler wrote:

> Hi Andrew,
>
> if this ought to have went to a mailing list, it didn't.

Yep, I missed To:, resent it yesterday.

>
> 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.

>> +(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:
https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/elpa-packages#n781

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

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

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