From: Liliana Marie Prikler <liliana.prikler@gmail.com>
To: Andrew Tropin <andrew@trop.in>
Cc: 57280@debbugs.gnu.org
Subject: [bug#57280] [PATCH 0/3] Add documentation-files argument to emacs build system.
Date: Tue, 30 Aug 2022 10:28:56 +0200 [thread overview]
Message-ID: <4b09e4416d637e121a71a316c1eb5d8912b05430.camel@gmail.com> (raw)
In-Reply-To: <87bks22lli.fsf@trop.in>
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
next prev parent reply other threads:[~2022-08-30 8:30 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <87wnb5lhyr.fsf@trop.in>
[not found] ` <107d9c475d47842d67db4f0a7d85d63ae11f9f3c.camel@gmail.com>
2022-08-19 3:33 ` [bug#57280] [PATCH 0/3] Add documentation-files argument to emacs build system Andrew Tropin
2022-08-19 4:19 ` Liliana Marie Prikler
2022-08-19 6:21 ` Andrew Tropin
2022-08-19 15:39 ` Liliana Marie Prikler
2022-08-26 14:33 ` Andrew Tropin
2022-08-29 16:38 ` Liliana Marie Prikler
2022-08-30 8:15 ` Andrew Tropin
2022-08-30 8:28 ` Liliana Marie Prikler [this message]
2022-08-31 9:36 ` Andrew Tropin
2022-08-31 10:07 ` Liliana Marie Prikler
2022-09-02 14:02 ` Andrew Tropin
2022-09-02 14:52 ` Liliana Marie Prikler
2023-04-26 4:40 ` bug#57280: " Andrew Tropin
2022-08-18 18:35 [bug#57280] " Andrew Tropin
2022-08-18 19:31 ` Liliana Marie Prikler
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4b09e4416d637e121a71a316c1eb5d8912b05430.camel@gmail.com \
--to=liliana.prikler@gmail.com \
--cc=57280@debbugs.gnu.org \
--cc=andrew@trop.in \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).