From mboxrd@z Thu Jan  1 00:00:00 1970
From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=)
Subject: Re: [PATCH v2] gnu: Add sunxi-tools.
Date: Tue, 04 Oct 2016 15:15:39 +0200
Message-ID: <87vax88dc4.fsf@gnu.org>
References: <20161002115401.2bea3797@scratchpost.org>
	<20161002095836.6495-1-dannym@scratchpost.org>
	<874m4scvzh.fsf@gnu.org> <20161004120738.2351b604@scratchpost.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Return-path: <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([2001:4830:134:3::10]:39269)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ludo@gnu.org>) id 1brPZT-0003gO-PW
	for guix-devel@gnu.org; Tue, 04 Oct 2016 09:15:52 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <ludo@gnu.org>) id 1brPZO-0008WB-1n
	for guix-devel@gnu.org; Tue, 04 Oct 2016 09:15:46 -0400
In-Reply-To: <20161004120738.2351b604@scratchpost.org> (Danny Milosavljevic's
	message of "Tue, 4 Oct 2016 12:07:38 +0200")
List-Id: "Development of GNU Guix and the GNU System distribution."
	<guix-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/guix-devel/>
List-Post: <mailto:guix-devel@gnu.org>
List-Help: <mailto:guix-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=subscribe>
Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org
Sender: "Guix-devel" <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
To: Danny Milosavljevic <dannym@scratchpost.org>
Cc: guix-devel@gnu.org

Danny Milosavljevic <dannym@scratchpost.org> skribis:

>> I don=E2=80=99t understand this description.  Since =E2=80=9CTools=E2=80=
=9D, =E2=80=9Cmanage=E2=80=9D, and
>> =E2=80=9Cdevices=E2=80=9D could mean anything, could you add qualifiers =
to give more
>> context, like:
>>=20
>>   =E2=80=9CFrobbing tools for Allwinner A10 foobar devices=E2=80=9D
>>=20
>> and similarly expound the description (with a period at the end of the
>> sentence)?
>>=20
>> Based on that, we might device that admin.scm is not the best fit for
>> this package.  Maybe flashing-tools.scm?
>
> The tools included are:

I=E2=80=99m not asking that you explain it to me personally ;-), but rather=
 that
the description conveys a message that makes sense both for the domain
expert and the passerby.

  https://www.gnu.org/software/guix/manual/html_node/Synopses-and-Descripti=
ons.html

> So how about this description:
>
>     (description "This package contains tools for Allwinner A10 devices:
> - sunxi-fexc, bin2fex, fex2bin: Compile a textual description of a board =
(.fex) to a binary representation (.bin).
> - sunxi-fel: Puts a Allwinner A10 device into FEL mode which makes it reg=
ister as a special USB device (rather than USB host). You can then connect =
it to another computer and flash it from there.
> - sunxi-nand-part: Partitions NAND flash.
> - sunxi-bootinfo: Reads out boot0 and boot1 information. These are the bo=
otloaders before U-Boot.
> - sunxi-pio: Sets GPIO and oscillates a GPIO in order to be able to find =
it.
> ")

Sure.  Make sure to use @enumerate/@item for the list, and @command for
the command names.

This still doesn=E2=80=99t address the synopsis issue as I wrote above.  Wh=
at
about this synopsis:

  Hardware management tools for Allwinner A10 single-board computers

?

Please send a patch the addresses this and I=E2=80=99ll happily apply it!

Ludo=E2=80=99.