From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mathieu Lirzin Subject: Re: Synopsis & description guidelines Date: Wed, 16 Sep 2015 00:28:56 +0200 Message-ID: <87si6fco5z.fsf@openmailbox.org> References: <87fv2fe6zt.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:44339) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zbyiu-0006nv-R4 for guix-devel@gnu.org; Tue, 15 Sep 2015 18:29:13 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Zbyiq-00087D-Ky for guix-devel@gnu.org; Tue, 15 Sep 2015 18:29:12 -0400 Received: from smtp24.openmailbox.org ([62.4.1.58]:56890) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zbyiq-000872-CG for guix-devel@gnu.org; Tue, 15 Sep 2015 18:29:08 -0400 In-Reply-To: <87fv2fe6zt.fsf@gnu.org> ("Ludovic \=\?utf-8\?Q\?Court\=C3\=A8s\=22'\?\= \=\?utf-8\?Q\?s\?\= message of "Tue, 15 Sep 2015 22:56:54 +0200") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: guix-devel ludo@gnu.org (Ludovic Court=C3=A8s) 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 =E2=80=98@code=E2=80=99 or =E2=80=98@dfn=E2=80=99, bull= et lists, or hyperlinks (*note > overview of Texinfo: (texinfo)Overview.). User interfaces such as =E2=80= =98guix > package --show=E2=80=99 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