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

[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")
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")

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

signature.asc
Description: PGP signature