Should synopsis handle texinfo markup?

Should synopsis handle texinfo markup?

[Alex Kost]

Hello, I've noticed that several packages contain "@code" structures in
their synopses, but only 'description' field supports texinfo markup.
For example, look at:

  guix package -s ruby-minitest-bonus-assertions

So I wonder, should these synopses be adjusted to remove @code things,
or would it be better to make sysnopses support it?

-- 
Alex

Re: Should synopsis handle texinfo markup?

[John Darrington]

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

On Sat, Mar 11, 2017 at 10:27:57PM +0300, Alex Kost wrote:
     Hello, I've noticed that several packages contain "@code" structures in
     their synopses, but only 'description' field supports texinfo markup.
     For example, look at:
     
       guix package -s ruby-minitest-bonus-assertions
     
     So I wonder, should these synopses be adjusted to remove @code things,
     or would it be better to make sysnopses support it?

... and, if we decide that synopses may not have Texinfo markup, then we
should have guix lint check for it.

J'

-- 
Avoid eavesdropping.  Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.


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

Re: Should synopsis handle texinfo markup?

[Ludovic Courtès]

Hi Alex,

Alex Kost <alezost@gmail.com> skribis:

> Hello, I've noticed that several packages contain "@code" structures in
> their synopses, but only 'description' field supports texinfo markup.
> For example, look at:
>
>   guix package -s ruby-minitest-bonus-assertions
>
> So I wonder, should these synopses be adjusted to remove @code things,
> or would it be better to make sysnopses support it?

Maybe we should support Texinfo in synopses after all.  I don’t think
there were good reasons not to do it.

Thoughts?

Ludo’.

Re: Should synopsis handle texinfo markup?

[Alex Kost]

Ludovic Courtès (2017-03-15 17:14 +0100) wrote:

> Hi Alex,
>
> Alex Kost <alezost@gmail.com> skribis:
>
>> Hello, I've noticed that several packages contain "@code" structures in
>> their synopses, but only 'description' field supports texinfo markup.
>> For example, look at:
>>
>>   guix package -s ruby-minitest-bonus-assertions
>>
>> So I wonder, should these synopses be adjusted to remove @code things,
>> or would it be better to make sysnopses support it?
>
> Maybe we should support Texinfo in synopses after all.  I don’t think
> there were good reasons not to do it.
>
> Thoughts?

I'm not aware of potential problems so I think it would be good to add
this support to synopses.

-- 
Alex

Re: Should synopsis handle texinfo markup?

[Ludovic Courtès]

Alex Kost <alezost@gmail.com> skribis:

> Ludovic Courtès (2017-03-15 17:14 +0100) wrote:
>
>> Hi Alex,
>>
>> Alex Kost <alezost@gmail.com> skribis:
>>
>>> Hello, I've noticed that several packages contain "@code" structures in
>>> their synopses, but only 'description' field supports texinfo markup.
>>> For example, look at:
>>>
>>>   guix package -s ruby-minitest-bonus-assertions
>>>
>>> So I wonder, should these synopses be adjusted to remove @code things,
>>> or would it be better to make sysnopses support it?
>>
>> Maybe we should support Texinfo in synopses after all.  I don’t think
>> there were good reasons not to do it.
>>
>> Thoughts?
>
> I'm not aware of potential problems so I think it would be good to add
> this support to synopses.

Cool.  Would you or anyone like to give it a try?  Alternatively we can
mail it to bug-guix for later.

Ludo’.

Re: Should synopsis handle texinfo markup?

[Alex Kost]

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

Ludovic Courtès (2017-03-16 23:29 +0100) wrote:

> Alex Kost <alezost@gmail.com> skribis:
>
>> Ludovic Courtès (2017-03-15 17:14 +0100) wrote:
>>
>>> Alex Kost <alezost@gmail.com> skribis:
>>>
>>>> Hello, I've noticed that several packages contain "@code" structures in
>>>> their synopses, but only 'description' field supports texinfo markup.
>>>> For example, look at:
>>>>
>>>>   guix package -s ruby-minitest-bonus-assertions
>>>>
>>>> So I wonder, should these synopses be adjusted to remove @code things,
>>>> or would it be better to make sysnopses support it?
>>>
>>> Maybe we should support Texinfo in synopses after all.  I don’t think
>>> there were good reasons not to do it.
>>>
>>> Thoughts?
>>
>> I'm not aware of potential problems so I think it would be good to add
>> this support to synopses.
>
> Cool.  Would you or anyone like to give it a try?  Alternatively we can
> mail it to bug-guix for later.

I gave it a try (the patch is attached).  I hope I didn't miss anything.


[-- Attachment #2: 0001-ui-Support-Texinfo-markup-in-package-synopses.patch --]
[-- Type: text/x-patch, Size: 5214 bytes --]

From 8d8a79d69619b68dd3a798e7456bfd871fcb8395 Mon Sep 17 00:00:00 2001
From: Alex Kost <alezost@gmail.com>
Date: Mon, 20 Mar 2017 13:41:41 +0300
Subject: [PATCH] ui: Support Texinfo markup in package synopses.

* guix/ui.scm (package-field-string): New procedure.
(package-description-string): Use it.
(package-synopsis-string): New procedure.
(package->recutils): Use it.
* guix/scripts/lint.scm (check-synopsis-style)[check-texinfo-markup]:
New procedure.  Use it in checks.
* gnu/packages/perl.scm (perl-try-tiny)[synopsis]: Adjust for the
Texinfo markup.
---
 gnu/packages/perl.scm |  2 +-
 guix/scripts/lint.scm | 22 +++++++++++++++++++---
 guix/ui.scm           | 17 +++++++++++++----
 3 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/gnu/packages/perl.scm b/gnu/packages/perl.scm
index 840e0b7..c415208 100644
--- a/gnu/packages/perl.scm
+++ b/gnu/packages/perl.scm
@@ -7580,7 +7580,7 @@ Tree::Simple::Visitor::* objects.")
          "068vdbpacfawc3lkfs0b82xxl27h3l0gj14iada3vlwk8rps9yv0"))))
     (build-system perl-build-system)
     (home-page "http://search.cpan.org/dist/Try-Tiny")
-    (synopsis "Minimal try/catch with proper preservation of $@")
+    (synopsis "Minimal try/catch with proper preservation of $@@")
     (description "This module provides bare bones try/catch/finally statements
 that are designed to minimize common mistakes with eval blocks, and nothing
 else.")
diff --git a/guix/scripts/lint.scm b/guix/scripts/lint.scm
index 66c82f0..811f167 100644
--- a/guix/scripts/lint.scm
+++ b/guix/scripts/lint.scm
@@ -5,6 +5,7 @@
 ;;; Copyright © 2015, 2016 Mathieu Lirzin <mthl@gnu.org>
 ;;; Copyright © 2016 Danny Milosavljevic <dannym+a@scratchpost.org>
 ;;; Copyright © 2016 Hartmut Goebel <h.goebel@crazy-compilers.com>
+;;; Copyright © 2017 Alex Kost <alezost@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -347,10 +348,25 @@ the synopsis")
                     (_ "synopsis should not start with the package name")
                     'synopsis)))
 
+  (define (check-texinfo-markup synopsis)
+    "Check that SYNOPSIS can be parsed as a Texinfo fragment.  If the
+markup is valid return a plain-text version of SYNOPSIS, otherwise #f."
+    (catch #t
+      (lambda () (texi->plain-text synopsis))
+      (lambda (keys . args)
+        (emit-warning package
+                      (_ "Texinfo markup in synopsis is invalid")
+                      'synopsis)
+        #f)))
+
   (define checks
-    (list check-not-empty check-proper-start check-final-period
-          check-start-article check-start-with-package-name
-          check-synopsis-length))
+    (list check-not-empty
+          check-proper-start
+          check-final-period
+          check-start-article
+          check-start-with-package-name
+          check-synopsis-length
+          check-texinfo-markup))
 
   (match (package-synopsis package)
     ((? string? synopsis)
diff --git a/guix/ui.scm b/guix/ui.scm
index 3a0a650..345bf49 100644
--- a/guix/ui.scm
+++ b/guix/ui.scm
@@ -4,7 +4,7 @@
 ;;; Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
 ;;; Copyright © 2014 Cyril Roelandt <tipecaml@gmail.com>
 ;;; Copyright © 2014 Cyrill Schenkel <cyrill.schenkel@gmail.com>
-;;; Copyright © 2014, 2015 Alex Kost <alezost@gmail.com>
+;;; Copyright © 2014, 2015, 2017 Alex Kost <alezost@gmail.com>
 ;;; Copyright © 2015 David Thompson <davet@gnu.org>
 ;;; Copyright © 2015, 2016 Mathieu Lirzin <mthl@gnu.org>
 ;;; Copyright © 2016 Roel Janssen <roel@gnu.org>
@@ -81,6 +81,7 @@
             fill-paragraph
             texi->plain-text
             package-description-string
+            package-synopsis-string
             string->recutils
             package->recutils
             package-specification->name+version+output
@@ -848,10 +849,18 @@ converted to a space; sequences of more than one line break are preserved."
   (with-fluids ((%default-port-encoding "UTF-8"))
     (stexi->plain-text (texi-fragment->stexi str))))
 
+(define (package-field-string package field-accessor)
+  "Return a plain-text representation of PACKAGE field."
+  (and=> (field-accessor package)
+         (compose texi->plain-text P_)))
+
 (define (package-description-string package)
   "Return a plain-text representation of PACKAGE description field."
-  (and=> (package-description package)
-         (compose texi->plain-text P_)))
+  (package-field-string package package-description))
+
+(define (package-synopsis-string package)
+  "Return a plain-text representation of PACKAGE synopsis field."
+  (package-field-string package package-synopsis))
 
 (define (string->recutils str)
   "Return a version of STR where newlines have been replaced by newlines
@@ -914,7 +923,7 @@ WIDTH columns."
           (string-map (match-lambda
                        (#\newline #\space)
                        (chr       chr))
-                      (or (and=> (package-synopsis p) P_)
+                      (or (and=> (package-synopsis-string p) P_)
                           "")))
   (format port "~a~2%"
           (string->recutils
-- 
2.10.2

Re: Should synopsis handle texinfo markup?

[Ludovic Courtès]

Hi Alex,

Sorry for the delay.

Alex Kost <alezost@gmail.com> skribis:

> From 8d8a79d69619b68dd3a798e7456bfd871fcb8395 Mon Sep 17 00:00:00 2001
> From: Alex Kost <alezost@gmail.com>
> Date: Mon, 20 Mar 2017 13:41:41 +0300
> Subject: [PATCH] ui: Support Texinfo markup in package synopses.
>
> * guix/ui.scm (package-field-string): New procedure.
> (package-description-string): Use it.
> (package-synopsis-string): New procedure.
> (package->recutils): Use it.
> * guix/scripts/lint.scm (check-synopsis-style)[check-texinfo-markup]:
> New procedure.  Use it in checks.
> * gnu/packages/perl.scm (perl-try-tiny)[synopsis]: Adjust for the
> Texinfo markup.

Could you add a test in tests/lint.scm that would be the same as
"description: valid Texinfo markup" but for the synopsis?

Other than that it LGTM!

Thank you!

Ludo’.

Re: Should synopsis handle texinfo markup?

[Alex Kost]

Ludovic Courtès (2017-03-24 10:38 +0100) wrote:

> Hi Alex,
>
> Sorry for the delay.

No problem!  My delays are longer :-)

> Alex Kost <alezost@gmail.com> skribis:
>
>> From 8d8a79d69619b68dd3a798e7456bfd871fcb8395 Mon Sep 17 00:00:00 2001
>> From: Alex Kost <alezost@gmail.com>
>> Date: Mon, 20 Mar 2017 13:41:41 +0300
>> Subject: [PATCH] ui: Support Texinfo markup in package synopses.
>>
>> * guix/ui.scm (package-field-string): New procedure.
>> (package-description-string): Use it.
>> (package-synopsis-string): New procedure.
>> (package->recutils): Use it.
>> * guix/scripts/lint.scm (check-synopsis-style)[check-texinfo-markup]:
>> New procedure.  Use it in checks.
>> * gnu/packages/perl.scm (perl-try-tiny)[synopsis]: Adjust for the
>> Texinfo markup.
>
> Could you add a test in tests/lint.scm that would be the same as
> "description: valid Texinfo markup" but for the synopsis?

Sure, done.

> Other than that it LGTM!

Committed, thanks!

-- 
Alex