diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 4 | ||||
| -rw-r--r-- | doc/emacs.texi | 37 | ||||
| -rw-r--r-- | doc/guix.texi | 113 | ||||
| -rw-r--r-- | doc/package-hello.scm | 5 |
4 files changed, 125 insertions, 34 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 7b16ea3539..ded54348bc 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -207,6 +207,10 @@ please run through this check list: @enumerate @item +Take some time to provide an adequate synopsis and description for the +package. @xref{Synopses and Descriptions}, for some guidelines. + +@item Run @code{guix lint @var{package}}, where @var{package} is the name of the new or modified package, and fix any errors it reports (@pxref{Invoking guix lint}). diff --git a/doc/emacs.texi b/doc/emacs.texi index db2e657d27..67773466a4 100644 --- a/doc/emacs.texi +++ b/doc/emacs.texi @@ -11,6 +11,7 @@ Guix convenient and fun. * Package Management: Emacs Package Management. Managing packages and generations. * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. +* Build Log Mode: Emacs Build Log. Highlighting Guix build logs. * Completions: Emacs Completions. Completing @command{guix} shell command. @end menu @@ -571,6 +572,42 @@ mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example: @end example +@node Emacs Build Log +@section Build Log Mode + +GNU@tie{}Guix provides major and minor modes for highlighting build +logs. So when you have a file with a package build output---for +example, a file returned by @command{guix build --log-file @dots{}} +command (@pxref{Invoking guix build}), you may call @kbd{M-x +guix-build-log-mode} command in the buffer with this file. This major +mode highlights some lines specific to build output and provides the +following key bindings: + +@table @kbd + +@item M-n +Move to the next build phase. + +@item M-p +Move to the previous build phase. + +@item @key{TAB} +Toggle (show/hide) the body of the current build phase. + +@item S-@key{TAB} +Toggle (show/hide) the bodies of all build phases. + +@end table + +There is also @kbd{M-x guix-build-log-minor-mode} which also provides +the same highlighting (but not key bindings). And as it is a minor +mode, it can be enabled in any buffer. For example, if you are building +some package in a shell buffer (@pxref{Interactive Shell,,, emacs, The +GNU Emacs Manual}), you may enable @command{guix-build-log-minor-mode} +to make it more colorful. Guix build output is rather specific, so this +new highlighting shouldn't conflict with the existing one. + + @node Emacs Completions @section Shell Completions diff --git a/doc/guix.texi b/doc/guix.texi index 9ae91a8d1e..3ca4cefa63 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -45,9 +45,7 @@ Documentation License''. @titlepage @title GNU Guix Reference Manual @subtitle Using the GNU Guix Functional Package Manager -@author Ludovic Courtès -@author Andreas Enge -@author Nikita Karetnikov +@author The GNU Guix Developers @page @vskip 0pt plus 1filll @@ -114,6 +112,7 @@ Emacs Interface * Package Management: Emacs Package Management. Managing packages and generations. * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. +* Build Log Mode: Emacs Build Log. Highlighting Guix build logs. * Completions: Emacs Completions. Completing @command{guix} shell command. Programming Interface @@ -179,6 +178,7 @@ Services * X Window:: Graphical display. * Desktop Services:: D-Bus and desktop services. * Database Services:: SQL databases. +* Web Services:: Web servers. * Various Services:: Other services. Packaging Guidelines @@ -186,6 +186,7 @@ Packaging Guidelines * Software Freedom:: What may go into the distribution. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. +* Synopses and Descriptions:: Helping users find the right package. * Python Modules:: Taming the snake. * Perl Modules:: Little pearls. * Fonts:: Fond of fonts. @@ -1963,13 +1964,14 @@ package looks like this: (define-public hello (package (name "hello") - (version "2.8") + (version "2.10") (source (origin - (method url-fetch) - (uri (string-append "mirror://gnu/hello/hello-" version - ".tar.gz")) - (sha256 - (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6")))) + (method url-fetch) + (uri (string-append "mirror://gnu/hello/hello-" version + ".tar.gz")) + (sha256 + (base32 + "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) (build-system gnu-build-system) (arguments `(#:configure-flags '("--enable-silent-rules"))) (inputs `(("gawk" ,gawk))) @@ -2506,12 +2508,13 @@ This variable is exported by @code{(guix build-system ruby)}. It implements the RubyGems build procedure used by Ruby packages, which involves running @code{gem build} followed by @code{gem install}. -The @code{source} field of a package that uses this build system is -expected to reference a gem archive instead of a traditional tarball, -since this is the format that all Ruby developers use when releasing -their software. The build system unpacks the gem archive, potentially -patches the source, runs the test suite, repackages the gem, and -installs it. +The @code{source} field of a package that uses this build system +typically references a gem archive, since this is the format that Ruby +developers use when releasing their software. The build system unpacks +the gem archive, potentially patches the source, runs the test suite, +repackages the gem, and installs it. Additionally, directories and +tarballs may be referenced to allow building unreleased gems from Git or +a traditional source release tarball. Which Ruby package is used can be specified with the @code{#:ruby} parameter. A list of additional flags to be passed to the @command{gem} @@ -4217,8 +4220,11 @@ Identify inputs that should most likely be native inputs. @item source @itemx home-page +@itemx source-file-name Probe @code{home-page} and @code{source} URLs and report those that are -invalid. +invalid. Check that the source file name is meaningful, e.g. is not +just a version number or ``git-checkout'', and should not have a +@code{file-name} declared (@pxref{origin Reference}). @item formatting Warn about obvious source code formatting issues: trailing white space, @@ -5289,16 +5295,11 @@ variables. @defvr {Scheme Variable} %base-file-systems These are essential file systems that are required on normal systems, -such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see +such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see below.) Operating system declarations should always contain at least these. @end defvr -@defvr {Scheme Variable} %devtmpfs-file-system -The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a -requirement for udev (@pxref{Base Services, @code{udev-service}}). -@end defvr - @defvr {Scheme Variable} %pseudo-terminal-file-system This is the file system to be mounted as @file{/dev/pts}. It supports @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar @@ -7154,6 +7155,7 @@ needed is to review and apply the patch. * Software Freedom:: What may go into the distribution. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. +* Synopses and Descriptions:: Helping users find the right package. * Python Modules:: Taming the snake. * Perl Modules:: Little pearls. * Fonts:: Fond of fonts. @@ -7231,23 +7233,70 @@ For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows @example (define-public gtk+ (package - (name "gtk+") - (version "3.9.12") - ...)) + (name "gtk+") + (version "3.9.12") + ...)) (define-public gtk+-2 (package - (name "gtk+") - (version "2.24.20") - ...)) + (name "gtk+") + (version "2.24.20") + ...)) @end example If we also wanted GTK+ 3.8.2, this would be packaged as @example (define-public gtk+-3.8 (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example + (name "gtk+") + (version "3.8.2") + ...)) +@end example + +@node Synopses and Descriptions +@subsection Synopses and Descriptions + +As we have seen before, each package in GNU@tie{}Guix includes a +synopsis and a description (@pxref{Defining Packages}). Synopses and +descriptions are important: They are what @command{guix package +--search} searches, and a crucial piece of information to help users +determine whether a given package suits their needs. Consequently, +packagers should pay attention to what goes into them. + +Synopses must start with a capital letter and must not end with a +period. They must not start with ``a'' or ``the'', which usually does +not bring anything; for instance, prefer ``File-frobbing tool'' over ``A +tool that frobs files''. The synopsis should say what the package +is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is +used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines +matching a pattern''. + +Keep in mind that the synopsis must be meaningful for a very wide +audience. For example, ``Manipulate alignments in the SAM format'' +might make sense for a seasoned bioinformatics researcher, but might be +fairly unhelpful or even misleading to a non-specialized audience. It +is a good idea to come up with a synopsis that gives an idea of the +application domain of the package. In this example, this might give +something like ``Manipulate nucleotide sequence alignments'', which +hopefully gives the user a better idea of whether this is what they are +looking for. + +@cindex Texinfo markup, in package descriptions +Descriptions should take between five and ten lines. Use full +sentences, and avoid using acronyms without first introducing them. +Descriptions can include Texinfo markup, which is useful to introduce +ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or +hyperlinks (@pxref{Overview, overview of Texinfo,, texinfo, GNU +Texinfo}). User interfaces such as @command{guix package --show} take +care of rendering it appropriately. + +Synopses and descriptions are translated by volunteers +@uref{http://translationproject.org/domain/guix-packages.html, at the +Translation Project} so that as many users as possible can read them in +their native language. User interfaces search them and display them in +the language specified by the current locale. + +Translation is a lot of work so, as a packager, please pay even more +attention to your synopses and descriptions as every change may entail +additional work for translators. @node Python Modules diff --git a/doc/package-hello.scm b/doc/package-hello.scm index b3fcd4ff73..c57eb89108 100644 --- a/doc/package-hello.scm +++ b/doc/package-hello.scm @@ -4,13 +4,14 @@ (package (name "hello") - (version "2.8") + (version "2.10") (source (origin (method url-fetch) (uri (string-append "mirror://gnu/hello/hello-" version ".tar.gz")) (sha256 - (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6")))) + (base32 + "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) (build-system gnu-build-system) (synopsis "Hello, GNU world: An example GNU package") (description "Guess what GNU Hello prints!") |