aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2015-09-15 22:37:12 +0200
committerLudovic Courtès <ludo@gnu.org>2015-09-15 22:48:52 +0200
commitcbd02397b523e167c7db9775eee1be71f110482c (patch)
treebb6589d5a5f9ce9a749e46511fdb2160d64eafc1
parent2cbed07eef96648948cfec2e225b9dfe6f08d72c (diff)
downloadguix-cbd02397b523e167c7db9775eee1be71f110482c.tar
guix-cbd02397b523e167c7db9775eee1be71f110482c.tar.gz
doc: Add guidelines for synopses and descriptions.
* doc/guix.texi (Synopses and Descriptions): New node. * doc/contributing.texi (Submitting Patches): Add item that cross-references it.
-rw-r--r--doc/contributing.texi4
-rw-r--r--doc/guix.texi50
2 files changed, 54 insertions, 0 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/guix.texi b/doc/guix.texi
index e3c7660b72..cfe83909da 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -178,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
@@ -185,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.
@@ -7158,6 +7160,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.
@@ -7253,6 +7256,53 @@ If we also wanted GTK+ 3.8.2, this would be packaged as
...))
@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
@subsection Python Modules