Synchronizing synopses with the Womb

Synchronizing synopses with the Womb

[Ludovic Courtès]

Hello Karl,

I’ve finally synchronized synopses of GNU packages found in the
distribution with those found in the Womb, thanks to the tools Nikita
added to Guix some time ago.

I ended up [0] using all the synopses from the Womb (they’re clear,
concise, and objective, whereas ours often repeated the package name,
and sometimes included subjective wording), except in two cases:

  gnu/packages/nano.scm:29:3: nano: proposed synopsis: "Free improved replacement for the pico text editor"
  gnu/packages/gdbm.scm:26:3: gdbm: proposed synopsis: "Hash library compatible with traditional dbm"

For Nano, I’m not sure it makes sense to mention Pico (Pico wasn’t free,
right?); instead we have "A small, user-friendly console text editor".

For gdbm, “hash library” seems misleading, and I think the word
“database” must appear; I would suggest: “Key/value database library”.

WDYT?

The tool for comparing synopses is now in the repo [1], and run from
‘dist-hook’.  It just reports differences.

Thanks,
Ludo’.

[0] http://git.savannah.gnu.org/cgit/guix.git/commit/?id=f50d2669e3e624365221cc81918ba55fdce94107
[1] http://git.savannah.gnu.org/cgit/guix.git/commit/?id=0e993428ce5ebd34d3bd9cb200140ffb2a5ef232

[PATCH] tests: Use a new synopsis of GNU Hello. (was: Synchronizing synopses with the Womb)

[Nikita Karetnikov]

[-- Attachment #1.1: Type: text/plain, Size: 53 bytes --]

Is it fine?

(I removed tabs using 'M-x untabify'.)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-tests-Use-a-new-synopsis-of-GNU-Hello.patch --]
[-- Type: text/x-diff, Size: 1959 bytes --]

From 2d0563884dd6d0633dd34419512c49cdeb114e1b Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Thu, 18 Apr 2013 15:22:40 +0000
Subject: [PATCH] tests: Use a new synopsis of GNU Hello.

* tests/guix-package.sh: Use a new synopsis of GNU Hello, which was
  added in f50d2669e3e624365221cc81918ba55fdce94107.
---
 tests/guix-package.sh |   21 +++++++++++----------
 1 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/tests/guix-package.sh b/tests/guix-package.sh
index f84893b..7b101aa 100644
--- a/tests/guix-package.sh
+++ b/tests/guix-package.sh
@@ -62,18 +62,19 @@ then
     # name and version string.
     installed="`guix package -p "$profile" --list-installed | cut -f1 | xargs echo | sort`"
     case "x$installed" in
-	"guile-bootstrap make-boot0")
-	    true;;
-	"make-boot0 guile-bootstrap")
-	    true;;
-	"*")
+        "guile-bootstrap make-boot0")
+            true;;
+        "make-boot0 guile-bootstrap")
+            true;;
+        "*")
             false;;
     esac
 
     test "`guix package -p "$profile" -I 'g.*e' | cut -f1`" = "guile-bootstrap"
 
     # Search.
-    test "`guix package -s "GNU Hello" | grep ^name:`" = "name: hello"
+    test "`guix package -s "An example GNU package" | grep ^name:`" = \
+        "name: hello"
     test "`guix package -s "n0t4r341p4ck4g3"`" = ""
 
     # Remove a package.
@@ -92,10 +93,10 @@ then
     # Move to the empty profile.
     for i in `seq 1 3`
     do
-	guix package --bootstrap --roll-back -p "$profile"
-	! test -f "$profile/bin"
-	! test -f "$profile/lib"
-	test "`readlink_base "$profile"`" = "$profile-0-link"
+        guix package --bootstrap --roll-back -p "$profile"
+        ! test -f "$profile/bin"
+        ! test -f "$profile/lib"
+        test "`readlink_base "$profile"`" = "$profile-0-link"
     done
 
     # Reinstall after roll-back to the empty profile.
-- 
1.7.5.4


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: [PATCH] tests: Use a new synopsis of GNU Hello.

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> Is it fine?

Yes sure, sorry for not catching it!

Ludo’.

Re: Synchronizing synopses with the Womb

[Karl Berry]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1935 bytes --]

    For Nano, Iœôòùm not sure it makes sense to mention Pico (Pico wasnœôòùt free,
    right?); instead we have "A small, user-friendly console text editor".

Agreed.  Except, trivial, there is no need for "A" here.  So I changed
it to:

doc-summary: Small, user-friendly console text editor

The other one is more problematic, though I certainly don't feel
absolutist about it.

    For gdbm, œôòühash libraryœôòý seems misleading, and I think the word
    œôòüdatabaseœôòý must appear; 

Because I put it in category Database?  Maybe that was wrong and the
more generic "Software libraries" would be better.

    I would suggest: œôòüKey/value database libraryœôòý.

Looking at it now ... to me, gdbm is precisely *not* a database, in the
sense of, say, postgresql or mysql or sqlite.  And thus using the term
in the description would be more confusing than helpful?

The other things I put in the Database category
(http://www.gnu.org/manual/#Database) all seem to be actual programs,
not just libraries.

Looking again at the gdbm web page (which is where I started), it starts
with:
    gdbm ... a library of database functions that use extensible hashing
    and work similar to the standard UNIX dbm.

So how about:
doc-summary: Hash library of database functions compatible with traditional dbm

I think the dbm reference is important, because many Unix programmers
and programs have heard of dbm and ndbm and will immediately know
exactly what it is.

I can't say I'm enthused about verbose "key/value" instead of "hash" --
are we not allowed to use technical terms any more :)?  Either would be
ok, but key/value will make my line >79 chars :).


However, it's more important to me that we come up with something we can
both live with than insisting on any particular point, so let me know.

Thanks,
Karl

P.S. Did you talk with Brandon about synchronizing the guix/gsrc
long(er) descriptions?  He was going to write you ...

Re: Synchronizing synopses with the Womb

[Ludovic Courtès]

karl@freefriends.org (Karl Berry) skribis:

>     For Nano, I’m not sure it makes sense to mention Pico (Pico wasn’t free,
>     right?); instead we have "A small, user-friendly console text editor".
>
> Agreed.  Except, trivial, there is no need for "A" here.  So I changed
> it to:
>
> doc-summary: Small, user-friendly console text editor

Perfect.

[...]

> So how about:
> doc-summary: Hash library of database functions compatible with traditional dbm

Looks good to me!

> I can't say I'm enthused about verbose "key/value" instead of "hash" --
> are we not allowed to use technical terms any more :)?  Either would be
> ok, but key/value will make my line >79 chars :).

It’s just that, as a gdbm user, the abstraction I manipulate is
key/value associations.  But what you suggest is fine with me.  :-)

> P.S. Did you talk with Brandon about synchronizing the guix/gsrc
> long(er) descriptions?  He was going to write you ...

Oh, not yet.  I had overlooked the fact that GSRC also has longer
descriptions.

It would be good to synchronize before Guix is added to the Translation
Project.

Thanks!

Ludo’.

Re: Synchronizing synopses with the Womb

[Brandon Invergo]

[-- Attachment #1: Type: text/plain, Size: 703 bytes --]

>> P.S. Did you talk with Brandon about synchronizing the guix/gsrc
>> long(er) descriptions?  He was going to write you ...
>
> Oh, not yet.  I had overlooked the fact that GSRC also has longer
> descriptions.
>
> It would be good to synchronize before Guix is added to the Translation
> Project.

Yes, I was going to send a message to the Guix list but it seems Karl
beat me to it. 

As of this past release, all of the GNU packages in GSRC have longer
descriptions as well as short ones. I like the idea of syncing with the
short descriptions in Womb and syncing the longer descriptions between
GSRC and Guix. How shall we proceed?

-- 
Brandon Invergo
http://brandon.invergo.net

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: Synchronizing synopses with the Womb

[Ludovic Courtès]

Brandon Invergo <brandon@gnu.org> skribis:

>>> P.S. Did you talk with Brandon about synchronizing the guix/gsrc
>>> long(er) descriptions?  He was going to write you ...
>>
>> Oh, not yet.  I had overlooked the fact that GSRC also has longer
>> descriptions.
>>
>> It would be good to synchronize before Guix is added to the Translation
>> Project.
>
> Yes, I was going to send a message to the Guix list but it seems Karl
> beat me to it. 

Heh.  :-)

> As of this past release, all of the GNU packages in GSRC have longer
> descriptions as well as short ones. I like the idea of syncing with the
> short descriptions in Womb and syncing the longer descriptions between
> GSRC and Guix. How shall we proceed?

Is there any easy way to extract long descriptions from GSRC?  There
could be a script in Guix, similar to what we have for the Womb.  I
suspect it might be a bit more work, though.

Ludo’.

Re: Synchronizing synopses with the Womb

[Brandon Invergo]

[-- Attachment #1: Type: text/plain, Size: 2010 bytes --]


> Is there any easy way to extract long descriptions from GSRC?  There
> could be a script in Guix, similar to what we have for the Womb.  I
> suspect it might be a bit more work, though.

I took inspiration from you guys and made a way to output package
information in the Recutils recfile format. An entire package manifest
in recfile format can be made with "make manifest" in the top-level GSRC
directory (it's also included by default in the last distribution,
gsrc-2013-04-06.tar.gz, but I recommend checking out the bzr repo).=20

Once MANIFEST.rec has been built, it is simple to get the info with
recsel. The field "Garname" contains the simple one-word package name
(always the same name used in forming URLs on the GNU web and FTP sites
and, i.e. at http://www.gnu.org/software/$Garname). The long description
is contained in the "Blurb" field.=20

    $ recsel -e "Garname =3D 'hello'" -P "Blurb" MANIFEST.rec=20
    GNU Hello prints the message "Hello, world!" and then exits.  It=20
    serves as an example of standard GNU coding practices.  As such, it
    supports command-line arguments, multiple languages, and so on.

    $ recsel -e "Garname =3D 'src-highlite'" -P "Blurb" MANIFEST.rec
    Source-highlight reads in a source code file and produces an output
    file in which the keywords are highlighted in different colors to
    designate their syntactic role.  It supports over 150 different
    languages and it can output to 8 different formats, including HTML,
    LaTeX and ODF.  It can also output to ANSI color escape sequences,
    allowing, for example, GNU less to show highlighted source code.

Of course, I welcome any suggested changes or corrections to the
descriptions. As you can imagine, doing a marathon of describing
hundreds of GNU packages alone might have led to some poor wording in
places.=20

I'll get to work on changing the short descriptions to match those of
Womb...

-- 
Brandon Invergo
http://brandon.invergo.net

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: Synchronizing synopses with the Womb

[Brandon Invergo]

[-- Attachment #1: Type: text/plain, Size: 2105 bytes --]

Hmm...not sure what I did to add all those funny characters to the
email. I'll fix it:


> Is there any easy way to extract long descriptions from GSRC?  There
> could be a script in Guix, similar to what we have for the Womb.  I
> suspect it might be a bit more work, though.

 I took inspiration from you guys and made a way to output package
 information in the Recutils recfile format. An entire package manifest
 in recfile format can be made with "make manifest" in the top-level GSRC
 directory (it's also included by default in the last distribution,
 gsrc-2013-04-06.tar.gz, but I recommend checking out the bzr repo).

 Once MANIFEST.rec has been built, it is simple to get the info with
 recsel. The field "Garname" contains the simple one-word package name
 (always the same name used in forming URLs on the GNU web and FTP sites
 and, i.e. at http://www.gnu.org/software/$Garname). The long description
 is contained in the "Blurb" field.

     $ recsel -e "Garname = 'hello'" -P "Blurb" MANIFEST.rec
     GNU Hello prints the message "Hello, world!" and then exits.  It
     serves as an example of standard GNU coding practices.  As such, it
     supports command-line arguments, multiple languages, and so on.

     $ recsel -e "Garname 'src-highlite'" -P "Blurb" MANIFEST.rec
     Source-highlight reads in a source code file and produces an output
     file in which the keywords are highlighted in different colors to
     designate their syntactic role.  It supports over 150 different
     languages and it can output to 8 different formats, including HTML,
     LaTeX and ODF.  It can also output to ANSI color escape sequences,
     allowing, for example, GNU less to show highlighted source code.

 Of course, I welcome any suggested changes or corrections to the
 descriptions. As you can imagine, doing a marathon of describing
 hundreds of GNU packages alone might have led to some poor wording in
 places.

 I'll get to work on changing the short descriptions to match those of
 Womb...
-- 
Brandon Invergo
http://brandon.invergo.net

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: Synchronizing synopses with the Womb

[Ludovic Courtès]

Brandon Invergo <brandon@gnu.org> skribis:

>> Is there any easy way to extract long descriptions from GSRC?  There
>> could be a script in Guix, similar to what we have for the Womb.  I
>> suspect it might be a bit more work, though.
>
>  I took inspiration from you guys and made a way to output package
>  information in the Recutils recfile format. An entire package manifest
>  in recfile format can be made with "make manifest" in the top-level GSRC
>  directory (it's also included by default in the last distribution,
>  gsrc-2013-04-06.tar.gz, but I recommend checking out the bzr repo).

Great.  I was able to build it (with $srcdir = $buildir).

Is there a place on-line where a pre-built MANIFEST.rec is/could be made
available?  That would simplify automation on the Guix side (for the
Womb, we just take gnupackages.txt from CVSWeb.)

[...]

>  Of course, I welcome any suggested changes or corrections to the
>  descriptions. As you can imagine, doing a marathon of describing
>  hundreds of GNU packages alone might have led to some poor wording in
>  places.

How do you usually come up with those descriptions?  I typically take a
paragraph or two from the package’s home page.

Thanks!

Ludo’.

Re: Synchronizing synopses with the Womb

[Brandon Invergo]

[-- Attachment #1: Type: text/plain, Size: 1374 bytes --]

> Is there a place on-line where a pre-built MANIFEST.rec is/could be made
> available?  That would simplify automation on the Guix side (for the
> Womb, we just take gnupackages.txt from CVSWeb.)

That can easily be arranged. I'll just upload it with the script that I
use to update the package list website
(gnu.org/s/gsrc/package-list.html).

It will be at www.gnu.org/s/gsrc/MANIFEST.rec shortly. At the moment I
have it set as a weekly cron job to update it.

> How do you usually come up with those descriptions?  I typically take a
> paragraph or two from the package’s home page.

Well, I tried to avoid copying verbatim from the home pages. I doubt
that any of the maintainers will try to assert copyright but I wanted to
be careful anyway. Regardless, the descriptions still mainly came from
the sites, supplemented by README files, Savannah and, when I didn't
understand some concept or term, Wikipedia. All went through the
in-your-own-words filter. Sometimes the websites went into way too much
detail, so I had to pick and choose the information to cover. Other
times, they didn't give nearly enough information so I had to use my own
experience with the program to add to them a bit. I didn't have any
specific length requirements but I aimed for about a paragraph.

Cheers,
-b

-- 
Brandon Invergo
http://brandon.invergo.net

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: Synchronizing synopses with the Womb

[Brandon Invergo]

[-- Attachment #1: Type: text/plain, Size: 232 bytes --]

> It will be at www.gnu.org/s/gsrc/MANIFEST.rec shortly.

Ok it's up now.

Also, I can officially report that GSRC short descriptions are synced to
Womb as well.

-brandon

-- 
Brandon Invergo
http://brandon.invergo.net

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]