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