[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
02/03: doc: Add guidelines for synopses and descriptions.
From: |
Ludovic Courtès |
Subject: |
02/03: doc: Add guidelines for synopses and descriptions. |
Date: |
Tue, 15 Sep 2015 20:50:49 +0000 |
civodul pushed a commit to branch master
in repository guix.
commit cbd02397b523e167c7db9775eee1be71f110482c
Author: Ludovic Courtès <address@hidden>
Date: Tue Sep 15 22:37:12 2015 +0200
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.
---
doc/contributing.texi | 4 +++
doc/guix.texi | 50 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 54 insertions(+), 0 deletions(-)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 7b16ea3..ded5434 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.
+
address@hidden
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 e3c7660..cfe8390 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
address@hidden Synopses and Descriptions
address@hidden Synopses and Descriptions
+
+As we have seen before, each package in address@hidden 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 address@hidden 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.
+
address@hidden 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
address@hidden://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