From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mathieu Lirzin Subject: [PATCH] doc: Add more recommandations for package descriptions. Date: Sun, 27 Sep 2015 01:31:35 +0200 Message-ID: <1443310295-17293-1-git-send-email-mthl@openmailbox.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------2.5.3" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39693) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zfyx7-00055x-Ee for guix-devel@gnu.org; Sat, 26 Sep 2015 19:32:26 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Zfyx3-0002uK-Dh for guix-devel@gnu.org; Sat, 26 Sep 2015 19:32:25 -0400 Received: from smtp8.openmailbox.org ([62.4.1.42]:51271) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zfyx3-0002tc-4j for guix-devel@gnu.org; Sat, 26 Sep 2015 19:32:21 -0400 List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: guix-devel@gnu.org This is a multi-part message in MIME format. --------------2.5.3 Content-Type: text/plain; charset=UTF-8; format=fixed Content-Transfer-Encoding: quoted-printable * doc/guix.texi (Synopses and Descriptions): Warn about special characters in Texinfo. Indicate how to help the translators. --- doc/guix.texi | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) --------------2.5.3 Content-Type: text/x-patch; name="0001-doc-Add-more-recommandations-for-package-description.patch" Content-Disposition: inline; filename="0001-doc-Add-more-recommandations-for-package-description.patch" Content-Transfer-Encoding: quoted-printable diff --git a/doc/guix.texi b/doc/guix.texi index 8608e7a..dfd054e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7294,9 +7294,12 @@ Descriptions should take between five and ten line= s. 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. +hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you +should be careful when using some characters for example @samp{@@} and +curly braces which are the basic special characters in Texinfo +(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces +such as @command{guix package --show} take care of rendering it +appropriately. =20 Synopses and descriptions are translated by volunteers @uref{http://translationproject.org/domain/guix-packages.html, at the @@ -7306,7 +7309,16 @@ the language specified by the current locale. =20 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. +additional work for translators. In order to help them, it is possible +to make recommandations or instructions visible to them by inserting +special comments like this (@pxref{xgettext Invocation,,, gettext, GNU +Gettext}): + +@example +;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. +(description "ARandR is designed to provide a simple visual front end +for the X11 resize-and-rotate (RandR) extension. @dots{}") +@end example =20 =20 @node Python Modules --------------2.5.3--