[NonGNU ELPA] New packages: elquery, file-ring, metamorph

[NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Adam]

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

Hello!

I have a few packages which might be a good fit for NonGNU ELPA

elquery is an HTML parsing (using emacs' libxml), formatting, and 
querying library, which is useful for scraping. It contains a 
querySelector implementation, and lots of helper functions for 
retrieving/setting data on parsed nodes.

file-ring lets you switch between files which have the same basename 
with a keypress, which I've found useful when writing c and angular code 
(.c/.h and .component.ts/.component.html)

metamorph is effectively a Turing-complete `replace-regexp`, which I've 
found useful when I need to add some number to twenty constants in a big 
header file.

Feedback is welcome and appreciated - thanks in advance!

Thanks,
-Adam

- elquery: https://github.com/AdamNiederer/elquery
- file-ring: https://github.com/AdamNiederer/file-ring
- metamorph: https://github.com/AdamNiederer/metamorph

[-- Attachment #2: 0001-elpa-packages-elquery-New-package.patch --]
[-- Type: text/x-patch, Size: 794 bytes --]

From 91467dad5ec59a22143ed8a8bdb323e71f18953c Mon Sep 17 00:00:00 2001
From: Adam Niederer <adam.niederer@gmail.com>
Date: Sun, 27 Mar 2022 23:29:03 -0400
Subject: [PATCH 1/3] * elpa-packages (elquery): New package

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

diff --git a/elpa-packages b/elpa-packages
index c008f8c6af..0b28139f9c 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -114,6 +114,10 @@
   :doc "elpher.texi"
   :ignored-files ("Makefile" "ISSUES.org" "RELEASE" "config.mk"))
 
+ ("elquery" :url "https://github.com/AdamNiederer/elquery.git"
+  :readme "README.org"
+  :ignored-files ("Cask" "test" ".github"))
+
  ("evil"		:url "https://github.com/emacs-evil/evil"
   :ignored-files ("COPYING" "lib" "scripts")
   :doc "doc/build/texinfo/evil.texi")
-- 
2.35.1


[-- Attachment #3: 0002-elpa-packages-file-ring-New-package.patch --]
[-- Type: text/x-patch, Size: 785 bytes --]

From 3256efb11041b554f6c97e9795735a4c426a8cdb Mon Sep 17 00:00:00 2001
From: Adam Niederer <adam.niederer@gmail.com>
Date: Sun, 27 Mar 2022 23:29:09 -0400
Subject: [PATCH 2/3] * elpa-packages (file-ring): New package

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

diff --git a/elpa-packages b/elpa-packages
index 0b28139f9c..3ade09ca8d 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -161,6 +161,10 @@
  ("evil-visualstar"     :url "https://github.com/bling/evil-visualstar.git"
   :readme ("README.md"))
 
+ ("file-ring" :url "https://github.com/AdamNiederer/file-ring.git"
+  :readme "README.org"
+  :ignored-files ("Cask" "test" ".github"))
+
  ("flymake-kondor"	:url "https://github.com/turbo-cafe/flymake-kondor"
   :ignored-files ("COPYING.txt"))
 
-- 
2.35.1


[-- Attachment #4: 0003-elpa-packages-metamorph-New-package.patch --]
[-- Type: text/x-patch, Size: 821 bytes --]

From 3be70f2971f309f985796d14899e6393c0fa81d3 Mon Sep 17 00:00:00 2001
From: Adam Niederer <adam.niederer@gmail.com>
Date: Sun, 27 Mar 2022 23:29:16 -0400
Subject: [PATCH 3/3] * elpa-packages (metamorph): New package

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

diff --git a/elpa-packages b/elpa-packages
index 3ade09ca8d..a3480d3f2b 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -360,6 +360,10 @@
   :ignored-files ("COPYING" "Makefile" "test-rtorrent.py" "test"
                   "doc/scgi-protocol.txt" "doc/screenshot.png"))
 
+ ("metamorph" :url "https://github.com/AdamNiederer/metamorph.git"
+  :readme "README.org"
+  :ignored-files ("Cask" "test" ".github"))
+
  ("moe-theme"           :url "https://github.com/kuanyui/moe-theme.el.git"
   :ignored-files ("pics" "LICENSE"))
 
-- 
2.35.1

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Visuwesh]

[ஞாயிறு மார்ச் 27, 2022] Adam wrote:

> Hello!
>
> I have a few packages which might be a good fit for NonGNU ELPA
>
> elquery is an HTML parsing (using emacs' libxml), formatting, and
> querying library, which is useful for scraping. It contains a
> querySelector implementation, and lots of helper functions for
> retrieving/setting data on parsed nodes.
>
> file-ring lets you switch between files which have the same basename
> with a keypress, which I've found useful when writing c and angular
> code (.c/.h and .component.ts/.component.html)
>
> metamorph is effectively a Turing-complete `replace-regexp`, which
> I've found useful when I need to add some number to twenty constants
> in a big header file.

The README file for metamorph suggests that you are reimplementing
query-replace-regexp's \,:

    In interactive calls, the replacement text can contain ‘\,’
    followed by a Lisp expression.  Each
    replacement evaluates that expression to compute the replacement
    string.  Inside of that expression, ‘\&’ is a string denoting the
    whole match as a string, ‘\N’ for a partial match, ‘\#&’ and ‘\#N’
    for the whole or a partial match converted to a number with
    ‘string-to-number’, and ‘\#’ itself for the number of replacements
    done so far (starting with zero).

Or am I missing something?

>
> Feedback is welcome and appreciated - thanks in advance!
>
> Thanks,
> -Adam
>
> - elquery: https://github.com/AdamNiederer/elquery
> - file-ring: https://github.com/AdamNiederer/file-ring
> - metamorph: https://github.com/AdamNiederer/metamorph

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[T.V Raman]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=gb18030, Size: 518 bytes --]

Took a look at elquery since I'm generally interested in anything that
can help me get useful data out of HTML soup.

A couple of thoughts:

1. elquery could do with a function that allows one to specify a URL to
   work on, rather than the two read-file and read-string that it
   currently provides --- so elquery-read-from-url

2. A few usage examples would make it easier to start with the package.

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
7©4 Id: kg:/m/0285kf1  •0Ü8

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Adam]

> The README file for metamorph suggests that you are reimplementing
> query-replace-regexp's \,:
> 
>      [...]
> 
> Or am I missing something?

Nope, I didn't know query-replace-regexp could do that. metamorph offers 
previews while you type and does it all in one shot, but that probably 
doesn't warrant a whole separate package. Thanks for taking a look at it!

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Ergus]

On Mon, Mar 28, 2022 at 06:09:23PM -0400, Adam wrote:
>>The README file for metamorph suggests that you are reimplementing
>>query-replace-regexp's \,:
>>
>>     [...]
>>
>>Or am I missing something?
>
>Nope, I didn't know query-replace-regexp could do that. metamorph 
>offers previews while you type and does it all in one shot, but that 
>probably doesn't warrant a whole separate package. Thanks for taking a 
>look at it!
>
IMHO the best would be to add previews to query-replace-regexp. I asked
about that on emacs help some days ago and Juri said that there is
already come WIP...

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[T.V Raman]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=gb18030, Size: 1182 bytes --]


Sadly putting the examples in README is not very helpful since
installing your package from melpa doesn't appear to bring down the
README; one shouldn't need to click through to Github to find out how to
use it if one has installed the package.

Also, a README that says "it's like JQuery but far less useful" is
likely to chase away any users --- yes I understand the need for
humility and to not over-promise but this is perhaps going a bit to far
--- why not try to at least have the goal of making it as useful as
JQuery? Alternatively just write an elisp wrapper that calls JQuery:-)


"T.V Raman" <raman@google.com> writes:

> Took a look at elquery since I'm generally interested in anything that
> can help me get useful data out of HTML soup.
>
> A couple of thoughts:
>
> 1. elquery could do with a function that allows one to specify a URL to
>    work on, rather than the two read-file and read-string that it
>    currently provides --- so elquery-read-from-url
>
> 2. A few usage examples would make it easier to start with the package.

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
7©4 Id: kg:/m/0285kf1  •0Ü8

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Karl Fogel]

On 28 Mar 2022, T.V Raman wrote:
>Sadly putting the examples in README is not very helpful since
>installing your package from melpa doesn't appear to bring down 
>the
>README; one shouldn't need to click through to Github to find out 
>how to
>use it if one has installed the package.

Hunh.  Would that be something we should make a general fix for? 
E.g., when a package 'foo' gets installed from melpa or from some 
similar package repository, and it has a README, then the README 
gets installed alongside the package as 'foo-README', or something 
like that?

Authors are going to keep putting useful information into README 
files, since that's become such a standard place.  We might as 
well make it easy for users to receive that information when they 
receive the package.

Thoughts?

(Feel free to start a new thread for this, if you think the idea 
might go somewhere.)

Best regards,
-Karl

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Adam]

On 3/28/22 23:43, Karl Fogel wrote:
> On 28 Mar 2022, T.V Raman wrote:
>> Sadly putting the examples in README is not very helpful since
>> installing your package from melpa doesn't appear to bring down the
>> README; one shouldn't need to click through to Github to find out how to
>> use it if one has installed the package.
> 
> Hunh.  Would that be something we should make a general fix for? E.g., 
> when a package 'foo' gets installed from melpa or from some similar 
> package repository, and it has a README, then the README gets installed 
> alongside the package as 'foo-README', or something like that?

I think that's a good way of going about it. From a cursory glance it 
looks like the most popular out-of-tree libraries (s, f, a, ht, epl, 
async, ov, popup, uuidgen) have most of their usage examples and 
documentation in the README.

Even if NonGNU's supposed to be a bit more curated, having everybody 
synchronize their README with docstrings or texi manuals might be a bit 
wasteful. I don't know if there's a way to do that automatically.

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Stefan Monnier]

> Sadly putting the examples in README is not very helpful since
> installing your package from melpa doesn't appear to bring down the
> README; one shouldn't need to click through to Github to find out how to
> use it if one has installed the package.

A better fix is to make it easy for Emacs to show the README (assuming
it's included in the tarball).  I think we've discussed this in the past
and there had been some progress, but there's probably more to do.

> Also, a README that says "it's like JQuery but far less useful" is
> likely to chase away any users --- yes I understand the need for
> humility and to not over-promise but this is perhaps going a bit to far
> --- why not try to at least have the goal of making it as useful as
> JQuery? Alternatively just write an elisp wrapper that calls JQuery:-)

More importantly, it should also be understandable by someone who
doesn't know what is JQuery.


        Stefan

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[T.V Raman]

If it just landed as README in the package dir, it would be
progress.:-)
Karl Fogel writes:
 > On 28 Mar 2022, T.V Raman wrote:
 > >Sadly putting the examples in README is not very helpful since
 > >installing your package from melpa doesn't appear to bring down 
 > >the
 > >README; one shouldn't need to click through to Github to find out 
 > >how to
 > >use it if one has installed the package.
 > 
 > Hunh.  Would that be something we should make a general fix for? 
 > E.g., when a package 'foo' gets installed from melpa or from some 
 > similar package repository, and it has a README, then the README 
 > gets installed alongside the package as 'foo-README', or something 
 > like that?
 > 
 > Authors are going to keep putting useful information into README 
 > files, since that's become such a standard place.  We might as 
 > well make it easy for users to receive that information when they 
 > receive the package.
 > 
 > Thoughts?
 > 
 > (Feel free to start a new thread for this, if you think the idea 
 > might go somewhere.)
 > 
 > Best regards,
 > -Karl

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

--

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[T.V Raman]

The better solution would be for the package to come with a short info
file -- see packages like  embark. Then the info file just shows up
when you hit  info.
Adam writes:
 > On 3/28/22 23:43, Karl Fogel wrote:
 > > On 28 Mar 2022, T.V Raman wrote:
 > >> Sadly putting the examples in README is not very helpful since
 > >> installing your package from melpa doesn't appear to bring down the
 > >> README; one shouldn't need to click through to Github to find out how to
 > >> use it if one has installed the package.
 > > 
 > > Hunh.  Would that be something we should make a general fix for? E.g., 
 > > when a package 'foo' gets installed from melpa or from some similar 
 > > package repository, and it has a README, then the README gets installed 
 > > alongside the package as 'foo-README', or something like that?
 > 
 > I think that's a good way of going about it. From a cursory glance it 
 > looks like the most popular out-of-tree libraries (s, f, a, ht, epl, 
 > async, ov, popup, uuidgen) have most of their usage examples and 
 > documentation in the README.
 > 
 > Even if NonGNU's supposed to be a bit more curated, having everybody 
 > synchronize their README with docstrings or texi manuals might be a bit 
 > wasteful. I don't know if there's a way to do that automatically.

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

--

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Stephen Leake]

Karl Fogel <kfogel@red-bean.com> writes:

> On 28 Mar 2022, T.V Raman wrote:
>>Sadly putting the examples in README is not very helpful since
>> installing your package from melpa doesn't appear to bring down the
>> README; one shouldn't need to click through to Github to find out
>> how to
>>use it if one has installed the package.
>
> Hunh.  Would that be something we should make a general fix for? E.g.,
> when a package 'foo' gets installed from melpa or from some similar
> package repository, and it has a README, then the README gets
> installed alongside the package as 'foo-README', or something like
> that?

That used to happen, but one directory up; the readme for ada-mode was
in ~/.emacs.d/elpa, next to ada-mode-<version>.

However, that readme was often out of date.

To access the readme now, use ? in the *Packages* buffer. That uses the
installed package files if it is installed.

The description that ? displays is either from a README file, or from
the Commentary header of the main package file; so the ada-mode readme
is in ~/.emacs.d/elpa/ada-mode-7.1.8/README. Is that not the case
for elquery?

-- 
-- Stephe

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Adam]

I've devised a way to create an info file from my README with a bit of 
clever formatting and pandoc, which should solve the issue of 
documentation not being shipped to the user.

Perhaps the build process could convert the README to an info file if no 
texi files exist in the repository?

-Adam

On 3/29/22 09:51, T.V Raman wrote:
> 
> The better solution would be for the package to come with a short info
> file -- see packages like  embark. Then the info file just shows up
> when you hit  info.
> Adam writes:
>   > On 3/28/22 23:43, Karl Fogel wrote:
>   > > On 28 Mar 2022, T.V Raman wrote:
>   > >> Sadly putting the examples in README is not very helpful since
>   > >> installing your package from melpa doesn't appear to bring down the
>   > >> README; one shouldn't need to click through to Github to find out how to
>   > >> use it if one has installed the package.
>   > >
>   > > Hunh.  Would that be something we should make a general fix for? E.g.,
>   > > when a package 'foo' gets installed from melpa or from some similar
>   > > package repository, and it has a README, then the README gets installed
>   > > alongside the package as 'foo-README', or something like that?
>   >
>   > I think that's a good way of going about it. From a cursory glance it
>   > looks like the most popular out-of-tree libraries (s, f, a, ht, epl,
>   > async, ov, popup, uuidgen) have most of their usage examples and
>   > documentation in the README.
>   >
>   > Even if NonGNU's supposed to be a bit more curated, having everybody
>   > synchronize their README with docstrings or texi manuals might be a bit
>   > wasteful. I don't know if there's a way to do that automatically.
> 

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Stefan Monnier]

> I've devised a way to create an info file from my README with a bit of
> clever formatting and pandoc, which should solve the issue of documentation
> not being shipped to the user.

AFAIK the users *should* already be able to see the
README if they use a recent enough Emacs.

IOW if that doesn't work, please file a bug report.

> Perhaps the build process could convert the README to an info file if no
> texi files exist in the repository?

The README and the doc are meant to be two different things.
The README is supposed to be a short presentation of what the package does.

Of course, you can use a `README.org` and use that same file for `:readme`
and for `:doc` but that will lead to the same doc being duplicated.


        Stefan

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Adam]

On 3/31/22 08:48, Stefan Monnier wrote:
> AFAIK the users *should* already be able to see the
> README if they use a recent enough Emacs.
> 
> IOW if that doesn't work, please file a bug report.
Is this something that is exclusive to ELPA? I am able to view READMEs 
of certain ELPA packages, but no packages from MELPA (including elquery) 
have READMEs available locally, on 29.0.50.

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Augusto Stoffel]

On Tue, 29 Mar 2022 at 01:10, Ergus <spacibba@aol.com> wrote:

> On Mon, Mar 28, 2022 at 06:09:23PM -0400, Adam wrote:
>>>The README file for metamorph suggests that you are reimplementing
>>>query-replace-regexp's \,:
>>>
>>>     [...]
>>>
>>>Or am I missing something?
>>
>> Nope, I didn't know query-replace-regexp could do that. metamorph
>> offers previews while you type and does it all in one shot, but that
>> probably doesn't warrant a whole separate package. Thanks for taking
>> a look at it!
>>
> IMHO the best would be to add previews to query-replace-regexp. I asked
> about that on emacs help some days ago and Juri said that there is
> already come WIP...

The changes Juri referred to are discussed in bug#53126, but they are
concerned only with lazy highlight and lazy count.

I am not (or at least not yet) working on a preview of the replacement
text.  Feel free to give this a try.

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Stefan Monnier]

Adam [2022-03-31 23:28:15] wrote:
> On 3/31/22 08:48, Stefan Monnier wrote:
>> AFAIK the users *should* already be able to see the
>> README if they use a recent enough Emacs.
>> IOW if that doesn't work, please file a bug report.
> Is this something that is exclusive to ELPA?

No.

> I am able to view READMEs of certain ELPA packages, but no packages
> from MELPA (including elquery) have READMEs available locally, on
> 29.0.50.

To view the README, it has to be included in the tarball, so it will
depend on the MELPA recipe.


        Stefan

Re: [NonGNU ELPA] New packages: elquery, file-ring, metamorph

[Stephen Leake]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Adam [2022-03-31 23:28:15] wrote:
>> On 3/31/22 08:48, Stefan Monnier wrote:
>>> AFAIK the users *should* already be able to see the
>>> README if they use a recent enough Emacs.
>>> IOW if that doesn't work, please file a bug report.
>> Is this something that is exclusive to ELPA?
>
> No.
>
>> I am able to view READMEs of certain ELPA packages, but no packages
>> from MELPA (including elquery) have READMEs available locally, on
>> 29.0.50.
>
> To view the README, it has to be included in the tarball, so it will
> depend on the MELPA recipe.

Currently, package-menu-describe-package (bound to '?' in *Packages*)
assumes that the README is available locally if the package is
installed. That could be relaxed; it could fetch it from the repository
if not found locally.

-- 
-- Stephe