Re: [RFC] libdata-structure-util-perl: description

[Justin B Rye <jbr@edlug.org.uk>]

Franck Joncourt wrote:
> Description: module to change nature of data within a structure
>  Data::Structure::Util is a toolbox to manipulate the data inside a
>  data structure.  It can process an entire tree and perform the
>  operation requested on each appropriate element.
>  .
>  For example: It can transform all strings within a data structure to
>  utf8 or transform any utf8 string back to the default encoding.  It
>  can remove the blessing on any reference. It can collect all the
>  objects or detect if there is a circular reference.
>  .
>  It is written in C for decent speed.

Normally I'd say s/utf8/UTF-8/, but they're two different things in
Perl, aren't they?  So I'll keep quiet.  Wait, can it really
transform "ɧ" to ASCII? 

There are some inconsistent inter-sentence spacings (we standardise
on one space - some displays crush sequences anyway.)

I'd use lowercase after the colon ("For example: it can"), or maybe
even reorganise it to factor out the repetition:

   For example, it can: transform all strings within a data structure to
   utf8, or transform any utf8 string back to the default encoding;
   remove the blessing on any reference; collect all the objects; or
   detect if there is a circular reference.

(Which way looks better, like that or the bulletpoint version below?)

> I would be glad if someone could check the above description. I am not 
> sure about some sentences:
>
> module to change nature of data -> the nature?

It's hard to decide, but that does make it less "headlinese".

> to manipulate the data inside   -> to manipulate data inside?

Either way would be grammatical, but "the data" tends to imply "all
the data", so leaving it out is probably more strictly accurate.

And (I'm feeling really picky here) I wouldn't use "to" there; I'd
say "a toolbox for manipulating...", since you don't directly use
the toolbox as a whole to do the manipulating.

> Please CC me on replies since I am not subscribed to the mailing list.

How about:

  Description: module to change the nature of data within a structure
   Data::Structure::Util is a toolbox for manipulating data inside a
   data structure. It can process an entire tree and perform the
   operation requested on each appropriate element.
   .
   For example, it can:
    * transform all strings within a data structure to utf8;
    * transform any utf8 string back to the default encoding;
    * remove the blessing on any reference;
    * collect all the objects;
    * detect if there is a circular reference.
   .
   It is written in C for decent speed.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package