Re: Synopsis & description guidelines

[Ludovic Courtès]

Mathieu Lirzin <address@hidden> skribis:

> address@hidden (Ludovic Courtès) writes:

[...]

>>    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") ?

Why not.  Would you like to do that?

>>    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 "")

Yes, see f4e92db.  The string literal must start on the same line as
‘description’.

> If it's working, it can be interesting to document it.  It would be
> useful when usage of obscure terminologies is inevitable.  WDYT?

Hopefully descriptions will rarely use obscure terms, but yes, we could
add a note about it with a xref to xgettext.

Thanks,
Ludo’.