[elpa] chess.el: Req. for comment/review: Info manual

[elpa] chess.el: Req. for comment/review: Info manual

[Mario Lang]

Hi.

I have recently tried to get the chess.el info manual more
complete/useful.  This is my first texi document, and actually the first
time I am trying to document software beyond comments/docstrings and/or
readme's :-).  The basic skeleton of chess.info was created by John
Wiegley in 2002.  I have just added to it, and fixed some incorrect
stubs.  Still, as this is the first info manual I am working on, I'd be
very happy about a bit of external review of my work.  If you have
recently checked out chess.el, or have a love for texi, or both, please
have a look at the latest version in elpa.  I am really happy about any
kind of help here, be it style corrections (I am not a native speaker)
or even some ideas on how to explain things better/more complete.

If you have elpa commit access and find anything valuable, just go ahead
and commit it, I am totally fine with that.

Thanks for your help/time

-- 
CYa,
  ⡍⠁⠗⠊⠕

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Mario Lang <mlang@delysid.org>
> Date: Thu, 12 Jun 2014 21:23:38 +0200
> 
> I have recently tried to get the chess.el info manual more
> complete/useful.  This is my first texi document, and actually the first
> time I am trying to document software beyond comments/docstrings and/or
> readme's :-).  The basic skeleton of chess.info was created by John
> Wiegley in 2002.  I have just added to it, and fixed some incorrect
> stubs.  Still, as this is the first info manual I am working on, I'd be
> very happy about a bit of external review of my work.  If you have
> recently checked out chess.el, or have a love for texi, or both, please
> have a look at the latest version in elpa.  I am really happy about any
> kind of help here, be it style corrections (I am not a native speaker)
> or even some ideas on how to explain things better/more complete.
> 
> If you have elpa commit access and find anything valuable, just go ahead
> and commit it, I am totally fine with that.

Looks like you (or someone else) just deleted the package from elpa,
so it is no longer accessible.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Mario Lang]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Mario Lang <mlang@delysid.org>
>> Date: Thu, 12 Jun 2014 21:23:38 +0200
>> 
>> I have recently tried to get the chess.el info manual more
>> complete/useful.  This is my first texi document, and actually the first
>> time I am trying to document software beyond comments/docstrings and/or
>> readme's :-).  The basic skeleton of chess.info was created by John
>> Wiegley in 2002.  I have just added to it, and fixed some incorrect
>> stubs.  Still, as this is the first info manual I am working on, I'd be
>> very happy about a bit of external review of my work.  If you have
>> recently checked out chess.el, or have a love for texi, or both, please
>> have a look at the latest version in elpa.  I am really happy about any
>> kind of help here, be it style corrections (I am not a native speaker)
>> or even some ideas on how to explain things better/more complete.
>> 
>> If you have elpa commit access and find anything valuable, just go ahead
>> and commit it, I am totally fine with that.
>
> Looks like you (or someone else) just deleted the package from elpa,
> so it is no longer accessible.

Hmm, this must be some kind of bug. I didn't delete anything.  And the
externals/chess branch is still there, getting checked out if I do "make
externals" in a fresh clone.  But you are right of course, the package
has gone from the website. I am totally at a loss why this could have
happened.  If anyone has any hints, let me know.

-- 
CYa,
  ⡍⠁⠗⠊⠕

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Mario Lang]

[Nevermind my last reply, I was apparently confused.]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Mario Lang <mlang@delysid.org>
>> Date: Thu, 12 Jun 2014 21:23:38 +0200
>> 
>> I have recently tried to get the chess.el info manual more
>> complete/useful.  This is my first texi document, and actually the first
>> time I am trying to document software beyond comments/docstrings and/or
>> readme's :-).  The basic skeleton of chess.info was created by John
>> Wiegley in 2002.  I have just added to it, and fixed some incorrect
>> stubs.  Still, as this is the first info manual I am working on, I'd be
>> very happy about a bit of external review of my work.  If you have
>> recently checked out chess.el, or have a love for texi, or both, please
>> have a look at the latest version in elpa.  I am really happy about any
>> kind of help here, be it style corrections (I am not a native speaker)
>> or even some ideas on how to explain things better/more complete.
>> 
>> If you have elpa commit access and find anything valuable, just go ahead
>> and commit it, I am totally fine with that.
>
> Looks like you (or someone else) just deleted the package from elpa,
> so it is no longer accessible.

chess was originally checked in under packages/chess/ but later
"moved" to a separate branch.  You should get it in packages/chess/ if you run "make
externals" in the elpa top-level directory.

-- 
CYa,
  ⡍⠁⠗⠊⠕ | Debian Developer <URL:http://debian.org/>
  .''`. | Get my public key via finger mlang/key@db.debian.org
 : :' : | 1024D/7FC1A0854909BCCDBE6C102DDFFC022A6B113E44
 `. `'
   `-      <URL:http://delysid.org/>  <URL:http://www.staff.tugraz.at/mlang/>

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Mario Lang <mlang@delysid.org>
> Cc: emacs-devel@gnu.org
> Date: Sat, 14 Jun 2014 21:08:00 +0200
> 
> chess was originally checked in under packages/chess/ but later
> "moved" to a separate branch.

You never said anything about a separate branch.  There wasn't any way
I could know that.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> You never said anything about a separate branch.  There wasn't any way
> I could know that.

It's the way `elpa' is setup: some packages are kept in
separate branches.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Mario Lang <mlang@delysid.org>
> Date: Thu, 12 Jun 2014 21:23:38 +0200
> 
> I have recently tried to get the chess.el info manual more
> complete/useful.  This is my first texi document, and actually the first
> time I am trying to document software beyond comments/docstrings and/or
> readme's :-).  The basic skeleton of chess.info was created by John
> Wiegley in 2002.  I have just added to it, and fixed some incorrect
> stubs.  Still, as this is the first info manual I am working on, I'd be
> very happy about a bit of external review of my work.  If you have
> recently checked out chess.el, or have a love for texi, or both, please
> have a look at the latest version in elpa.  I am really happy about any
> kind of help here, be it style corrections (I am not a native speaker)
> or even some ideas on how to explain things better/more complete.
> 
> If you have elpa commit access and find anything valuable, just go ahead
> and commit it, I am totally fine with that.

I've reviewed the manual and have quite a few changes to it.

I'm not sure how to proceed with this: the package is maintained
outside of elpa, and I probably don't have write access there.  OTOH,
committing the changes to savannah doesn't sound right, since README
says that local changes to externals should be kept to a minimum.

Let me know whether to send the diffs to you.  Thanks.

Btw, your last change to README, viz.:

  -   git clone --reference .. --single-branch --branch externals/PACKAGE git://git.sv.gnu.org/srv/git/emacs/elpa PACKAGE
  +   git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE

is not necessarily for better: now this command and "make externals"
will do subtly different things, which not everyone will realize.  If
we want to be sure people with write access use the URL with write
access (and don't want to rely on them to know that and use the
correct URL), we should make changes to admin/archive-contents.el to
do that when all the externals are checked out.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> I'm not sure how to proceed with this: the package is maintained
> outside of elpa, and I probably don't have write access there.

AFAIK no, emacs-chess's upstream is now the "externals/chess" branch of
elpa on savannah.

> OTOH, committing the changes to savannah doesn't sound right, since
> README says that local changes to externals should be kept to
> a minimum.

We should always feel free to install corrections into `elpa'.  It's the
maintainer's responsability to then integrate them upstream (in case
there is another upstream).  Of course, if it's not just a plain
correction, you might like to get the maintainer's agreement first.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Mario Lang <mlang@delysid.org>,  emacs-devel@gnu.org
> Date: Wed, 18 Jun 2014 14:09:02 -0400
> 
> > I'm not sure how to proceed with this: the package is maintained
> > outside of elpa, and I probably don't have write access there.
> 
> AFAIK no, emacs-chess's upstream is now the "externals/chess" branch of
> elpa on savannah.

Then why does its entry in externals-list says

   ("chess"    :external "https://github.com/jwiegley/emacs-chess.git")

?  What does that URL mean?  The README text definitely makes a strong
impression that's the upstream:

  ** External branches

  Some packages are maintained in external branches.  These should be
  appropriately listed in the `externals-list' file.
  There are two different cases: subtrees and externals.

  In both cases, a copy of the code is kept in the `elpa' repository and
  should be sync'd with the upstream every once in a while.  This copy may
  include local changes, tho ideally these should be kept to a minimum.

If the upstream is in elpa, then what "upstream" and what "copy" are
alluded to here, and why does the text talk about syncing and local
changes?

> We should always feel free to install corrections into `elpa'.  It's the
> maintainer's responsability to then integrate them upstream (in case
> there is another upstream).  Of course, if it's not just a plain
> correction, you might like to get the maintainer's agreement first.

I don't know what is plain correction and what isn't.  What I
corrected are errors in Texinfo usage, typos, and a few cases of
unclear wording.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> Then why does its entry in externals-list says
>    ("chess"    :external "https://github.com/jwiegley/emacs-chess.git")

Because https://github.com/jwiegley/emacs-chess.git was the upstream.
It should probably be removed now, tho it's up to Mario.

>> We should always feel free to install corrections into `elpa'.  It's the
>> maintainer's responsability to then integrate them upstream (in case
>> there is another upstream).  Of course, if it's not just a plain
>> correction, you might like to get the maintainer's agreement first.
> I don't know what is plain correction and what isn't.

Nobody does.  You'll just have to make an educated guess as to whether
there's a chance the maintainer might object.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: mlang@delysid.org,  emacs-devel@gnu.org
> Date: Wed, 18 Jun 2014 14:55:26 -0400
> 
> > Then why does its entry in externals-list says
> >    ("chess"    :external "https://github.com/jwiegley/emacs-chess.git")
> 
> Because https://github.com/jwiegley/emacs-chess.git was the upstream.
> It should probably be removed now, tho it's up to Mario.

Yes, please remove it, and then it should probably be moved back to
trunk, because it no longer fits the other packages in externals in
this respect.

> >> We should always feel free to install corrections into `elpa'.  It's the
> >> maintainer's responsability to then integrate them upstream (in case
> >> there is another upstream).  Of course, if it's not just a plain
> >> correction, you might like to get the maintainer's agreement first.
> > I don't know what is plain correction and what isn't.
> 
> Nobody does.  You'll just have to make an educated guess as to whether
> there's a chance the maintainer might object.

In this case, the maintainer actually asked for this.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> Yes, please remove it, and then it should probably be moved back to
> trunk,

No, the externals-vs-subtree choice has no relationship to whether the
package has some upstream version somewhere else.  It's just a technical
detail of how the files are stored.

Largish packages are better off in a separate "external" branch.

> because it no longer fits the other packages in externals in
> this respect.

You mean like w3?  rudel?  dismal?
auctex and ergoemacs-mode are the only two "external" packages which
have some other upstream.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: mlang@delysid.org,  emacs-devel@gnu.org
> Date: Wed, 18 Jun 2014 16:29:09 -0400
> 
> Largish packages are better off in a separate "external" branch.

Why?  The disadvantage is clear: it's more complicated to work with a
package that is on a branch.  What are the advantages?

> > because it no longer fits the other packages in externals in
> > this respect.
> 
> You mean like w3?  rudel?  dismal?
> auctex and ergoemacs-mode are the only two "external" packages which
> have some other upstream.

Then README needs some real rework.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Mario Lang]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Mario Lang <mlang@delysid.org>
>> Date: Thu, 12 Jun 2014 21:23:38 +0200
>> 
>> I have recently tried to get the chess.el info manual more
>> complete/useful.  This is my first texi document, and actually the first
>> time I am trying to document software beyond comments/docstrings and/or
>> readme's :-).  The basic skeleton of chess.info was created by John
>> Wiegley in 2002.  I have just added to it, and fixed some incorrect
>> stubs.  Still, as this is the first info manual I am working on, I'd be
>> very happy about a bit of external review of my work.  If you have
>> recently checked out chess.el, or have a love for texi, or both, please
>> have a look at the latest version in elpa.  I am really happy about any
>> kind of help here, be it style corrections (I am not a native speaker)
>> or even some ideas on how to explain things better/more complete.
>> 
>> If you have elpa commit access and find anything valuable, just go ahead
>> and commit it, I am totally fine with that.
>
> I've reviewed the manual and have quite a few changes to it.

Thank you!!!

> I'm not sure how to proceed with this: the package is maintained
> outside of elpa,

That is sort of a misunderstanding.  chess.el is maintained as part of
ELPA since beginning of June.  I originally just wanted to commit it
(which is what I initially did) to the master branch in packages/chess/,
but Stefan convinced me to keep it in a separate branch
(externals/chess) to preserve the history.  So while it is under
"externals/", it is really a native ELPA package these days.  The github
repo is basically dead, since the original author has no interest in
working on it anymore.  To make this short, no, chess.el is part of
ELPA, and you are free to commit to its branch directly, it is really
the main repository these days.

> and I probably don't have write access there.

You have.

> OTOH, committing the changes to savannah doesn't sound right, since
> README says that local changes to externals should be kept to a
> minimum.

This info is contrary to what Stefan made me do, so just ignore it, in
the case of chess.el. (To clarify, it was really for the better to
actually preserve VCS history.)

> Let me know whether to send the diffs to you.  Thanks.
>
> Btw, your last change to README, viz.:
>
>   -   git clone --reference .. --single-branch --branch externals/PACKAGE git://git.sv.gnu.org/srv/git/emacs/elpa PACKAGE
>   +   git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE
>
> is not necessarily for better: now this command and "make externals"
> will do subtly different things, which not everyone will realize.  If
> we want to be sure people with write access use the URL with write
> access (and don't want to rely on them to know that and use the
> correct URL), we should make changes to admin/archive-contents.el to
> do that when all the externals are checked out.

Hmm, I changed just README since I tripped over this behaviour when
using make externals.  I originally wanted to change the code run by
make externals as well, but I was a bit too much chicken regarding me
being new on ELPA :-).  Feel free to revert the one-liner in README if
you think it is too confusing.  Or I will do that, if you feel strongly
about it.

-- 
CYa,
  ⡍⠁⠗⠊⠕

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Mario Lang <mlang@delysid.org>
> Date: Wed, 18 Jun 2014 20:20:14 +0200
> 
> >   -   git clone --reference .. --single-branch --branch externals/PACKAGE git://git.sv.gnu.org/srv/git/emacs/elpa PACKAGE
> >   +   git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE
> >
> > is not necessarily for better: now this command and "make externals"
> > will do subtly different things, which not everyone will realize.  If
> > we want to be sure people with write access use the URL with write
> > access (and don't want to rely on them to know that and use the
> > correct URL), we should make changes to admin/archive-contents.el to
> > do that when all the externals are checked out.
> 
> Hmm, I changed just README since I tripped over this behaviour when
> using make externals.  I originally wanted to change the code run by
> make externals as well, but I was a bit too much chicken regarding me
> being new on ELPA :-).  Feel free to revert the one-liner in README if
> you think it is too confusing.  Or I will do that, if you feel strongly
> about it.

I'll let Stefan and Glenn do TRT, I no longer feel I understand what
is going on with elpa and the externals.  Why on earth did it have to
be so complicated?  Why did I need to read the Lisp source to figure
out how to checkout a single package from externals?

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> Why did I need to read the Lisp source to figure out how to checkout
> a single package from externals?

I wouldn't know.  I made it as simple as I could, because I don't have
much time to devote to it and nobody else seemed interested in spending
time on it, whereas I think GNU ELPA is very important for Emacs.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Mario Lang <mlang@delysid.org>,  emacs-devel@gnu.org
> Date: Wed, 18 Jun 2014 14:58:53 -0400
> 
> > Why did I need to read the Lisp source to figure out how to checkout
> > a single package from externals?
> 
> I wouldn't know.  I made it as simple as I could, because I don't have
> much time to devote to it and nobody else seemed interested in spending
> time on it, whereas I think GNU ELPA is very important for Emacs.

Thank you, but having a way to checkout _all_ of the external packages
without a way to do that only for one or a few is a limitation.
Besides, you assume that someone can run "make" in the same session
where she runs git and Emacs, which is entirely non-trivial on
Windows.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> Thank you, but having a way to checkout _all_ of the external packages
> without a way to do that only for one or a few is a limitation.
> Besides, you assume that someone can run "make" in the same session
> where she runs git and Emacs, which is entirely non-trivial on
> Windows.

I have no access, no experience, no desire of access nor desire of
experience on Windows.  So until someone else invests time on this
front, it might suck, indeed.

This said, running "git" and "make" inside a cygwin shell should work OK.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: mlang@delysid.org,  emacs-devel@gnu.org
> Date: Wed, 18 Jun 2014 16:36:50 -0400
> 
> > Thank you, but having a way to checkout _all_ of the external packages
> > without a way to do that only for one or a few is a limitation.
> > Besides, you assume that someone can run "make" in the same session
> > where she runs git and Emacs, which is entirely non-trivial on
> > Windows.
> 
> I have no access, no experience, no desire of access nor desire of
> experience on Windows.

You never know where life will take you.

> So until someone else invests time on this front, it might suck,
> indeed.

I just did, and wrote that in README.

The point is that having just a Make rule for something like checking
out a subtree is not the best way of exposing the knowledge to users.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[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. ]]]

    > I have no access, no experience, no desire of access nor desire of
    > experience on Windows.

    You never know where life will take you.

Some of us choose free software on principle; life might do various
things to us, but can't make us Windows users.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> Date: Thu, 19 Jun 2014 11:18:16 -0400
> From: Richard Stallman <rms@gnu.org>
> CC: monnier@iro.umontreal.ca, mlang@delysid.org, emacs-devel@gnu.org
> 
>     > I have no access, no experience, no desire of access nor desire of
>     > experience on Windows.
> 
>     You never know where life will take you.
> 
> Some of us choose free software on principle; life might do various
> things to us, but can't make us Windows users.

Yes, it can.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Mario Lang]

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

>> Why did I need to read the Lisp source to figure out how to checkout
>> a single package from externals?
>
> I wouldn't know.  I made it as simple as I could, because I don't have
> much time to devote to it and nobody else seemed interested in spending
> time on it, whereas I think GNU ELPA is very important for Emacs.

I am actually rather motivated to work on ELPA, but I am too green to do
any infrastructure changes just yet.

THat said, what might be confusing is the "externals/" prefix, since it
suggests that the package is really externally maintained.  As it
stands, we seem to use separate branches for packages to keep history
apart, which is a valid enough reason with big packages methinks.  We
*could* clear up that confusion by using another branch prefix, like
"packages/" to indicate that these are really packages native to the ELPA repo.

I also find the instructions to generate archives locally which include
externals a bit too verbose.  I'd rather prefer to have a make target
that does all the work, so that it becomes more easy to test-build a
package living in a separate branch locally.

-- 
CYa,
  ⡍⠁⠗⠊⠕

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Stefan Monnier]

> That said, what might be confusing is the "externals/" prefix, since it

Indeed.

> I also find the instructions to generate archives locally which include
> externals a bit too verbose.

My assumption on this front is that very few people will want to
generate their own archives.

> I'd rather prefer to have a make target that does all the work,

Personally, I use just "make", indeed, and that mode of use is the one
I expect to be The Normal Way.


        Stefan

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Glenn Morris]

Eli Zaretskii wrote:

>> Hmm, I changed just README since I tripped over this behaviour when
>> using make externals.  I originally wanted to change the code run by
>> make externals as well, but I was a bit too much chicken regarding me
>> being new on ELPA :-).  Feel free to revert the one-liner in README if
>> you think it is too confusing.  Or I will do that, if you feel strongly
>> about it.
>
> I'll let Stefan and Glenn do TRT

Just for the record, I've put zero work into elpa (just lack of time),
and have no special knowledge of or authority over it. I imagine I know
less about it than you do.

Re: [elpa] chess.el: Req. for comment/review: Info manual

[Eli Zaretskii]

> From: Mario Lang <mlang@delysid.org>
> Date: Wed, 18 Jun 2014 20:20:14 +0200
> 
> > I've reviewed the manual and have quite a few changes to it.
> 
> Thank you!!!
> 
> > I'm not sure how to proceed with this: the package is maintained
> > outside of elpa,
> 
> That is sort of a misunderstanding.  chess.el is maintained as part of
> ELPA since beginning of June.  I originally just wanted to commit it
> (which is what I initially did) to the master branch in packages/chess/,
> but Stefan convinced me to keep it in a separate branch
> (externals/chess) to preserve the history.  So while it is under
> "externals/", it is really a native ELPA package these days.  The github
> repo is basically dead, since the original author has no interest in
> working on it anymore.  To make this short, no, chess.el is part of
> ELPA, and you are free to commit to its branch directly, it is really
> the main repository these days.
> 
> > and I probably don't have write access there.
> 
> You have.

OK, I committed the changes.  Let me know if you need me to explain
some of what I changed.