On 2022-08-30 10:28, Liliana Marie Prikler wrote:

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

Yes.  In 3.3.0 it's Documentation/magit.texi and
Documentation/magit-section.texi, but in recent not yet released
version it's ("docs/magit.texi" "docs/magit-section.texi"), there are
also org counterparts of magit and magit-section files, but they are in
sync with texi files.

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

Yes, the second one is User Guide.

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

What can be a good place (module) for such build phases?

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

I think it will work, need to experiment with (build-*-documentation) to
get the feeling.


Attaching the latest version of the documentation-files patch I have: