* [PATCH] doc: Add more recommandations for package descriptions.
@ 2015-09-26 23:31 Mathieu Lirzin
2015-09-27 20:31 ` Ludovic Courtès
2015-09-27 22:45 ` Mark H Weaver
0 siblings, 2 replies; 3+ messages in thread
From: Mathieu Lirzin @ 2015-09-26 23:31 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 232 bytes --]
* 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(-)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Add-more-recommandations-for-package-description.patch --]
[-- Type: text/x-patch; name="0001-doc-Add-more-recommandations-for-package-description.patch", Size: 1829 bytes --]
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 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.
+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.
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.
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
@node Python Modules
^ permalink raw reply related [flat|nested] 3+ messages in thread
end of thread, other threads:[~2015-09-27 22:46 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-09-26 23:31 [PATCH] doc: Add more recommandations for package descriptions Mathieu Lirzin
2015-09-27 20:31 ` Ludovic Courtès
2015-09-27 22:45 ` Mark H Weaver
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).