From patchwork Wed Mar 8 01:22:09 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Bruno Victal X-Patchwork-Id: 47779 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id F0B2616E17; Wed, 8 Mar 2023 01:23:23 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=MAILING_LIST_MULTI, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 24C1616DE5 for ; Wed, 8 Mar 2023 01:23:22 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pZiWG-0005pT-Ju; Tue, 07 Mar 2023 20:23:04 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pZiWF-0005ou-3A for guix-patches@gnu.org; Tue, 07 Mar 2023 20:23:03 -0500 Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pZiWE-0003p4-LM for guix-patches@gnu.org; Tue, 07 Mar 2023 20:23:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pZiWE-0004jg-HK for guix-patches@gnu.org; Tue, 07 Mar 2023 20:23:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#62042] [PATCH 4/4] doc: Use @defmac and @defspec for macros. Resent-From: Bruno Victal Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 08 Mar 2023 01:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 62042 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 62042@debbugs.gnu.org Cc: Bruno Victal Received: via spool by 62042-submit@debbugs.gnu.org id=B62042.167823853918127 (code B ref 62042); Wed, 08 Mar 2023 01:23:02 +0000 Received: (at 62042) by debbugs.gnu.org; 8 Mar 2023 01:22:19 +0000 Received: from localhost ([127.0.0.1]:47526 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pZiVW-0004iI-TS for submit@debbugs.gnu.org; Tue, 07 Mar 2023 20:22:19 -0500 Received: from smtpmciv3.myservices.hosting ([185.26.107.239]:56910) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pZiVT-0004ho-IJ for 62042@debbugs.gnu.org; Tue, 07 Mar 2023 20:22:16 -0500 Received: from mail1.netim.hosting (unknown [185.26.106.173]) by smtpmciv3.myservices.hosting (Postfix) with ESMTP id D834920807 for <62042@debbugs.gnu.org>; Wed, 8 Mar 2023 02:22:14 +0100 (CET) Received: from localhost (localhost [127.0.0.1]) by mail1.netim.hosting (Postfix) with ESMTP id 8F5DF80098; Wed, 8 Mar 2023 02:22:14 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mail1.netim.hosting Received: from mail1.netim.hosting ([127.0.0.1]) by localhost (mail1-2.netim.hosting [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id 2jaRpkxWCCdD; Wed, 8 Mar 2023 02:22:14 +0100 (CET) Received: from guix-nuc.home.arpa (bl9-119-177.dsl.telepac.pt [85.242.119.177]) (Authenticated sender: lumen@makinata.eu) by mail1.netim.hosting (Postfix) with ESMTPSA id D896880079; Wed, 8 Mar 2023 02:22:13 +0100 (CET) From: Bruno Victal Date: Wed, 8 Mar 2023 01:22:09 +0000 Message-Id: <6122a9ef42150289534e13f1336353fc58aeda75.1678238486.git.mirai@makinata.eu> X-Mailer: git-send-email 2.39.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (package Reference, Defining Package Variants) (Build Utilities, The Store Monad, G-Expressions, operating-system Reference) (Service Reference, Complex Configurations): Use @defmac and @defspec for macros. --- doc/guix.texi | 97 +++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 50 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index ed9994a41b..358be58205 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7781,7 +7781,7 @@ package Reference @end table @end deftp -@deffn {Scheme Syntax} this-package +@defmac this-package When used in the @emph{lexical scope} of a package field definition, this identifier resolves to the package being defined. @@ -7801,7 +7801,7 @@ package Reference @end lisp It is an error to refer to @code{this-package} outside a package definition. -@end deffn +@end defmac The following helper procedures are provided to help deal with package inputs. @@ -8160,7 +8160,7 @@ Defining Package Variants macro is a helper that can prove useful anytime you want to remove, add, or replace package inputs. -@deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses} +@defmac modify-inputs inputs clauses Modify the given package inputs, as returned by @code{package-inputs} & co., according to the given clauses. Each clause must have one of the following forms: @@ -8195,7 +8195,7 @@ Defining Package Variants The last type of clause is @code{append}, to add inputs at the back of the list. -@end deffn +@end defmac In some cases, you may find it useful to write functions (``procedures'', in Scheme parlance) that return a package based on some @@ -10161,7 +10161,7 @@ Build Utilities @command{sed}. They complement Guile's extensive, but low-level, file system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}). -@deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{} +@defmac with-directory-excursion directory body @dots{} Run @var{body} with @var{directory} as the process's current directory. Essentially, this macro changes the current directory to @var{directory} @@ -10170,7 +10170,7 @@ Build Utilities directory when the dynamic extent of @var{body} is left, be it @i{via} normal procedure return or @i{via} a non-local exit such as an exception. -@end deffn +@end defmac @defun mkdir-p dir Create directory @var{dir} and all its ancestors. @@ -10202,8 +10202,8 @@ Build Utilities is true. Report but ignore errors. @end defun -@deffn {Scheme Syntax} substitute* @var{file} @ - ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{} +@defmac substitute* file @ + ((regexp match-var@dots{}) body@dots{}) @dots{} Substitute @var{regexp} in @var{file} by the string returned by @var{body}. @var{body} is evaluated with each @var{match-var} bound to the corresponding positional regexp sub-expression. For example: @@ -10229,7 +10229,7 @@ Build Utilities Be careful about using @code{$} to match the end of a line; by itself it won't match the terminating newline of a line. -@end deffn +@end defmac @subsection File Search @@ -10390,7 +10390,7 @@ Build Utilities those with tools written with build phases in mind. @cindex build phases, modifying -@deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{} +@defmac modify-phases phases clause@dots{} Modify @var{phases} sequentially as per each @var{clause}, which may have one of the following forms: @@ -10403,7 +10403,7 @@ Build Utilities Where every @var{phase-name} above is an expression evaluating to a symbol, and @var{new-phase} an expression evaluating to a procedure. -@end deffn +@end defmac The example below is taken from the definition of the @code{grep} package. It adds a phase to run after the @code{install} phase, called @@ -11190,16 +11190,16 @@ The Store Monad The main syntactic forms to deal with monads in general are provided by the @code{(guix monads)} module and are described below. -@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ... +@defmac with-monad monad body @dots{} Evaluate any @code{>>=} or @code{return} forms in @var{body} as being in @var{monad}. -@end deffn +@end defmac -@deffn {Scheme Syntax} return @var{val} +@defmac return val Return a monadic value that encapsulates @var{val}. -@end deffn +@end defmac -@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ... +@defmac >>= mval mproc @dots{} @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic procedures @var{mproc}@dots{}@footnote{This operation is commonly referred to as ``bind'', but that name denotes an unrelated procedure in @@ -11218,12 +11218,10 @@ The Store Monad @result{} 4 @result{} some-state @end lisp -@end deffn +@end defmac -@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... -@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... +@defmac mlet monad ((var mval) @dots{}) body @dots{} +@defmacx mlet* monad ((var mval) @dots{}) body @dots{} Bind the variables @var{var} to the monadic values @var{mval} in @var{body}, which is a sequence of expressions. As with the bind operator, this can be thought of as ``unpacking'' the raw, non-monadic @@ -11237,9 +11235,9 @@ The Store Monad @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn +@end defmac -@deffn {Scheme System} mbegin @var{monad} @var{mexp} ... +@defmac mbegin monad mexp @dots{} Bind @var{mexp} and the following monadic expressions in sequence, returning the result of the last expression. Every expression in the sequence must be a monadic expression. @@ -11247,21 +11245,21 @@ The Store Monad This is akin to @code{mlet}, except that the return values of the monadic expressions are ignored. In that sense, it is analogous to @code{begin}, but applied to monadic expressions. -@end deffn +@end defmac -@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ... +@defmac mwhen condition mexp0 mexp* @dots{} When @var{condition} is true, evaluate the sequence of monadic expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is false, return @code{*unspecified*} in the current monad. Every expression in the sequence must be a monadic expression. -@end deffn +@end defmac -@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ... +@defmac munless condition mexp0 mexp* @dots{} When @var{condition} is false, evaluate the sequence of monadic expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is true, return @code{*unspecified*} in the current monad. Every expression in the sequence must be a monadic expression. -@end deffn +@end defmac @cindex state monad The @code{(guix monads)} module provides the @dfn{state monad}, which @@ -11582,8 +11580,8 @@ G-Expressions The syntactic form to construct gexps is summarized below. -@deffn {Scheme Syntax} #~@var{exp} -@deffnx {Scheme Syntax} (gexp @var{exp}) +@defmac #~@var{exp} +@defmacx (gexp @var{exp}) Return a G-expression containing @var{exp}. @var{exp} may contain one or more of the following forms: @@ -11637,9 +11635,9 @@ G-Expressions G-expressions created by @code{gexp} or @code{#~} are run-time objects of the @code{gexp?} type (see below). -@end deffn +@end defmac -@deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{} +@defmac with-imported-modules modules body@dots{} Mark the gexps defined in @var{body}@dots{} as requiring @var{modules} in their execution environment. @@ -11661,9 +11659,9 @@ G-Expressions This form has @emph{lexical} scope: it has an effect on the gexps directly defined in @var{body}@dots{}, but not on those defined, say, in procedures called from @var{body}@dots{}. -@end deffn +@end defmac -@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{} +@defmac with-extensions extensions body@dots{} Mark the gexps defined in @var{body}@dots{} as requiring @var{extensions} in their build and execution environment. @var{extensions} is typically a list of package objects such as those @@ -11673,7 +11671,7 @@ G-Expressions load path while compiling imported modules in @var{body}@dots{}; they are also added to the load path of the gexp returned by @var{body}@dots{}. -@end deffn +@end defmac @defun gexp? obj Return @code{#t} if @var{obj} is a G-expression. @@ -11957,8 +11955,8 @@ G-Expressions @dots{})} expression to construct the file name @emph{at run time}. @end defun -@deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{} -@deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{} +@defmac let-system system body@dots{} +@defmacx let-system (system target) body@dots{} Bind @var{system} to the currently targeted system---e.g., @code{"x86_64-linux"}---within @var{body}. @@ -11981,9 +11979,9 @@ G-Expressions (error "dunno!")))) "-net" "user" #$image) @end lisp -@end deffn +@end defmac -@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp} +@defmac with-parameters ((parameter value) @dots{}) exp This macro is similar to the @code{parameterize} form for dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU Guile Reference Manual}). The key difference is that it takes effect @@ -12000,7 +11998,7 @@ G-Expressions The example above returns an object that corresponds to the i686 build of Coreutils, regardless of the current value of @code{%current-system}. -@end deffn +@end defmac Of course, in addition to gexps embedded in ``host'' code, there are @@ -16651,7 +16649,7 @@ operating-system Reference @end table -@deffn {Scheme Syntax} this-operating-system +@defmac this-operating-system When used in the @emph{lexical scope} of an operating system field definition, this identifier resolves to the operating system being defined. @@ -16669,7 +16667,7 @@ operating-system Reference It is an error to refer to @code{this-operating-system} outside an operating system definition. -@end deffn +@end defmac @end deftp @@ -40564,8 +40562,8 @@ Service Reference @code{modify-services} simply provides a more concise form for this common pattern. -@deffn {Scheme Syntax} modify-services @var{services} @ - (@var{type} @var{variable} => @var{body}) @dots{} +@defspec modify-services services @ + (type variable => body) @dots{} Modify the services listed in @var{services} according to the given clauses. Each clause has the form: @@ -40598,7 +40596,7 @@ Service Reference @xref{Using the Configuration System}, for example usage. -@end deffn +@end defspec Next comes the programming interface for service types. This is something you want to know when writing new service definitions, but not @@ -41074,8 +41072,7 @@ Complex Configurations G-expression (@pxref{G-Expressions}), which should, once serialized to the disk, return a string. More details are listed below. -@deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @ -@var{clause2} ... +@defmac define-configuration name clause1 clause2 @dots{} Create a record type named @code{@var{name}} that contains the fields found in the clauses. @@ -41185,9 +41182,9 @@ Complex Configurations (string "test") "Some documentation.")) @end lisp -@end deffn +@end defmac -@deffn {Scheme Syntax} define-maybe @var{type} +@defmac define-maybe type Sometimes a field should not be serialized if the user doesn’t specify a value. To achieve this, you can use the @code{define-maybe} macro to define a ``maybe type''; if the value of a maybe type is left unset, or @@ -41239,7 +41236,7 @@ Complex Configurations maybe-symbol "Docstring.")) @end lisp -@end deffn +@end defmac @defun maybe-value-set? value Predicate to check whether a user explicitly specified the value of a