Re: [PATCH] doc: Document native-inputs and propagated-inputs.

[Ludovic Courtès]

address@hidden (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?=
>  <address@hidden>
> 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.)

> address@hidden package Reference
> address@hidden package Reference

@subsection @code{package} Reference

(Same for the second subsection.)

> +This section summarizes all the options available in ‘package’

@code{package}

> address@hidden @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.

> address@hidden @code{outputs} (default: @code{'("out")})
> +The list of output names of the package.

+ @xref{Packages with Multiple Outputs}, for typical uses of additional
outputs.

> address@hidden @code{native-search-paths} (default: @code{'()})
> +FIXME
> +
> address@hidden @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.  ;-)

> address@hidden @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.

> address@hidden @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.

> address@hidden @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.)


[...]

> address@hidden {Data Type} origin
> +This is the data type representing a source code origin.
> +
> address@hidden @asis
> address@hidden @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.

> address@hidden @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

> address@hidden @code{sha256}
> +A bytevector containing the SHA-256 hash of the source.  Typically the
> address@hidden procedure is used here to generate the bytevector from a

s/procedure/form/

> address@hidden @code{patch-inputs} (default: @code{#f})
> +Input packages or derivations to the patching process.  When this is
> address@hidden, the usual set of inputs necessary for patching are provided,
> +such as GNU Patch.

address@hidden

> address@hidden @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’.