From mboxrd@z Thu Jan 1 00:00:00 1970 From: ng0 Subject: Re: [PATCH] doc: The description should not be used as an introduction to generics. Date: Sun, 28 Aug 2016 21:26:15 +0000 Message-ID: <871t187fgo.fsf@we.make.ritual.n0.is> References: <874m67oiwj.fsf@we.make.ritual.n0.is> <87eg583b0w.fsf@openmailbox.org> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:38699) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1be7au-0007Or-MP for guix-devel@gnu.org; Sun, 28 Aug 2016 17:26:22 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1be7as-0004Np-Ae for guix-devel@gnu.org; Sun, 28 Aug 2016 17:26:19 -0400 Received: from mithlond.libertad.in-berlin.de ([2001:67c:1400:2490::1]:43717 helo=beleriand.n0.is) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1be7ar-0004NV-Vp for guix-devel@gnu.org; Sun, 28 Aug 2016 17:26:18 -0400 In-Reply-To: <87eg583b0w.fsf@openmailbox.org> 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: Lukas Gradl Cc: guix-devel@gnu.org Lukas Gradl writes: > [ Unknown signature status ] > 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 introduction 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-leading'', >> 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. Thanks for finding the mistake. Yes, it should probably be reworded, this was just what I wanted to get out. I will apply what you suggested and send an updated patch in the next days. >> 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 which >> +need explanation, keep it short and simple. >> >> @cindex Texinfo markup, in package descriptions >> Descriptions can include Texinfo markup, which is useful to introduce >> -- >> 2.9.3 -- ng0 For non-prism friendly talk find me on http://www.psyced.org