packaging - sentences in description

packaging - sentences in description

[Giovanni Biscuolo]

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

Hi Guix

I'm packaging go-github-com-burntsushi-locker, this is the package
definition:

--8<---------------cut here---------------start------------->8---
(define-public go-github-com-burntsushi-locker
  (let ((commit "a6e239ea1c69bff1cfdb20c4b73dadf52f784b6a")
        (revision "0"))
    (package
      (name "go-github-com-burntsushi-locker")
      (version (git-version "0.0.0" revision commit))
      (source
       (origin
         (method git-fetch)
         (uri (git-reference
               (url "https://github.com/BurntSushi/locker")
               (commit commit)))
         (file-name (git-file-name name version))
         (sha256
          (base32
           "1xak4aync4klswq5217qvw191asgla51jr42y94vp109lirm5dzg"))))
      (build-system go-build-system)
      (arguments
       '(#:import-path "github.com/BurntSushi/locker"))
      (home-page "https://github.com/BurntSushi/locker")
      (synopsis "Manage named ReadWrite mutexes in Go")
      (description "Golang package for conveniently using named read/write
locks. These appear to be especially useful for synchronizing access to
session based information in web applications. 
  
The common use case is to use the package level functions, which use a package
level set of locks (safe to use from multiple goroutines
simultaneously). However, you may also create a new separate set of locks
test. 
  
All locks are implemented with read-write mutexes. To use them like a regular
mutex, simply ignore the RLock/RUnlock functions.")
      (license license:public-domain))))
--8<---------------cut here---------------end--------------->8---

it builds but when I check its description I get [1]:

--8<---------------cut here---------------start------------->8---
giovanni@anemone: time ./pre-inst-env guix lint -c description go-github-com-burntsushi-locker
gnu/packages/golang.scm:3202:19: go-github-com-burntsushi-locker@0.0.0-0.a6e239e: sentences in description should be followed by two spaces; possible infractions at 60, 329, 447

Some deprecated features have been used.  Set the environment
variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
program to get more information.  Set it to "no" to suppress
this message.

real	4m24.644s
user	5m24.480s
sys	0m1.420s
--8<---------------cut here---------------end--------------->8---

I copy/pasted and adapted the description from the project homepage,
I'm using emacs and auto-fill mode on so it should have followed the
rules in .dir-locals.el 

I can't understand where the sentences in my description lacks the two
required spaces: any hint please?

Thanks!
Gio

[1] it takes more than five minutes just for the description: I will
diligently do it for all my packages :-)... but it's a little bit
discouraging :-S

[2] https://www.gnu.org/software/guix/manual/en/html_node/Synopses-and-Descriptions.html#Synopses-and-Descriptions

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: packaging - sentences in description

[Julien Lepiller]

Le 2019-03-18 15:34, Giovanni Biscuolo a écrit :
> Hi Guix
> 
> I'm packaging go-github-com-burntsushi-locker, this is the package
> definition:
> 
> [...]
> 
>       (home-page "https://github.com/BurntSushi/locker")
>       (synopsis "Manage named ReadWrite mutexes in Go")
>       (description "Golang package for conveniently using named 
> read/write
> locks. These appear to be especially useful for synchronizing access to
         ^ here
> session based information in web applications.
> 
> The common use case is to use the package level functions, which use a 
> package
> level set of locks (safe to use from multiple goroutines
> simultaneously). However, you may also create a new separate set of 
> locks
                   ^ here
> test.
> 
> All locks are implemented with read-write mutexes. To use them like a 
> regular
                                                     ^ and here
> mutex, simply ignore the RLock/RUnlock functions.")
>       (license license:public-domain))))
> 

I think that's all.

HTH :)

Re: packaging - sentences in description

[Tobias Geerinckx-Rice]

Giovanni Biscuolo wrote:
>       (description "Golang package for conveniently using named 
>       read/write
> locks. These appear to be especially useful for synchronizing 
> access to
> session based information in web applications. 
>   
> The common use case is to use the package level functions, which 
> use a package
> level set of locks (safe to use from multiple goroutines
> simultaneously). However, you may also create a new separate set 
> of locks
> test. 
>   
> All locks are implemented with read-write mutexes. To use them 
> like a regular
> mutex, simply ignore the RLock/RUnlock functions.")
>       (license license:public-domain))))
> --8<---------------cut 
> here---------------end--------------->8---
>
> it builds but when I check its description I get [1]:
>
> --8<---------------cut 
> here---------------start------------->8---
> giovanni@anemone: time ./pre-inst-env guix lint -c description 
> go-github-com-burntsushi-locker
> gnu/packages/golang.scm:3202:19: 
> go-github-com-burntsushi-locker@0.0.0-0.a6e239e: sentences in 
> description should be followed by two spaces; possible 
> infractions at 60, 329, 447

[…]

> --8<---------------cut 
> here---------------end--------------->8---
>
> I copy/pasted and adapted the description from the project 
> homepage,
> I'm using emacs and auto-fill mode on so it should have followed 
> the
> rules in .dir-locals.el

These rules are for formatting Scheme code, they won't touch the 
insides of strings.

(Which isn't to say there isn't some M-x double-my-spaces 
somewhere that I don't know of…)

> I can't understand where the sentences in my description lacks 
> the two
> required spaces: any hint please?

Everywhere? :-p

  Instead. Of. Like. This.
          ^   ^     ^
  We.  Write.  Like.  This.
     ^^      ^^     ^^

> [1] it takes more than five minutes just for the description: I 
> will
> diligently do it for all my packages :-)... but it's a little 
> bit
> discouraging :-S

I can sympathise, but it's not that much work compared to writing 
code, and about as important.

There will always be people who have never even heard of your 
package, and there's nothing more frustrating than reading a 1( or 
10)-line description and not learning a thing.

Kind regards,

T G-R

Re: packaging - sentences in description

[Giovanni Biscuolo]

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

Thanks Tobias,

and also to you, Julien!

now mi package lints like a charm!

Tobias Geerinckx-Rice <me@tobias.gr> writes:

[...]

>> I copy/pasted and adapted the description from the project 
>> homepage,
>> I'm using emacs and auto-fill mode on so it should have followed 
>> the
>> rules in .dir-locals.el
>
> These rules are for formatting Scheme code, they won't touch the 
> insides of strings.

they help to auto-fill strings also, but don't help with (my lack of
knowledge about) proper sentences handling

I live in emacs but was still not aware (among too much other things) of
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sentences.html#Sentences

IMHO we need to add this info in
https://www.gnu.org/software/guix/manual/en/html_node/Synopses-and-Descriptions.html#Synopses-and-Descriptions
(valid for non-emacs users also)

I can send a patch if agreed :-)

[...]

>> I can't understand where the sentences in my description lacks 
>> the two required spaces: any hint please?
>
> Everywhere? :-p

eh :-)

[...]

>> [1] it takes more than five minutes just for the description: I 
>> will
>> diligently do it for all my packages :-)... but it's a little 
>> bit
>> discouraging :-S
>
> I can sympathise, but it's not that much work compared to writing 
> code, and about as important.

for sure! I'll meditate meanwhile :-D

[...]

Thanks!
Gio

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]