From mboxrd@z Thu Jan 1 00:00:00 1970 From: Lukas Gradl Subject: Re: [PATCH] doc: The description should not be used as an introduction to generics. Date: Sun, 28 Aug 2016 15:15:43 -0500 Message-ID: <87eg583b0w.fsf@openmailbox.org> References: <874m67oiwj.fsf@we.make.ritual.n0.is> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35338) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1be74k-0000iv-A6 for guix-devel@gnu.org; Sun, 28 Aug 2016 16:53:10 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1be74f-0007nU-FO for guix-devel@gnu.org; Sun, 28 Aug 2016 16:53:05 -0400 Received: from smtp26.openmailbox.org ([62.4.1.60]:35932 helo=smtp11.openmailbox.org) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1be74f-0007nB-5z for guix-devel@gnu.org; Sun, 28 Aug 2016 16:53:01 -0400 In-Reply-To: <874m67oiwj.fsf@we.make.ritual.n0.is> (ng0@we.make.ritual.n0.is's message of "Fri, 26 Aug 2016 11:43:08 +0000") 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" To: ng0 Cc: guix-devel@gnu.org --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable ng0 writes: > From e399e9a982e8a14e4e7f66d5318d3cf7919a81fb Mon Sep 17 00:00:00 2001 > From: ng0 > Date: Fri, 26 Aug 2016 11:16:27 +0000 > Subject: [PATCH] doc: The description should not be used as an introducti= on to > generics. > > * doc/guix.texi (Synopses and Description): Generic terms like > "tiling window manager" should not be explained in full length > in the description, only explain generic terms when no external > resources explain them and if you need to explain them, keep it > short and simple. > --- > doc/guix.texi | 5 +++++ > 1 file changed, 5 insertions(+) > > diff --git a/doc/guix.texi b/doc/guix.texi > index 5330238..48512e8 100644 > --- a/doc/guix.texi > +++ b/doc/guix.texi > @@ -11676,6 +11676,11 @@ Please avoid marketing phrases such as ``world-l= eading'', > like ``the most advanced''---they are not helpful to users looking for a > package and may even sound suspicious. Instead, try to be factual, > mentioning use cases and features. > +Please avoid giving introductions to generic and repetive concepts ^ I am not an English native speaker but ispell thinks this should be 'repetitive'. In that case it may be better to just say 'generic concepts' since the concepts themselves are not repetitive only their explanations are repeated often? I do not have a strong opinion though. > which > +can can be found at external resources, such as ``tiling window manager'= '. > +Rather than giving an introduction to a topic in what should be a short > +description, think about its unique features. If there are features whi= ch > +need explanation, keep it short and simple. >=20=20 > @cindex Texinfo markup, in package descriptions > Descriptions can include Texinfo markup, which is useful to introduce > --=20 > 2.9.3 --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBCAAGBQJXw0ZwAAoJEFP7dyh+2DCRHnYQAIFf0VPiHd3tfPZYS6hXLt5X U8ZY3Fer0WqpgQP3sK42w2Ug31IyVVYxt08YhXmewosyekVhoeQdHV380+1ffwt6 DHPiwUa+YpmUB+BCbf9QF+7/6TxQ8xNA+ftw3+JuSuIx7RJafl5uauMltGeTz/uR 9Wjm38upz12voU4o+ONq0V1Y5xgwDEm/mnntagyb/bvBWIdKs7PJGRcToIHf2Jlh I/J6E/kqw2T7Zb5ehYUZp2aWXJ9vLS1p9TBA6674uzkQgock2LikZw2dAKLQb3P1 zt3YnWYp2hyoksLp+1uLeOom7aTVy33aY9sybHpeLXpCEvhNIeqtzbsSgsZpsRRg V+plkGpFa/spJ8DonY3iaeed73AgimgIO3UjWrFXvdic3xc0VyUEasKVE4k9Nx3n otuTwUDsdtEqg/wnbJ5tth5z5j40SzOzfJxFJmZM4qXXW2byhJ4WIktoUCFNtGxM VhL0X4j31hqWtKFEB1u3ggOw0bAkeAHiQMQ5HMttRroC8C2Ym1bSKZqsFczL4D78 Yo6WuI5W8tSj5xJpeKcbUoSv+S7LegstTNnX5HUoeAIjB8fh6SGCt7Ipa3VLTdbH kRgElJ04ETZ/ygXOc5nuAHPXZuDRa7KKJg+4iRaKMa3k9uRrXw6D2PQ3X8lAJTnT Zb52VPHheUQEY6jhg71S =PsJI -----END PGP SIGNATURE----- --=-=-=--