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

[Andrew Tropin]

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.

-- 
Best regards,
Andrew Tropin

signature.asc
Description: PGP signature