From debbugs-submit-bounces@debbugs.gnu.org Tue Aug 30 04:29:06 2022 Received: (at 57280) by debbugs.gnu.org; 30 Aug 2022 08:29:07 +0000 Received: from localhost ([127.0.0.1]:34695 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oSwcM-0006jN-HM for submit@debbugs.gnu.org; Tue, 30 Aug 2022 04:29:06 -0400 Received: from mail-ed1-f67.google.com ([209.85.208.67]:40449) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oSwcK-0006ip-HG for 57280@debbugs.gnu.org; Tue, 30 Aug 2022 04:29:05 -0400 Received: by mail-ed1-f67.google.com with SMTP id m1so13195870edb.7 for <57280@debbugs.gnu.org>; Tue, 30 Aug 2022 01:29:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:user-agent:references :in-reply-to:date:cc:to:from:subject:message-id:from:to:cc; bh=Q+ZcQiuz9DD6Wy9H3OL+T8+IJOxY6mmRHjpe0dte4AU=; b=ggUBzcYH/6X99FCgb6IlWb+6Zn4U+sPyHdGHyG7VfRM76UQIFvnN1lO77cfdSYL/p2 KW+/+RU1FlLY3E+3euIxvyVjvpC3n/JdBA2/3h9tcunfkAn097WE9X6sqWMnb9W8RymK Y60ymkXx2FRUzu4zA90ua45htRSDdeaScMvvXpAREYxDsgXbHeHcXh3aJL9gEozd+fD8 7kNj8d6qWmrvUmLum7DPljXiiUE4qzIF0ECHoi2YNJU/8e033d0uhTQmEuq79You/NGM 4YMOif24bNTAybST6liTYUYOAzIsUlj2dCGTxFvEE7UCVodPpiMM0sp/BW1Xd5v9UyLa Wmwg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:user-agent:references :in-reply-to:date:cc:to:from:subject:message-id:x-gm-message-state :from:to:cc; bh=Q+ZcQiuz9DD6Wy9H3OL+T8+IJOxY6mmRHjpe0dte4AU=; b=3XjyBz1JkXy4hQudvur4wAAa+iLPyG44jJ64ulZIvUVlEh0Kr1wjSNsRTsPWaUtTSn eduhNABhjYSLBzgcuvxUcmtkhqaPq9e8t/MxVwvRN8eMBzDAzs0AcxxL5ZWaViLJNAIM WDkhh+yxpA4aqjtBRjlf7r+SVYfOk/7IE0HhNDYbbOywbf5qBocFRNrEEisfLdd7Hy48 SbuxtHvtzrAUiiCI/uUT6O2YDiY7H+LvcaGKBmcrnJ0FaGBxXieBt7WdnXohJmgEAS4C EXpD+l34D69GTRO9tnxQRUYXHeVujEd3wqTqYDFhh6IScwBzS0ThgPCzYkkZbyAqvog5 VrwQ== X-Gm-Message-State: ACgBeo00qSJ/HEk7MTi325M/gLfjh+ZcxAplznJPwQVmVVE3qn8wfwWn dmw75a+mlpJHgKGQMY6UJYs= X-Google-Smtp-Source: AA6agR74QZtLYM2WJ0qSZ5skk5+QY0V/SzvUAIBJO6tHqXo0Mqq3rPzfzSEWozN9WtpNOAejhUUAeA== X-Received: by 2002:aa7:c956:0:b0:43b:206d:c283 with SMTP id h22-20020aa7c956000000b0043b206dc283mr19354628edt.381.1661848138611; Tue, 30 Aug 2022 01:28:58 -0700 (PDT) Received: from nijino.fritz.box (85-127-52-93.dsl.dynamic.surfer.at. [85.127.52.93]) by smtp.gmail.com with ESMTPSA id kz13-20020a17090777cd00b0073d753759fasm5547527ejc.172.2022.08.30.01.28.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 30 Aug 2022 01:28:57 -0700 (PDT) Message-ID: <4b09e4416d637e121a71a316c1eb5d8912b05430.camel@gmail.com> Subject: Re: [PATCH 0/3] Add documentation-files argument to emacs build system. From: Liliana Marie Prikler To: Andrew Tropin Date: Tue, 30 Aug 2022 10:28:56 +0200 In-Reply-To: <87bks22lli.fsf@trop.in> References: <87mtbr13dd.fsf@trop.in> <6f1b7bc2361cd375ee54abbeb1e9c4091329283b.camel@gmail.com> <87bks22lli.fsf@trop.in> Content-Type: text/plain; charset="UTF-8" User-Agent: Evolution 3.42.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 57280 Cc: 57280@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) 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