[GNU ELPA] New package: Urgrep

[GNU ELPA] New package: Urgrep

[Jim Porter]

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


I'd like to add a new package to GNU ELPA: Urgrep[1]. I posted about it 
a while ago[2], but wasn't quite ready to submit it to GNU ELPA at the 
time. Well, now is that time! I'll quote my original message for a 
summary of what it's interesting about Urgrep:

 > A brief summary: Urgrep is designed to provide a universal interface on
 > top of all "recursive grep"-like commands, from ripgrep to git grep to
 > the classic find+grep. I made it to solve a frustration I had with other
 > similar packages: they're primarily built to support a *particular*
 > searching tool, and while some can be coaxed into running with other
 > tools, it doesn't always work. Even when it does, it's usually not
 > seamless, especially when you add Tramp to the equation.
 >
 > With Urgrep, you can use *any* rgrep-like command. It will
 > automatically use the best tool on the system in question, so if some
 > remote host doesn't have your favorite tool, it'll still work just fine.
 >
 > I also added some Isearch-like bindings in the main function's prompt
 > (creatively named 'urgrep'). These all start with M-s and let you set
 > common search flags, like number of context lines. Maybe there's a
 > better way to do this; the current method seemed reasonable to me, but
 > I'm certainly open to suggestions.

[1] https://github.com/jimporter/urgrep
[2] https://lists.gnu.org/archive/html/emacs-devel/2022-09/msg00723.html

[-- Attachment #2: 0001-elpa-packages-urgrep-New-package.patch --]
[-- Type: text/plain, Size: 748 bytes --]

From 9745926ef47fe52f0c94287c992637e00e849b38 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Mon, 8 May 2023 22:07:56 -0700
Subject: [PATCH] * elpa-packages (urgrep): New package

---
 elpa-packages | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index 93f6ccc..93e6e46 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -696,6 +696,9 @@
  (uni-confusables 	:url nil
   :readme "README.md")
  (uniquify-files	:url nil)
+ (urgrep		:url "https://github.com/jimporter/urgrep"
+  :readme "README.md"
+  :ignored-files (".github" "LICENSE" "Makefile" "*-tests.el"))
  (url-http-ntlm 	:url nil)
  (url-http-oauth	:url "https://git.sr.ht/~fitzsim/url-http-oauth"
   :readme ignore)
-- 
2.25.1

Re: [GNU ELPA] New package: Urgrep

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> I'd like to add a new package to GNU ELPA: Urgrep[1]. I posted about
> it a while ago[2], but wasn't quite ready to submit it to GNU ELPA at
> the time. Well, now is that time! I'll quote my original message for a
> summary of what it's interesting about Urgrep:
>
>> A brief summary: Urgrep is designed to provide a universal interface on
>> top of all "recursive grep"-like commands, from ripgrep to git grep to
>> the classic find+grep. I made it to solve a frustration I had with other
>> similar packages: they're primarily built to support a *particular*
>> searching tool, and while some can be coaxed into running with other
>> tools, it doesn't always work. Even when it does, it's usually not
>> seamless, especially when you add Tramp to the equation.
>>
>> With Urgrep, you can use *any* rgrep-like command. It will
>> automatically use the best tool on the system in question, so if some
>> remote host doesn't have your favorite tool, it'll still work just fine.
>>
>> I also added some Isearch-like bindings in the main function's prompt
>> (creatively named 'urgrep'). These all start with M-s and let you set
>> common search flags, like number of context lines. Maybe there's a
>> better way to do this; the current method seemed reasonable to me, but
>> I'm certainly open to suggestions.

Looks interesting!

> [1] https://github.com/jimporter/urgrep
> [2] https://lists.gnu.org/archive/html/emacs-devel/2022-09/msg00723.html
>
> From 9745926ef47fe52f0c94287c992637e00e849b38 Mon Sep 17 00:00:00 2001
> From: Jim Porter <jporterbugs@gmail.com>
> Date: Mon, 8 May 2023 22:07:56 -0700
> Subject: [PATCH] * elpa-packages (urgrep): New package
>
> ---
>  elpa-packages | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/elpa-packages b/elpa-packages
> index 93f6ccc..93e6e46 100644
> --- a/elpa-packages
> +++ b/elpa-packages
> @@ -696,6 +696,9 @@
>   (uni-confusables 	:url nil
>    :readme "README.md")
>   (uniquify-files	:url nil)
> + (urgrep		:url "https://github.com/jimporter/urgrep"
> +  :readme "README.md"
> +  :ignored-files (".github" "LICENSE" "Makefile" "*-tests.el"))

Could you track these files in a .elpaignore file within the repository?

>   (url-http-ntlm 	:url nil)
>   (url-http-oauth	:url "https://git.sr.ht/~fitzsim/url-http-oauth"
>    :readme ignore)

Re: [GNU ELPA] New package: Urgrep

[Jim Porter]

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

On 5/9/2023 1:45 AM, Philip Kaludercic wrote:
> Could you track these files in a .elpaignore file within the repository?

Thanks, I didn't know about that file. Fixed in Urgrep, and here's the 
updated patch for GNU ELPA.

[-- Attachment #2: 0001-elpa-packages-urgrep-New-package.patch --]
[-- Type: text/plain, Size: 683 bytes --]

From 83b716918f55737783c2dfe699487f451e9a47f1 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Mon, 8 May 2023 22:07:56 -0700
Subject: [PATCH] * elpa-packages (urgrep): New package

---
 elpa-packages | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index 93f6ccc..c99708f 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -696,6 +696,8 @@
  (uni-confusables 	:url nil
   :readme "README.md")
  (uniquify-files	:url nil)
+ (urgrep		:url "https://github.com/jimporter/urgrep"
+  :readme "README.md")
  (url-http-ntlm 	:url nil)
  (url-http-oauth	:url "https://git.sr.ht/~fitzsim/url-http-oauth"
   :readme ignore)
-- 
2.25.1

Re: [GNU ELPA] New package: Urgrep

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> On 5/9/2023 1:45 AM, Philip Kaludercic wrote:
>> Could you track these files in a .elpaignore file within the repository?
>
> Thanks, I didn't know about that file. Fixed in Urgrep, and here's the
> updated patch for GNU ELPA.
>
> From 83b716918f55737783c2dfe699487f451e9a47f1 Mon Sep 17 00:00:00 2001
> From: Jim Porter <jporterbugs@gmail.com>
> Date: Mon, 8 May 2023 22:07:56 -0700
> Subject: [PATCH] * elpa-packages (urgrep): New package
>
> ---
>  elpa-packages | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/elpa-packages b/elpa-packages
> index 93f6ccc..c99708f 100644
> --- a/elpa-packages
> +++ b/elpa-packages
> @@ -696,6 +696,8 @@
>   (uni-confusables 	:url nil
>    :readme "README.md")
>   (uniquify-files	:url nil)
> + (urgrep		:url "https://github.com/jimporter/urgrep"
> +  :readme "README.md")

elpa-admin.el has a default list of README file names, that include
README.md.  I can fix that before applying the patch, since there
appears to be no opposition to adding the package.

>   (url-http-ntlm 	:url nil)
>   (url-http-oauth	:url "https://git.sr.ht/~fitzsim/url-http-oauth"
>    :readme ignore)

Re: [GNU ELPA] New package: Urgrep

[Jim Porter]

On 5/9/2023 11:22 PM, Philip Kaludercic wrote:
> elpa-admin.el has a default list of README file names, that include
> README.md.  I can fix that before applying the patch, since there
> appears to be no opposition to adding the package.

Thanks. I guess we should also update the ELPA README too then:

> By default we try to use README, README.rst, README.org, or the
> Commentary section in the main file.

Re: [GNU ELPA] New package: Urgrep

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> On 5/9/2023 11:22 PM, Philip Kaludercic wrote:
>> elpa-admin.el has a default list of README file names, that include
>> README.md.  I can fix that before applying the patch, since there
>> appears to be no opposition to adding the package.
>
> Thanks. I guess we should also update the ELPA README too then:

Nevermind, I was mistaken.  elpa-admin.el says

;; Most README.md files seem to be currently worse than the Commentary:
;; section :-( "README.md"

>> By default we try to use README, README.rst, README.org, or the
>> Commentary section in the main file.

Re: [GNU ELPA] New package: Urgrep

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > ;; Most README.md files seem to be currently worse than the Commentary:
  > ;; section :-( "README.md"

Could someone please explain what that text is supposed to mean?
I can't tell the intended meaning.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [GNU ELPA] New package: Urgrep

[Jim Porter]

On 5/12/2023 2:52 PM, Richard Stallman wrote:
>    > ;; Most README.md files seem to be currently worse than the Commentary:
>    > ;; section :-( "README.md"
> 
> Could someone please explain what that text is supposed to mean?
> I can't tell the intended meaning.

I think it just means that, for existing packages whose README file is 
"README.md", the Commentary section of the main PACKAGE.el file usually 
has more useful information. Therefore, ELPA chooses to ignore README.md 
by default and show the Commentary section instead for applicable packages.

Re: [GNU ELPA] New package: Urgrep

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> On 5/12/2023 2:52 PM, Richard Stallman wrote:
>>    > ;; Most README.md files seem to be currently worse than the Commentary:
>>    > ;; section :-( "README.md"
>> Could someone please explain what that text is supposed to mean?
>> I can't tell the intended meaning.
>
> I think it just means that, for existing packages whose README file is
> "README.md", the Commentary section of the main PACKAGE.el file
> usually has more useful information. Therefore, ELPA chooses to ignore
> README.md by default and show the Commentary section instead for
> applicable packages.

This is correct.

Re: [GNU ELPA] New package: Urgrep

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > >    > ;; Most README.md files seem to be currently worse than the Commentary:
  > >    > ;; section :-( "README.md"
  > > 
  > > Could someone please explain what that text is supposed to mean?
  > > I can't tell the intended meaning.

  > I think it just means that, for existing packages whose README file is 
  > "README.md", the Commentary section of the main PACKAGE.el file usually 
  > has more useful information. Therefore, ELPA chooses to ignore README.md 
  > by default and show the Commentary section instead for applicable packages.

That makes sense.  Can we replace these terse and cryptic words

  > ;; Most README.md files seem to be currently worse than the Commentary:
  > ;; section :-( "README.md"

with something clear like the text that you suggested above?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [GNU ELPA] New package: Urgrep

[Philip Kaludercic]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > >    > ;; Most README.md files seem to be currently worse than the Commentary:
>   > >    > ;; section :-( "README.md"
>   > > 
>   > > Could someone please explain what that text is supposed to mean?
>   > > I can't tell the intended meaning.
>
>   > I think it just means that, for existing packages whose README file is 
>   > "README.md", the Commentary section of the main PACKAGE.el file usually 
>   > has more useful information. Therefore, ELPA chooses to ignore README.md 
>   > by default and show the Commentary section instead for applicable packages.
>
> That makes sense.  Can we replace these terse and cryptic words
>
>   > ;; Most README.md files seem to be currently worse than the Commentary:
>   > ;; section :-( "README.md"
>
> with something clear like the text that you suggested above?

Since this is just an brief, internal comment in elpa-admin.el, I
wouldn't be that concerned.  I believe it is justified to assume that
everyone working on the script knows what this means.

Re: [GNU ELPA] New package: Urgrep

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Since this is just an brief, internal comment in elpa-admin.el, I
  > wouldn't be that concerned.  I believe it is justified to assume that
  > everyone working on the script knows what this means.

It is not unusual for people who don't kow the internals of a program
to read its code to learn to understand it.  So how about changing
those lines to make that learning easier?  Please give future
maintainers a break!

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [GNU ELPA] New package: Urgrep

[Philip Kaludercic]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Since this is just an brief, internal comment in elpa-admin.el, I
>   > wouldn't be that concerned.  I believe it is justified to assume that
>   > everyone working on the script knows what this means.
>
> It is not unusual for people who don't kow the internals of a program
> to read its code to learn to understand it.  So how about changing
> those lines to make that learning easier?  Please give future
> maintainers a break!

I started working on ELPA about two years ago, and comments like these
were never an issue.  Of course in this individual case it can be
changed, but generally speaking I would consider the ability to
understand what a comment like this means a pre-requisite for being able
to hack on a file like elpa-admin.el, as it "proves" familiarity with
Elisp packaging and conventions around Emacs packages.

Or perhaps I am misunderstanding you, what exactly do you find confusing
about comments like these in general? 

-- 
Philip Kaludercic

Re: [GNU ELPA] New package: Urgrep

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Or perhaps I am misunderstanding you, what exactly do you find confusing
  > about comments like these in general? 

I am speaking only about the one I quoted.
It is gratuitously terse, where one more line
could make it entirely clear.

Cryptic words that are not self-explanitory can make any aspect of a
system hard to understand.  It's worth an extra minute and an extra
line to say it clearly.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)