| Message ID | 87mtc18ko9.fsf@trop.in |
|---|---|
| State | New |
| Headers | show |
On 2022-08-19 17:39, Liliana Marie Prikler wrote: > 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.
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? > 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. Cheers
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?
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? > 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? > 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. 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
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(+) 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