[email protected] (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 ‘@code’ or ‘@dfn’, 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
