[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Synopsis & description guidelines
From: |
Mathieu Lirzin |
Subject: |
Re: Synopsis & description guidelines |
Date: |
Wed, 16 Sep 2015 00:28:56 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
address@hidden (Ludovic Courtès) writes:
> I wanted to add a note somewhere in the manual about Texinfo markup and
> ended up writing a section on synopses and descriptions (see below.)
Thanks for taking the time to do it!
> 7.6.4 Synopses and 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 address@hidden or address@hidden, bullet lists, or
> hyperlinks (*note
> overview of Texinfo: (texinfo)Overview.). User interfaces such as ‘guix
> package --show’ take care of rendering it appropriately.
Maybe will it could be useful to indicate that '@' '{' and '}' are
treated specially by giving a cross reference to (info "(texinfo)Special
Characters") ?
> Synopses and descriptions are translated by volunteers at the
> Translation Project
> (http://translationproject.org/domain/guix-packages.html) 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.
In the context of package descriptions, will comments extraction work?
;; TRANSLATORS: ...
(description "")
If it's working, it can be interesting to document it. It would be
useful when usage of obscure terminologies is inevitable. WDYT?
--
Mathieu Lirzin