taylanbayi...@gmail.com (Taylan Ulrich "Bayırlı/Kammer") skribis:
> From 948fcdbb0cea1b8fcd7907554c61633db2f54dd8 Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Taylan=20Ulrich=20Bay=C4=B1rl=C4=B1/Kammer?=
> <taylanbayi...@gmail.com>
> Date: Fri, 15 May 2015 21:54:11 +0200
> Subject: [PATCH] doc: Add "package Reference" and "origin Reference" sections.
>
> * doc/guix.texi (Defining Packages): Link to "package Reference". Add menu.
> (package Reference, origin Reference): New subsections.
This looks great!
> +See @pxref{package Reference} for a full description of possible fields.
Should be:
@xref{package Reference}, for a full description...
(@xref generates “See” and must be followed by a comma.)
> +@node package Reference
> +@subsection package Reference
@subsection @code{package} Reference
(Same for the second subsection.)
> +This section summarizes all the options available in ‘package’
@code{package}
> +@item @code{build-system}
> +The build system (@pxref{Build Systems}) that should be used to
> +build the package.
In general try to put parentheses at the end of the sentence so that
it’s easier to read.
> +@item @code{outputs} (default: @code{'("out")})
> +The list of output names of the package.
+ @xref{Packages with Multiple Outputs}, for typical uses of additional
outputs.
> +@item @code{native-search-paths} (default: @code{'()})
> +FIXME
> +
> +@item @code{search-paths} (default: @code{'()})
> +FIXME
You can group both with @itemx. For now, let’s just say that it’s a
list of @code{search-path-specification} objects describing search-path
environment variables honored by the package. We can write the
‘search-path-specification’ reference another day. ;-)
> +@item @code{replacement} (default: @code{'()})
> +FIXME
Default is @code{#f}.
Something like:
This must either @code{#f} or a package object that will be used as a
@dfn{replacement} for this package. @xref{Security Updates, grafts},
for details.
> +@item @code{maintainers} (default: @code{'()})
> +The list of maintainers of the package. FIXME: upstream, or package
> +recipe?
It’s still unused, but it’s meant to be the list of downstream package
maintainers, represented as a list of <maintainer> objects (imagine a
(guix maintainers) module akin to (guix licenses) where we would all
live.) Probably now would be a good time to start discussing it.
> +@item @code{properties} (default: @code{'()})
> +An alist of arbitrary properties of the package.
Leave that one undocumented (it’s currently unused and I’m not sure it’s
useful.)
[...]
> +@deftp {Data Type} origin
> +This is the data type representing a source code origin.
> +
> +@table @asis
> +@item @code{uri}
> +A string containing the URI of the source.
s/A string/An object/
You can add:
The object type depends on the @code{method} (see below.) For
example, when using the @var{url-fetch} method of @code{(guix
download)}, the valid @code{uri} values are: a URL represented as a
string, or a list thereof.
> +@item @code{method}
> +A procedure that will handle the URI, such as @code{url-fetch}.
s/,.*//
Add a paragraph:
Examples include:
@table @asis
@item @var{url-fetch} from @code{(guix download)}
download a file the HTTP, HTTPS, or FTP URL specified in the
@code{uri} field;
@item @var{git-fetch} from @code{(guix git-download)}
clone the Git version control repository, and check out the revision
specified in the @code{uri} field as a @code{git-reference} object; a
@code{git-reference} looks like this:
@example
(git-reference
(url "git://git.debian.org/git/pkg-shadow/shadow")
(commit "v4.1.5.1"))
@end example
@end @table
> +@item @code{sha256}
> +A bytevector containing the SHA-256 hash of the source. Typically the
> +@code{base32} procedure is used here to generate the bytevector from a
s/procedure/form/
> +@item @code{patch-inputs} (default: @code{#f})
> +Input packages or derivations to the patching process. When this is
> +@code{#f}, the usual set of inputs necessary for patching are provided,
> +such as GNU Patch.
GNU@tie{}Patch
> +@item @code{imported-modules} (default: @code{'()})
The list of Guile modules to import in the patch derivation, for use by
the @code{snippet}.
Could you send an updated patch?
Excellent work, thank you!
Ludo’.
