Re: Synopsis & description guidelines

[Mathieu Lirzin]

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