Re: [PATCH v2] gnu: Add sunxi-tools.

[Ludovic Courtès]

Danny Milosavljevic <address@hidden> skribis:

>> I don’t understand this description.  Since “Tools”, “manage”, and
>> “devices” could mean anything, could you add qualifiers to give more
>> context, like:
>> 
>>   “Frobbing tools for Allwinner A10 foobar devices”
>> 
>> and similarly expound the description (with a period at the end of the
>> sentence)?
>> 
>> 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’m 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-Descriptions.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 
> register 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 
> bootloaders 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’t address the synopsis issue as I wrote above.  What
about this synopsis:

  Hardware management tools for Allwinner A10 single-board computers

?

Please send a patch the addresses this and I’ll happily apply it!

Ludo’.