Emacs pretest 24.0.95

Emacs pretest 24.0.95

[Chong Yidong]

Emacs pretest 24.0.95 is now available for download via FTP, at the
following location:

 ftp://alpha.gnu.org/gnu/emacs/pretest/emacs-24.0.95.tar.gz

This is the sixth pretest for what will become Emacs 24.1.
See etc/NEWS for a list of changes since Emacs 23.4.

Please send me an email reporting success or failure on your build
platform.  Please report any bugs that you come across via
M-x report-emacs-bugs, or email bug-gnu-emacs@gnu.org.
For questions, email emacs-devel@gnu.org.

Thank you for helping to test Emacs.

Release branch plans

[Chong Yidong]

Now that the 24.0.95 pretest is out, we plan to cut the 24.1 branch
soon.  After that is done, fixes that should go into 24.1 should be
committed into the branch, then merged into the trunk.

I'll email emacs-devel with more details shortly before the branch is
cut.  First, I'd like feedback on a couple of items:

1. I'd like to remove the +++ and --- lines from NEWS before the branch
   is cut, to avoid a messy merge later.  Could someone help look
   through NEWS and double-check if there are any entries that still
   aren't tagged with +++ or ---, and need documentation?

   The entries for pcase.el, secrets.el, notifications.el, and
   soap-client.el, but OTOH these don't need documentation in the
   manuals (i.e. they are ---).  One other issue is that I think
   `delayed-warnings-list' and `delayed-warnings-hook' ought to be
   documented; I'll take a closer look at this tomorrow.

   Also, if you come across any instances of poor ordering of the NEWS
   entries, please feel free to re-order them directly (I've already
   done a couple of re-orderings but may have missed something).

2. Any opinions on what to name the release branch?  If we go by the old
   naming convention, it would be EMACS_24_1_RC, but that's kind of
   ugly; maybe we should name it "emacs-24.1-rc" instead.

Re: Release branch plans

[Glenn Morris]

Chong Yidong wrote:

> 1. I'd like to remove the +++ and --- lines from NEWS before the branch
>    is cut, to avoid a messy merge later.  Could someone help look
>    through NEWS and double-check if there are any entries that still
>    aren't tagged with +++ or ---, and need documentation?
>
>    The entries for pcase.el, secrets.el, notifications.el, and
>    soap-client.el, but OTOH these don't need documentation in the
>    manuals (i.e. they are ---). 

I thought it might be nice if the lispref mentioned pcase, but don't
have the first clue about it.

The other ones on my list of maybe-not-done were:

shell-mode uses pcomplete rules...
comint and modes derived from it...
gnutls

And things in doc/misc:

d-bus changes
erc-coding-system-precedence
gnus.texi and message.texi need updating for pgg being obsoleted by EasyPG

Re: Release branch plans

[Michael Albinus]

Chong Yidong <cyd@gnu.org> writes:

>    The entries for pcase.el, secrets.el, notifications.el, and
>    soap-client.el, but OTOH these don't need documentation in the
>    manuals (i.e. they are ---).  One other issue is that I think
>    `delayed-warnings-list' and `delayed-warnings-hook' ought to be
>    documented; I'll take a closer look at this tomorrow.

For secrets.el, I've promised long long ago to contribute to
auth.texi. Ted has added the node "Secret Service API" in that manual, I
will try to write the missing text next days.

notifications.el is documented by the docstring of its major command
`notifications-notify'. However, it might be helpful to add also some
doc to the Elisp manual, especially examples. Which chapter would be the
best? "System Interface"? If nobody else takes the ball, I'll try to
contribute.

For soap-client.el, there exist
<http://code.google.com/p/emacs-soap-client/wiki/QuickStart>. I don't
know whether Alex or (somebody else) could write a manual based on this
in time. But I agree, it is not mandatory for Emacs 24.1.

Best regards, Michael.

PS: I'm not a native English speaker, all contributions from me require
proof-reading.

Re: Release branch plans

[Michael Albinus]

Glenn Morris <rgm@gnu.org> writes:

> And things in doc/misc:
>
> d-bus changes

I'll check that.

Best regards, Michael.

Re: Release branch plans

[Chong Yidong]

Michael Albinus <michael.albinus@gmx.de> writes:

> notifications.el is documented by the docstring of its major command
> `notifications-notify'. However, it might be helpful to add also some
> doc to the Elisp manual, especially examples. Which chapter would be
> the best? "System Interface"? If nobody else takes the ball, I'll try
> to contribute.

Yes, System Interface is the right place, either before or after the
Session Management node.

> PS: I'm not a native English speaker, all contributions from me require
> proof-reading.

Please go ahead and make your changes, and we can clean it up afterward.

Re: Release branch plans

[Andreas Schwab]

Chong Yidong <cyd@gnu.org> writes:

>    ugly; maybe we should name it "emacs-24.1-rc" instead.

I'd rather suggest "emacs-24.1-branch" or "emacs-24-branch", depending
how it is supposed to be used after the release.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Stefan Monnier]

> 2. Any opinions on what to name the release branch?  If we go by the old
>    naming convention, it would be EMACS_24_1_RC, but that's kind of
>    ugly; maybe we should name it "emacs-24.1-rc" instead.

We have `emacs-23' already, so the next one should simply be `emacs-24'
or `emacs-24.1'.


        Stefan

Re: Release branch plans

[Chong Yidong]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Chong Yidong <cyd@gnu.org> writes:
>
>>    ugly; maybe we should name it "emacs-24.1-rc" instead.
>
> I'd rather suggest "emacs-24.1-branch" or "emacs-24-branch", depending
> how it is supposed to be used after the release.

The plan is for 24.2 to be made from the trunk; the branch will be used
for 24.1 only.  The name "emacs-24.1-branch" sounds OK.

Re: Release branch plans

[Andreas Schwab]

While you are at it please also change the tag name to be less shouting.
IMHO we can even drop the pretest word from it.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Eli Zaretskii]

> From: Chong Yidong <cyd@gnu.org>
> Date: Mon, 02 Apr 2012 13:38:51 +0800
> 
> Now that the 24.0.95 pretest is out, we plan to cut the 24.1 branch
> soon.  After that is done, fixes that should go into 24.1 should be
> committed into the branch, then merged into the trunk.

Could we _please_ do it the other way around this time?  That is,
commit to the trunk and merge to the branch?  Merging from the branch
makes it hard to find out where some changes came from and why,
because history metadata says some revisions were merged, but their
code was not really brought to the target branch.  If one of the
branches has to sustain such damage, let it be other than the main
branch, if only because the life of the release branches is much
shorter; after some time no one looks at them anymore.

Please?...

Re: Release branch plans

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> Could we _please_ do it the other way around this time?  That is,
> commit to the trunk and merge to the branch?

How can that be correct?  Most of the trunk commits are not supposed to
occur on the release branch.

> Merging from the branch makes it hard to find out where some changes
> came from and why, because history metadata says some revisions were
> merged, but their code was not really brought to the target branch.

Merges are supposed to merge everything.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: Chong Yidong <cyd@gnu.org>,  emacs-devel@gnu.org
> Date: Mon, 02 Apr 2012 19:21:55 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Could we _please_ do it the other way around this time?  That is,
> > commit to the trunk and merge to the branch?
> 
> How can that be correct?  Most of the trunk commits are not supposed to
> occur on the release branch.

As long as not all branch commits are merged to the trunk, we already
know how to cope with this problem.

> > Merging from the branch makes it hard to find out where some changes
> > came from and why, because history metadata says some revisions were
> > merged, but their code was not really brought to the target branch.
> 
> Merges are supposed to merge everything.

Yes, except they don't.

Re: Release branch plans

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andreas Schwab <schwab@linux-m68k.org>
>> Cc: Chong Yidong <cyd@gnu.org>,  emacs-devel@gnu.org
>> Date: Mon, 02 Apr 2012 19:21:55 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > Could we _please_ do it the other way around this time?  That is,
>> > commit to the trunk and merge to the branch?
>> 
>> How can that be correct?  Most of the trunk commits are not supposed to
>> occur on the release branch.
>
> As long as not all branch commits are merged to the trunk, we already
> know how to cope with this problem.

Merging always merges the complete history.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Date: Mon, 02 Apr 2012 20:43:40 +0200
> Cc: cyd@gnu.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Andreas Schwab <schwab@linux-m68k.org>
> >> Cc: Chong Yidong <cyd@gnu.org>,  emacs-devel@gnu.org
> >> Date: Mon, 02 Apr 2012 19:21:55 +0200
> >> 
> >> Eli Zaretskii <eliz@gnu.org> writes:
> >> 
> >> > Could we _please_ do it the other way around this time?  That is,
> >> > commit to the trunk and merge to the branch?
> >> 
> >> How can that be correct?  Most of the trunk commits are not supposed to
> >> occur on the release branch.
> >
> > As long as not all branch commits are merged to the trunk, we already
> > know how to cope with this problem.
> 
> Merging always merges the complete history.

Yes.

Re: Emacs pretest 24.0.95

[Glenn Morris]

Chong Yidong wrote:

> Emacs pretest 24.0.95 is now available for download via FTP, at the

Lookes like you tagged it as "EMACS_PRETEST_24_0_05" rather than
"EMACS_PRETEST_24_0_95". `bzr help tag' suggests that is fixable:

  To rename a tag (change the name but keep it on the same revsion), run
  ``bzr tag new-name -r tag:old-name`` and then ``bzr tag --delete oldname``.

Re: Release branch plans

[Stefan Monnier]

>> Merges are supposed to merge everything.
> Yes, except they don't.

They do, although sometimes only conceptually.


        Stefan

Re: Emacs pretest 24.0.95

[Glenn Morris]

>   To rename a tag (change the name but keep it on the same revsion), run
>   ``bzr tag new-name -r tag:old-name`` and then ``bzr tag --delete oldname``.

I added the EMACS_PRETEST_24_0_95 tag, and deleted the old one, but
the deletion will not propagate to existing checkouts
(https://bugs.launchpad.net/bzr/+bug/138802). Doesn't really matter AFAICS.

Tags in Emacs repository [was Re: Emacs pretest 24.0.95]

[Glenn Morris]

BTW, there are ~ 1150 tags in the Emacs repository. 931 of those are
"libc-[digits]". Many of these are duplicates; eg there are over 100
libc- tags for r19861 (the vital commit "typos"). All are over 13 years
old. Does anyone expect to ever want to use those again; or even know
what they are for?

Re: Tags in Emacs repository

[Glenn Morris]

Meh, bzr tags are essentially not deletable at all, so this is even more
irrelevant than it first seemed.

Re: Tags in Emacs repository [was Re: Emacs pretest 24.0.95]

[Andreas Schwab]

Glenn Morris <rgm@gnu.org> writes:

> or even know what they are for?

They are inherited from the old times when the RCS files were shared
between different projects.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Glenn Morris]

I hope replies with more than one sentence are allowed...

If I can try to summarize:

The current way things work is:

There is a trunk and a release branch.

Ideally, changes appropriate to the release get made on the release
branch and then merged to the trunk. This is fine.

Sometimes, a change is made on the trunk, and then it is realized
after that fact that it needs to be on the release branch too. So it
gets committed there by hand, with a label "do not merge to trunk", or
"backport from trunk". This is less fine, because when the branch gets
merged to the trunk, you have to merge every commit (essentially), even
the ones that came from the trunk originally. So the same commit "shows
up twice" on the trunk. This is a minor annoyance (IMO).

The new proposal is presumably to commit everything on the trunk, and
label those things that need to also go to the release branch in some
way (eg "merge to emacs-24 branch"). Then use bzrmerge.el to merge from
trunk to branch, skipping everything not so labelled. This would work.
It would be slightly more effort because trunk will see more commits
than the release branch, so there are more revision to "skip" when
merging.

The log of the release branch would be essentially useless (IMO). Every
single commit would be "merge from trunk", with very few of the merged
commits having actually been applied. This is the opposite of the
current situation, where most of the merge commits are actually
applicable (it's just the backports that are not).

So I think it would be worse than the current situation.


IIRC, at this point, some wacky (IMO) three branch proposal usually
comes up...

Re: Tags in Emacs repository

[Glenn Morris]

Andreas Schwab wrote:

> They are inherited from the old times when the RCS files were shared
> between different projects.

Wow. Sounds like the kind of thing that should have been posted April 1. ;)

Actually, it seems that using `bzr tag --delete' in a bound branch
_does_ delete tags from the upstream repo. At least, in a fresh checkout
of the Emacs trunk, the EMACS_PRETEST_24_0_05 tag is no longer present.
It's just that it does not propagate to existing checkouts.

So it would be possible to get rid of all those "libc" etc tags.
Would anyone object to that?

Re: Release branch plans

[Juanma Barranquero]

On Tue, Apr 3, 2012 at 00:20, Glenn Morris <rgm@gnu.org> wrote:

> The new proposal is presumably to commit everything on the trunk, and
> label those things that need to also go to the release branch in some
> way (eg "merge to emacs-24 branch"). [...]
> The log of the release branch would be essentially useless (IMO). Every
> single commit would be "merge from trunk", with very few of the merged
> commits having actually been applied.

There are commits that are only intended for trunk, and others that
are only intended for the release branch (the poster case being a bug
that it is fixed in a conservative way in the release branch and in a
more invasive, and hopefully better or more generic, way in the
trunk), so it's not really true that every single commit would be a
merge from trunk, though many (most?) would.

> So I think it would be worse than the current situation.

In absolute terms, you're right. But Eli's argument is, I think, that
the state of the trunk is more important. Having a worse trunk's
history in exchange of a cleaner release branch's history is a net
loss because we do, on the long term, orders of magnitude more work
with the trunk that the release branch. Particularly "historical
research" to determine when/how/why/by-whom an old change was done.

    Juanma

Re: Release branch plans

[Andreas Schwab]

Glenn Morris <rgm@gnu.org> writes:

> The new proposal is presumably to commit everything on the trunk, and
> label those things that need to also go to the release branch in some
> way (eg "merge to emacs-24 branch"). Then use bzrmerge.el to merge from
> trunk to branch, skipping everything not so labelled. This would work.

That wouldn't be merges any more, but a series of cherry-picks.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Andreas Schwab]

Juanma Barranquero <lekktu@gmail.com> writes:

> In absolute terms, you're right. But Eli's argument is, I think, that
> the state of the trunk is more important. Having a worse trunk's
> history in exchange of a cleaner release branch's history is a net
> loss because we do, on the long term, orders of magnitude more work
> with the trunk that the release branch. Particularly "historical
> research" to determine when/how/why/by-whom an old change was done.

For this purpose a proper merge is far superior to a cherry-pick.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Juanma Barranquero]

On Tue, Apr 3, 2012 at 00:54, Andreas Schwab <schwab@linux-m68k.org> wrote:

> For this purpose a proper merge is far superior to a cherry-pick.

If done in the branch, that's almost irrelevant. Much less
history-digging is done in branches.

    Juanma

Re: Release branch plans

[Glenn Morris]

Andreas Schwab wrote:

> Glenn Morris <rgm@gnu.org> writes:
>
>> The new proposal is presumably to commit everything on the trunk, and
>> label those things that need to also go to the release branch in some
>> way (eg "merge to emacs-24 branch"). Then use bzrmerge.el to merge from
>> trunk to branch, skipping everything not so labelled. This would work.
>
> That wouldn't be merges any more, but a series of cherry-picks.

Not as I envisage it; or (tried to) describe it.

If we could do what you seem to be saying, then we could just do that
when merging from release branch to trunk, and the issue that started
this discussion would not arise in the first place.

But we can't, because bzr does not track cherry-picked revisions.
(IIUC, etc, etc).

Re: Release branch plans

[Glenn Morris]

Glenn Morris wrote:

>>> way (eg "merge to emacs-24 branch"). Then use bzrmerge.el to merge from
>>> trunk to branch, skipping everything not so labelled. This would work.
>>
>> That wouldn't be merges any more, but a series of cherry-picks.
>
> Not as I envisage it; or (tried to) describe it.

PS If you are not familiar with bzrmerge.el, the whole point is that it
does a real merge, then does some tricks to get an effect akin to
cherry-picking.

Maybe the idea was to merge from trunk to release-branch some other way,
but I don't know what way that would be.

Re: Release branch plans

[Andreas Schwab]

Glenn Morris <rgm@gnu.org> writes:

> PS If you are not familiar with bzrmerge.el, the whole point is that it
> does a real merge, then does some tricks to get an effect akin to
> cherry-picking.

That's not cherry-picking, it adds additional changes as part of the
merge.  This is an evil merge.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Release branch plans

[Chong Yidong]

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

> We have `emacs-23' already, so the next one should simply be
> `emacs-24' or `emacs-24.1'.

Just to clarify (after a quick off-list discussion with Stefan): his
first suggestion here refers to using `emacs-24' for the 24.1 release
branch now, and when the time comes to open the trunk for Emacs 25
development (post 24.2), copying the contents of the trunk into the
emacs-24 branch.

That is to say, from now to 24.1 release, use emacs-24 for the release
branch; after 24.1 release, 24.2 development takes place on trunk;
shortly before 24.2 release, copy trunk into emacs-24 branch, and open
trunk for Emacs 25 development.

I guess this makes sense in a "make only as many Savannah branches as we
need" way, but I don't know enough about usual bzr practices to know if
it's TRT.  Would the "copy everything over" step munge the history on
the emacs-24 branch?  Or is that not an issue?

Re: Release branch plans

[Stefan Monnier]

> PS If you are not familiar with bzrmerge.el, the whole point is that it
> does a real merge, then does some tricks to get an effect akin to
> cherry-picking.

Actually, that's not the way I see it: bzrmerge does a plain full
complete merge.  The only difference with "bzr merge" is that it helps
you avoid spurious conflicts for changes which you know would be
resolved by taking the trunk version (because the trunk's code is
already ahead of the release branch's code).

E.g. it tries to avoid the conflicts due to a change like "increase
revision from 24.0.95 to 24.0.96" when the trunk it already at
"24.1.50", or when the trunk already has the same bugfix installed
(e.g. with the exact same code, or maybe with a different less
conservative change).

It is not designed for cherry picking.


        Stefan

Re: Release branch plans

[Michael Albinus]

Michael Albinus <michael.albinus@gmx.de> writes:

> Glenn Morris <rgm@gnu.org> writes:
>
>> And things in doc/misc:
>>
>> d-bus changes
>
> I'll check that.

I've made a diff between the trunk and the emacs-23 branch. Major
visible changes are documented.

etc/NEWS adapted with a doc flag.

Best regards, Michael.

Re: Release branch plans

[Michael Albinus]

Chong Yidong <cyd@gnu.org> writes:

> Michael Albinus <michael.albinus@gmx.de> writes:
>
>> notifications.el is documented by the docstring of its major command
>> `notifications-notify'. However, it might be helpful to add also some
>> doc to the Elisp manual, especially examples. Which chapter would be
>> the best? "System Interface"? If nobody else takes the ball, I'll try
>> to contribute.
>
> Yes, System Interface is the right place, either before or after the
> Session Management node.

Done.

Best regards, Michael.

Re: Release branch plans

[Stefan Monnier]

> Would the "copy everything over" step munge the history on
> the emacs-24 branch?

If the trunk has merged everything from the emacs-24 branch (which will
be the case), then the "copy over" can be done with a plain normal
"push", i.e. without losing any history.

It might/will switch around some revisions from "on the main line" to
"on a branch" in the history of `emacs-24', so the `push' will need
append_revisions_only=False, but that's about it.


        Stefan

Re: Tags in Emacs repository

[Stefan Monnier]

> So it would be possible to get rid of all those "libc" etc tags.
> Would anyone object to that?

Not sure about the "etc", but the libc ones, yes no problem.


        Stefan

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Tue, 03 Apr 2012 09:50:47 -0400
> Cc: emacs-devel@gnu.org
> 
> > Would the "copy everything over" step munge the history on
> > the emacs-24 branch?
> 
> If the trunk has merged everything from the emacs-24 branch (which will
> be the case), then the "copy over" can be done with a plain normal
> "push", i.e. without losing any history.

The history will be insanely messy after that anyway, so I wouldn't
bother.  Just "bzr pull --overwrite" and commit.  If the trunk will be
copied into emacs-24, then the history of trunk at that point really
_becomes_ the history of emacs-24.

Re: Release branch plans

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  cyd@gnu.org,  emacs-devel@gnu.org
> Date: Tue, 03 Apr 2012 12:00:34 +0200
> 
> Glenn Morris <rgm@gnu.org> writes:
> 
> > PS If you are not familiar with bzrmerge.el, the whole point is that it
> > does a real merge, then does some tricks to get an effect akin to
> > cherry-picking.
> 
> That's not cherry-picking, it adds additional changes as part of the
> merge.  This is an evil merge.

I agree.  That's what prompted my plea.  I would even consider not
merging at all, neither from trunk to the branch nor the other way
around.  If the number of common revisions is small, cherry-picking is
a lesser evil, and we still get help from the VCS (i.e., no need to do
the same changes twice).

Better ideas are welcome.

Re: Release branch plans

[Stefan Monnier]

>> > PS If you are not familiar with bzrmerge.el, the whole point is that it
>> > does a real merge, then does some tricks to get an effect akin to
>> > cherry-picking.
>> That's not cherry-picking, it adds additional changes as part of the
>> merge.  This is an evil merge.
> I agree.

I have no idea what you guys are talking about.


        Stefan

Re: Tags in Emacs repository

[Glenn Morris]

Stefan Monnier wrote:

>> So it would be possible to get rid of all those "libc" etc tags.
>> Would anyone object to that?
>
> Not sure about the "etc", but the libc ones, yes no problem.

My definition of "etc" is now in admin/notes/tags.

Re: Tags in Emacs repository

[Glenn Morris]

Nooo, all the tags I removed seem to have come back again... :(

Re: Tags in Emacs repository

[Glenn Morris]

I guess this is because other people still have those tags in their
copies, and every time they commit an update, all the tags are
unavoidably pushed as well. So the bzr tag --delete command really is
almost totally pointless. Oh well, that was a waste of time.

Re: Release branch plans

[Michael Albinus]

Michael Albinus <michael.albinus@gmx.de> writes:

> Chong Yidong <cyd@gnu.org> writes:
>
>>    The entries for pcase.el, secrets.el, notifications.el, and
>>    soap-client.el, but OTOH these don't need documentation in the
>>    manuals (i.e. they are ---).  One other issue is that I think
>>    `delayed-warnings-list' and `delayed-warnings-hook' ought to be
>>    documented; I'll take a closer look at this tomorrow.
>
> For secrets.el, I've promised long long ago to contribute to
> auth.texi. Ted has added the node "Secret Service API" in that manual, I
> will try to write the missing text next days.

Done.

Best regards, Michael.

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Tue, 03 Apr 2012 09:45:55 -0400
> Cc: Eli Zaretskii <eliz@gnu.org>, cyd@gnu.org,
> 	Andreas Schwab <schwab@linux-m68k.org>, emacs-devel@gnu.org
> 
> It is not designed for cherry picking.

Why do you need to design anything for cherry-picking?  Cherry-picking
picks up individual revisions and merges them, so what kind of
automated support would be needed?  I think none.

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: Andreas Schwab <schwab@linux-m68k.org>, cyd@gnu.org, emacs-devel@gnu.org
> Date: Tue, 03 Apr 2012 15:13:50 -0400
> 
> >> > PS If you are not familiar with bzrmerge.el, the whole point is that it
> >> > does a real merge, then does some tricks to get an effect akin to
> >> > cherry-picking.
> >> That's not cherry-picking, it adds additional changes as part of the
> >> merge.  This is an evil merge.
> > I agree.
> 
> I have no idea what you guys are talking about.

Yes, you do, at least what _I_ am talking about.  I explained this at
least twice in the past: the history is all messed up on the trunk as
result of this.  You disagree with this being a problem, but I submit
that this is akin to saying that the history is not important.

Maybe we should take a step back and ask ourselves why do we need to
merge from the stable branch to the trunk at all?  Sure, it's a
natural thing to do, but the way we do it, IMO the cure is so bad that
we should be talking about the disease more than we do.

Re: Release branch plans

[Stefan Monnier]

> Yes, you do, at least what _I_ am talking about.  I explained this at
> least twice in the past: the history is all messed up on the trunk as
> result of this.

No, it's not messed up.  Maybe you don't like it (not sure why), and
maybe `bzr log' shows it in a weird or messed up way (in which case you
should take it up with the bzr guys), but the history itself is very
much not messed up at all.

> You disagree with this being a problem, but I submit
> that this is akin to saying that the history is not important.

I care a lot about the VCS history metadata, which is why I insist that
we merge from the release branch onto the trunk.

> Maybe we should take a step back and ask ourselves why do we need to
> merge from the stable branch to the trunk at all?

Very simple: we want to make sure all the bug-fixes we install on the
stable branch don't get lost on the next release, and we want to reflect
this info into the VCS history so the VCS knows what's going on.


        Stefan

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: schwab@linux-m68k.org,  cyd@gnu.org,  emacs-devel@gnu.org
> Date: Wed, 04 Apr 2012 13:41:59 -0400
> 
> > Yes, you do, at least what _I_ am talking about.  I explained this at
> > least twice in the past: the history is all messed up on the trunk as
> > result of this.
> 
> No, it's not messed up.  Maybe you don't like it (not sure why), and
> maybe `bzr log' shows it in a weird or messed up way (in which case you
> should take it up with the bzr guys), but the history itself is very
> much not messed up at all.

If it shows to humans as messed up, then for all practical purposes it
_is_ messed up.  History is not an abstract feature, it is only
important because it is useful to humans who use such bzr commands as
"log", "diff", "annotate", etc.  (Well, it is also useful to bzr for
merging, but since the branch and the trunk diverge anyway, and will
never converge, this part is not too important in this case.)

> > You disagree with this being a problem, but I submit
> > that this is akin to saying that the history is not important.
> 
> I care a lot about the VCS history metadata, which is why I insist that
> we merge from the release branch onto the trunk.

If you care about history, you should care first and foremost about
how it is presented through the bzr commands that explore it.
Otherwise, the history is all but useless.

> > Maybe we should take a step back and ask ourselves why do we need to
> > merge from the stable branch to the trunk at all?
> 
> Very simple: we want to make sure all the bug-fixes we install on the
> stable branch don't get lost on the next release, and we want to reflect
> this info into the VCS history so the VCS knows what's going on.

What do you mean by "don't get lost"?  Installing them on the trunk
separately, or through cherry-picking, will get them to trunk all the
same, no?

Re: Release branch plans

[Stefan Monnier]

>> > Yes, you do, at least what _I_ am talking about.  I explained this at
>> > least twice in the past: the history is all messed up on the trunk as
>> > result of this.
>> No, it's not messed up.  Maybe you don't like it (not sure why), and
>> maybe `bzr log' shows it in a weird or messed up way (in which case you
>> should take it up with the bzr guys), but the history itself is very
>> much not messed up at all.
> If it shows to humans as messed up, then for all practical purposes it
> _is_ messed up.

No: history is something that gets recorded "for eternity", whereas its
rendition in human form is done on the fly and can be fixed by
subsequent releases (or by the use of other tools, options, ...).
Hence history is of utmost importance, whereas its rendition is secondary.

>> > Maybe we should take a step back and ask ourselves why do we need to
>> > merge from the stable branch to the trunk at all?
>> Very simple: we want to make sure all the bug-fixes we install on the
>> stable branch don't get lost on the next release, and we want to reflect
>> this info into the VCS history so the VCS knows what's going on.
> What do you mean by "don't get lost"?  Installing them on the trunk
> separately, or through cherry-picking, will get them to trunk all the
> same, no?

But that depends on not forgetting to install it on both sides, which is
error prone and is more work than installing only once on the release
branch and merging later since merging can be batched and largely automated.


        Stefan

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: schwab@linux-m68k.org,  cyd@gnu.org,  emacs-devel@gnu.org
> Date: Wed, 04 Apr 2012 18:01:59 -0400
> 
> >> > Yes, you do, at least what _I_ am talking about.  I explained this at
> >> > least twice in the past: the history is all messed up on the trunk as
> >> > result of this.
> >> No, it's not messed up.  Maybe you don't like it (not sure why), and
> >> maybe `bzr log' shows it in a weird or messed up way (in which case you
> >> should take it up with the bzr guys), but the history itself is very
> >> much not messed up at all.
> > If it shows to humans as messed up, then for all practical purposes it
> > _is_ messed up.
> 
> No: history is something that gets recorded "for eternity", whereas its
> rendition in human form is done on the fly and can be fixed by
> subsequent releases (or by the use of other tools, options, ...).
> Hence history is of utmost importance, whereas its rendition is secondary.

And you still didn't say what is it important _for_, if not for being
investigated by humans.  Until you explain that, I consider your
arguments void, because all they say is what history _is_, not what's
its purpose.

> > What do you mean by "don't get lost"?  Installing them on the trunk
> > separately, or through cherry-picking, will get them to trunk all the
> > same, no?
> 
> But that depends on not forgetting to install it on both sides, which is
> error prone and is more work than installing only once on the release
> branch and merging later since merging can be batched and largely automated.

How is it more error prone or more work?  All it takes is one merge
command and one ci command.  Since those immediately follow the
original commit, even getting the revision right is easy and thus
error free.

Re: Release branch plans

[Ted Zlatanov]

On Wed, 04 Apr 2012 17:36:33 +0200 Michael Albinus <michael.albinus@gmx.de> wrote: 

MA> Michael Albinus <michael.albinus@gmx.de> writes:
>> Chong Yidong <cyd@gnu.org> writes:
>> 
>>> The entries for pcase.el, secrets.el, notifications.el, and
>>> soap-client.el, but OTOH these don't need documentation in the
>>> manuals (i.e. they are ---).  One other issue is that I think
>>> `delayed-warnings-list' and `delayed-warnings-hook' ought to be
>>> documented; I'll take a closer look at this tomorrow.
>> 
>> For secrets.el, I've promised long long ago to contribute to
>> auth.texi. Ted has added the node "Secret Service API" in that manual, I
>> will try to write the missing text next days.

MA> Done.

Thanks, Michael.  I have edited your submission a bit (I hope you don't
mind my minor nitpicks) and given examples of the integration of
secrets.el with `auth-sources'.

Ted

GnuTLS docs (was: Release branch plans)

[Ted Zlatanov]

On Mon, 02 Apr 2012 03:47:48 -0400 Glenn Morris <rgm@gnu.org> wrote: 

GM> The other ones on my list of maybe-not-done were:
GM> gnutls

I talked to Stefan about this but haven't done work to update the docs:
http://permalink.gmane.org/gmane.emacs.devel/148597

I can work on this but am not sure how to structure it.  GnuTLS is a DLL
library (so it's part of the configure and install), it's some C glue,
it's gnutls.el and the functions therein, and then there's stuff in
processes.texi that will talk about *using* it.

Should I make a separate manual (gnutls.texi) and reference it in all
the places in the Emacs docs that need it, some listed above?

Or should I allow the information about GnuTLS to be scattered across
the Emacs docs?

Thanks
Ted

Re: Release branch plans

[Stefan Monnier]

>> But that depends on not forgetting to install it on both sides, which is
>> error prone and is more work than installing only once on the release
>> branch and merging later since merging can be batched and largely automated.
> How is it more error prone or more work?

I think that's pretty obvious: more error prone because you have to
remember to do it (and since the branch wouldn't be merged, you can't
use "bzr merge" in the usual way), and more work because it can't
be batched (i.e. it's 2*N work, as opposed to N+M where M is the number
of times you decide to "merge from branch").


        Stefan

Re: GnuTLS docs (was: Release branch plans)

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Thu, 05 Apr 2012 08:57:17 -0400
> 
> Should I make a separate manual (gnutls.texi) and reference it in all
> the places in the Emacs docs that need it, some listed above?

That's be a good beginning, I think.  Its main benefit is that it
makes it easier for you to write and organize the material, without
worrying too much about the structure of an existing manual.

Once most of that job is done, we could then consider whether to make
it a chapter in the user manual or leave it as a separate one.

Thanks.

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Thu, 05 Apr 2012 09:17:52 -0400
> 
> >> But that depends on not forgetting to install it on both sides, which is
> >> error prone and is more work than installing only once on the release
> >> branch and merging later since merging can be batched and largely automated.
> > How is it more error prone or more work?
> 
> I think that's pretty obvious: more error prone because you have to
> remember to do it

We could let bzrmerge.el "remember" to do it, can't we?

> and more work because it can't be batched (i.e. it's 2*N work, as
> opposed to N+M where M is the number of times you decide to "merge
> from branch").

That's more work for the machine, not for the human, I think.

Re: Release branch plans

[Eli Zaretskii]

> Date: Thu, 05 Apr 2012 06:04:55 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> > No: history is something that gets recorded "for eternity", whereas its
> > rendition in human form is done on the fly and can be fixed by
> > subsequent releases (or by the use of other tools, options, ...).
> > Hence history is of utmost importance, whereas its rendition is secondary.
> 
> And you still didn't say what is it important _for_, if not for being
> investigated by humans.  Until you explain that, I consider your
> arguments void

Ouch! that sounds offensive, which was not the intent, far from it.
Sorry.

What I meant was that, unless you tell what uses of history you
consider important, the arguments are not convincing at all, because
they don't reveal any practical reasons for which you are so opposed
to cherry-picking, for example.

Re: Release branch plans

[Stefan Monnier]

>> >> But that depends on not forgetting to install it on both sides,
>> >> which is error prone and is more work than installing only once on
>> >> the release branch and merging later since merging can be batched
>> >> and largely automated.
>> > How is it more error prone or more work?
>> I think that's pretty obvious: more error prone because you have to
>> remember to do it
> We could let bzrmerge.el "remember" to do it, can't we?

bzrmerge does something completely different.

>> and more work because it can't be batched (i.e. it's 2*N work, as
>> opposed to N+M where M is the number of times you decide to "merge
>> from branch").
> That's more work for the machine, not for the human, I think.

No, I'm talking about more work for the human.
In any case my decision is made on this matter.


        Stefan

Re: Release branch plans

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Thu, 05 Apr 2012 11:44:49 -0400
> 
> >> >> But that depends on not forgetting to install it on both sides,
> >> >> which is error prone and is more work than installing only once on
> >> >> the release branch and merging later since merging can be batched
> >> >> and largely automated.
> >> > How is it more error prone or more work?
> >> I think that's pretty obvious: more error prone because you have to
> >> remember to do it
> > We could let bzrmerge.el "remember" to do it, can't we?
> 
> bzrmerge does something completely different.

Sure, but I meant to modify it, obviously.

> In any case my decision is made on this matter.

I rather hoped I could understand the motivation behind that, but I
guess not.

Re: GnuTLS docs

[Ted Zlatanov]

On Thu, 05 Apr 2012 17:53:19 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> 
>> Should I make a separate manual (gnutls.texi) and reference it in all
>> the places in the Emacs docs that need it, some listed above?

EZ> That's be a good beginning, I think.  Its main benefit is that it
EZ> makes it easier for you to write and organize the material, without
EZ> worrying too much about the structure of an existing manual.

EZ> Once most of that job is done, we could then consider whether to make
EZ> it a chapter in the user manual or leave it as a separate one.

Is there a model I can follow?  Or should I just wing it?

Ted

auth.texi (was: Release branch plans)

[Michael Albinus]

Ted Zlatanov <tzz@lifelogs.com> writes:

> Thanks, Michael.  I have edited your submission a bit (I hope you don't
> mind my minor nitpicks) and given examples of the integration of
> secrets.el with `auth-sources'.

No problem. Just a question; You have changed the collection names
from @samp{"default"} to @samp{default}. I have used the apostrophes in
order to show that the names are strings, as done for example in the
doc/lispref/* files. I believe we shall keep this (but maybe @code{"default"}
would be more appropriate).

> Ted

Best regards, Michael.

Re: GnuTLS docs

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Thu, 05 Apr 2012 13:12:44 -0400
> 
> Is there a model I can follow?  Or should I just wing it?

Sorry, I'm not sure I understand the question.

Re: auth.texi (was: Release branch plans)

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Date: Thu, 05 Apr 2012 22:18:33 +0200
> 
> No problem. Just a question; You have changed the collection names
> from @samp{"default"} to @samp{default}. I have used the apostrophes in
> order to show that the names are strings, as done for example in the
> doc/lispref/* files. I believe we shall keep this (but maybe @code{"default"}
> would be more appropriate).

Indeed, @code is more appropriate here, as it won't add an extra pair
of single quotes around the string in the printed version of the
manual.

Re: auth.texi

[Ted Zlatanov]

On Fri, 06 Apr 2012 00:23:53 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

>> From: Michael Albinus <michael.albinus@gmx.de>
>> Date: Thu, 05 Apr 2012 22:18:33 +0200
>> 
>> No problem. Just a question; You have changed the collection names
>> from @samp{"default"} to @samp{default}. I have used the apostrophes in
>> order to show that the names are strings, as done for example in the
>> doc/lispref/* files. I believe we shall keep this (but maybe @code{"default"}
>> would be more appropriate).

EZ> Indeed, @code is more appropriate here, as it won't add an extra pair
EZ> of single quotes around the string in the printed version of the
EZ> manual.

Got it; fixed in the Gnus repo.  @samp{"default"} rendered as
`"default"' in text mode, so @code was the better markup.

Thanks
Ted

Re: GnuTLS docs

[Ted Zlatanov]

On Fri, 06 Apr 2012 00:06:14 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Thu, 05 Apr 2012 13:12:44 -0400
>> 
>> Is there a model I can follow?  Or should I just wing it?

EZ> Sorry, I'm not sure I understand the question.

Is there any library that Emacs embeds or links to, which is documented
to the depth that I plan to do with GnuTLS?  I was hoping to have a
template to follow, at least.

Ted

Re: GnuTLS docs

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Thu, 05 Apr 2012 18:32:06 -0400
> 
> Is there any library that Emacs embeds or links to, which is documented
> to the depth that I plan to do with GnuTLS?  I was hoping to have a
> template to follow, at least.

I'm not aware of a template, but you do have a few examples in
doc/misc/: widget.texi, auth.texi, dbus.texi, and smtpmail.texi.  They
all follow the same routine: an Overview followed by descriptions of
the user- or programmer-level features in some logical order.

The various facilities of Texinfo mode should help you in the more
mundane tasks, see the node "Texinfo Mode" in the Texinfo manual.

Re: Release branch plans

[Glenn Morris]

Chong Yidong wrote:

> Now that the 24.0.95 pretest is out, we plan to cut the 24.1 branch
> soon.  After that is done, fixes that should go into 24.1 should be
> committed into the branch, then merged into the trunk.
>
> I'll email emacs-devel with more details shortly before the branch is
> cut.

So are we supposed to start using the emacs-24 branch that seems to exist?

http://lists.gnu.org/archive/html/savannah-hackers/2012-04/msg00011.html
http://bzr.savannah.gnu.org/r/emacs/

Re: GnuTLS docs

[Ted Zlatanov]

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

On Fri, 06 Apr 2012 12:39:01 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Thu, 05 Apr 2012 18:32:06 -0400
>> 
>> Is there any library that Emacs embeds or links to, which is documented
>> to the depth that I plan to do with GnuTLS?  I was hoping to have a
>> template to follow, at least.

EZ> I'm not aware of a template, but you do have a few examples in
EZ> doc/misc/: widget.texi, auth.texi, dbus.texi, and smtpmail.texi.  They
EZ> all follow the same routine: an Overview followed by descriptions of
EZ> the user- or programmer-level features in some logical order.

EZ> The various facilities of Texinfo mode should help you in the more
EZ> mundane tasks, see the node "Texinfo Mode" in the Texinfo manual.

Thanks, Eli.  Could you take a look at the attached first draft?

Thanks
Ted


[-- Attachment #2: gnutls.texi --]
[-- Type: application/x-texinfo, Size: 6469 bytes --]

Re: GnuTLS docs

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Sun, 08 Apr 2012 21:37:43 -0400
> 
> Thanks, Eli.  Could you take a look at the attached first draft?

Looks good, thanks.  A few comments below.

> GnuTLS is a library to establish encrypted SSL or TLS connections.

Acronyms such as SSL and TLS will look better in print if you enclose
them in @acronym{}, as in "@acronym{SSL}".  Also, readers do not
necessarily know what these mean, so something like this would be
better:

  The GnuTLS library is an integral part of Emacs.  Through it, any
  Emacs Lisp program can establish encrypted network connections that
  use @dfn{Socket Secure Layer} (@acronym{SSL}) and @dfn{Transport
  Layer Security} (@acronym{TLS}) protocols.  The process of using
  @acronym{SSL} and @acronym{TLS} in establishing connections is as
  automated and transparent as possible.

Note that I reworded the text to use active rather than passive tense,
which makes the text more clear and concise.  Also note the use of
@dfn whenever new terminology is introduced.

> Emacs supports it through the @code{gnutls.c} and @code{gnutls.h} C
> files and the @file{gnutls.el} Emacs Lisp library.

File names should all have the @file markup, like you did with
gnutls.el.

> @node Overview
> @chapter Overview
> 
> The GnuTLS library is an integral part of Emacs.  Through it,
> encrypted SSL and TLS network connections can be established by any
> Emacs Lisp program.  The process is as automated and transparent as
> possible.

That's an exact repetition of what you said in the Top node.  In the
printed manual, both will appear.  So I would suggest to make the
first one shorter, or maybe eliminate it entirely.

> @chapter Help for users

Chapter, section, and subsection headers should capitalize every word.

> From the user's perspective, there's nothing to the GnuTLS
> integration.  It Just Works for any Emacs Lisp code that uses
> @code{open-protocol-stream} or @code{open-network-stream} (the two are
> equivalent, the first one being an alias to the second).

There should be a cross-reference to where these two functions are
described.  Like this:

  It Just Works for any Emacs Lisp code that uses
  @code{open-protocol-stream} or @code{open-network-stream}
  (@pxref{Network,, Network Connections, elisp, The Emacs Lisp
  Reference Manual}).  The two functions are equivalent, the first one
  being an alias of the second.

> @defvar gnutls-log-level
> 
> The @code{gnutls-log-level} variable sets the log level.  1 is
> verbose.  2 is very verbose.  5 is crazy.  Crazy!  Set it to 1 or 2
> and look in the @code{*Messages*} buffer for the debugging
> information.
> 
> @end defvar
> 
> @defvar gnutls-algorithm-priority
> 
> The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority

It is best not to leave an empty line between @def* and the
explanatory text (here and elsewhere).

> it could be done if needed).  The priority string syntax is in the
> GnuTLS documentation at
> @url{http://www.gnu.org/software/gnutls/documentation.html}.

The last sentence will look better in HTML if you modify it like this:

  The priority string syntax is in the
  @uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS
  documentation}.

> @file{"/etc/ssl/certs/ca-certificates.crt"} for Debian, Ubuntu, Gentoo
> and Arch Linux; @file{"/etc/pki/tls/certs/ca-bundle.crt"} for Fedora
> and RHEL; @file{"/etc/ssl/ca-bundle.pem"} for Suse;
> @file{"/usr/ssl/certs/ca-bundle.crt"} for Cygwin.  You can easily

Please remove the ".." quotes inside @file, they are not needed.

> @defun open-gnutls-stream name buffer host service
> 
> This function creates a buffer connected to a specific @code{host} and
> @code{service} (port number or service name).  The connection process
> is called @code{name} (made unique if necessary).  It returns the
> connection process.

When you describe arguments mentioned in function declarations, use
the @var{} markup, not @code{}.  That's because these arguments stand
for something else: the actual variables that will be used in the call
to the function.  By contrast, @code is for the actual variables and
other literal symbols.

> @lisp
> ;; open a HTTPS connection
> (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
> 
> ;; open a IMAPS connection
> (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
> @end lisp

Judging by these examples, all the arguments are strings, which you
didn't say in the description.  If any of them can be anything else
(e.g., if BUFFER can be a buffer object), you should say that as well.

> @node Index
> @chapter Index
> @printindex cp

This index comes up empty, right?  If you really want a concept index,
you should have at least a few @cindex entries in the manual, where
issues of interest are described.  Or you could omit this index.

Thanks again for working on this.

Re: GnuTLS docs

[Ted Zlatanov]

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

On Mon, 09 Apr 2012 10:39:42 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Sun, 08 Apr 2012 21:37:43 -0400
>> 
>> Thanks, Eli.  Could you take a look at the attached first draft?

EZ> Looks good, thanks.  A few comments below.

Thanks for the comments.  I've used all of them and the doc looks
better.  See attached the proposed patch that modifies all the
Makefile.in mentions and names the new file emacs-gnutls.texi.  Take a
look.

I don't know if I've done the info addition correctly.  I think so, but
`make' keeps re-running `makeinfo' in the doc/misc directory.  Could you
check?

Thanks!
Ted


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: emacs-gnutls.doc.patch --]
[-- Type: text/x-diff, Size: 10504 bytes --]

=== modified file 'ChangeLog'
--- ChangeLog	2012-04-09 06:40:20 +0000
+++ ChangeLog	2012-04-09 12:21:51 +0000
@@ -1,3 +1,7 @@
+2012-04-09  Teodor Zlatanov  <tzz@lifelogs.com>
+
+	* Makefile.in: Add emacs-gnutls to the INFO_FILES target.
+
 2012-04-09  Glenn Morris  <rgm@gnu.org>
 
 	* Makefile.in (leim): Check cd return value.  Pass fewer variables.

=== modified file 'Makefile.in'
--- Makefile.in	2012-04-09 06:40:20 +0000
+++ Makefile.in	2012-04-09 12:16:18 +0000
@@ -136,11 +136,11 @@
 # system, it is inappropriate to imply that it is part of Emacs.
 infodir=@infodir@
 INFO_FILES=ada-mode auth autotype calc ccmode cl dbus dired-x ebrowse	\
-           ede ediff edt eieio efaq eintr elisp emacs emacs-mime epa erc \
-	   ert eshell eudc flymake forms gnus idlwave info mairix-el	\
-	   message mh-e newsticker nxml-mode org pcl-cvs pgg rcirc	\
-	   reftex remember sasl sc semantic ses sieve smtpmail speedbar \
-	   tramp url vip viper widget woman
+           ede ediff edt eieio efaq eintr elisp emacs emacs-gnutls	\
+           emacs-mime epa erc ert eshell eudc flymake forms gnus	\
+           idlwave info mairix-el message mh-e newsticker nxml-mode	\
+           org pcl-cvs pgg rcirc reftex remember sasl sc semantic ses	\
+           sieve smtpmail speedbar tramp url vip viper widget woman
 
 # If no makeinfo was found and configured --without-makeinfo, "no"; else "yes".
 HAVE_MAKEINFO=@HAVE_MAKEINFO@

=== modified file 'doc/misc/ChangeLog'
--- doc/misc/ChangeLog	2012-04-06 01:56:38 +0000
+++ doc/misc/ChangeLog	2012-04-09 12:02:11 +0000
@@ -1,3 +1,10 @@
+2012-04-09  Teodor Zlatanov  <tzz@lifelogs.com>
+
+	* Makefile.in (INFO_TARGETS): Add gnutls.texi to build.
+
+	* gnutls.texi: New file to explain the GnuTLS integration.
+
+
 2012-04-05  Teodor Zlatanov  <tzz@lifelogs.com>
 
 	* auth.texi (Secret Service API): Edit further and give examples.

=== modified file 'doc/misc/Makefile.in'
--- doc/misc/Makefile.in	2012-01-19 07:21:25 +0000
+++ doc/misc/Makefile.in	2012-04-09 12:08:26 +0000
@@ -68,6 +68,7 @@
 	$(infodir)/flymake \
 	$(infodir)/forms \
 	$(infodir)/gnus \
+	$(infodir)/emacs-gnutls \
 	$(infodir)/idlwave \
 	$(infodir)/info \
 	$(infodir)/mairix-el \
@@ -119,6 +120,7 @@
 	flymake.dvi \
 	forms.dvi \
 	gnus.dvi \
+	emacs-gnutls.dvi \
 	idlwave.dvi \
 	info.dvi \
 	mairix-el.dvi \
@@ -170,6 +172,7 @@
 	flymake.pdf \
 	forms.pdf \
 	gnus.pdf \
+	emacs-gnutls.pdf \
 	idlwave.pdf \
 	info.pdf \
 	mairix-el.pdf \
@@ -342,6 +345,15 @@
 eieio.pdf: ${srcdir}/eieio.texi
 	$(ENVADD) $(TEXI2PDF) $<
 
+emacs-gnutls : $(infodir)/emacs-gnutls
+$(infodir)/emacs-gnutls: emacs-gnutls.texi
+	$(mkinfodir)
+	cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $<
+emacs-gnutls.dvi: ${srcdir}/emacs-gnutls.texi
+	$(ENVADD) $(TEXI2DVI) $<
+emacs-gnutls.pdf: ${srcdir}/emacs-gnutls.texi
+	$(ENVADD) $(TEXI2PDF) $<
+
 emacs-mime : $(infodir)/emacs-mime
 $(infodir)/emacs-mime: emacs-mime.texi
 	$(mkinfodir)

=== added file 'doc/misc/emacs-gnutls.texi'
--- doc/misc/emacs-gnutls.texi	1970-01-01 00:00:00 +0000
+++ doc/misc/emacs-gnutls.texi	2012-04-09 11:58:41 +0000
@@ -0,0 +1,198 @@
+\input texinfo                  @c -*-texinfo-*-
+
+@setfilename ../../info/gnutls
+@settitle Emacs GnuTLS Integration @value{VERSION}
+
+@set VERSION 0.3
+
+@copying
+This file describes the Emacs GnuTLS integration.
+
+Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs lisp libraries
+@direntry
+* GnuTLS: (gnutls).          The Emacs GnuTLS Integration.
+@end direntry
+
+@titlepage
+@title Emacs GnuTLS Integration
+@author by Ted Zlatanov
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Emacs GnuTLS
+This manual describes the Emacs GnuTLS integration.
+
+GnuTLS is a library that establishes encrypted @acronym{SSL} or
+@acronym{TLS} connections.  Emacs supports it through the
+@file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el}
+Emacs Lisp library.
+
+@insertcopying
+
+@menu
+* Overview::                    Overview of the GnuTLS integration.
+* Help For Users::
+* Help For Developers::
+* Function Index::
+* Variable Index::
+@end menu
+@end ifnottex
+
+@node Overview
+@chapter Overview
+
+The GnuTLS library is an optional add-on for Emacs.  Through it, any
+Emacs Lisp program can establish encrypted network connections that
+use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer
+Security} (@acronym{TLS}) protocols.  The process of using
+@acronym{SSL} and @acronym{TLS} in establishing connections is as
+automated and transparent as possible.
+
+The user has only a few customization options currently: the log
+level, priority string, trustfile list, and the minimum number of bits
+to be used in Diffie-Hellman key exchange.  Rumors that every Emacs
+library requires at least 83 customizable variables are thus proven
+false.
+
+@node Help For Users
+@chapter Help For Users
+
+From the user's perspective, there's nothing to the GnuTLS
+integration.  It Just Works for any Emacs Lisp code that uses
+@code{open-protocol-stream} or @code{open-network-stream}
+(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
+Manual}).  The two functions are equivalent, the first one being an
+alias of the second.
+
+There's one way to find out if GnuTLS is available, by calling
+@code{gnutls-available-p}.  This is a little bit trickier on the W32
+(Windows) platform, but if you have the GnuTLS DLLs (available from
+@url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli
+Zaretskii) in the same directory as Emacs, you should be OK.
+
+@defun gnutls-available-p
+This function returns t if GnuTLS is available in this instance of Emacs.
+@end defun
+
+Oh, but sometimes things go wrong.  Budgets aren't balanced,
+television ads lie, and even TLS and SSL connections can fail to work
+properly.  Well, there's something to be done in the last case.
+
+@defvar gnutls-log-level
+The @code{gnutls-log-level} variable sets the log level.  1 is
+verbose.  2 is very verbose.  5 is crazy.  Crazy!  Set it to 1 or 2
+and look in the @code{*Messages*} buffer for the debugging
+information.
+@end defvar
+
+@defvar gnutls-algorithm-priority
+The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
+string.  This is global, not per host name (although
+@code{gnutls-negotiate} supports a priority string per connection so
+it could be done if needed).  The priority string syntax is in the
+@uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS
+documentation}.
+@end defvar
+
+@defvar gnutls-trustfiles
+The @code{gnutls-trustfiles} variable is a list of trustfiles
+(certificates for the issuing authorities).  This is global, not per
+host name (although @code{gnutls-negotiate} supports a trustfile per
+connection so it could be done if needed).  The trustfiles can be in
+PEM or DER format and examples can be found in most Unix
+distributions.  By default four locations are tried in this order:
+@file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo
+and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora
+and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse;
+@file{/usr/ssl/certs/ca-bundle.crt} for Cygwin.  You can easily
+customize @code{gnutls-trustfiles} to be something else, but let us
+know if you do, so we can make the change to benefit the other users
+of that platform.
+@end defvar
+
+@defvar gnutls-min-prime-bits
+The @code{gnutls-min-prime-bits} variable is a pretty exotic
+customization for cases where you want to refuse handshakes with keys
+under a specific size.  If you don't know for sure that you need it,
+you don't.  Leave it @code{nil}.
+@end defvar
+
+@node Help For Developers
+@chapter Help For Developers
+
+The GnuTLS library is detected automatically at compile time.  You
+should see that it's enabled in the @code{configure} output.  If not,
+follow the standard procedure for finding out why a system library is
+not picked up by the Emacs compilation.  On the W32 (Windows)
+platform, installing the DLLs with a recent build should be enough.
+
+Just use @code{open-protocol-stream} or @code{open-network-stream}
+(the two are equivalent, the first one being an alias to the second).
+You should not have to use the @file{gnutls.el} functions directly.
+But you can test them with @code{open-gnutls-stream}.
+
+@defun open-gnutls-stream name buffer host service
+This function creates a buffer connected to a specific @var{host} and
+@var{service} (port number or service name).  The parameters and their
+syntax are the same as those given to @code{open-network-stream}
+(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
+Manual}).  The connection process is called @var{name} (made unique if
+necessary).  This function returns the connection process.
+
+@lisp
+;; open a HTTPS connection
+(open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
+
+;; open a IMAPS connection
+(open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
+@end lisp
+
+@end defun
+
+The function @code{gnutls-negotiate} is not generally useful and it
+may change as needed, so please see @file{gnutls.el} for the details.
+
+@defun gnutls-negotiate spec
+Please see @file{gnutls.el} for the @var{spec} details and for usage,
+but do not rely on this function's interface if possible.
+@end defun
+
+@node Function Index
+@chapter Function Index
+@printindex fn
+
+@node Variable Index
+@chapter Variable Index
+@printindex vr
+
+@bye
+
+@c End:

Re: GnuTLS docs

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Mon, 09 Apr 2012 08:25:55 -0400
> 
> I don't know if I've done the info addition correctly.  I think so, but
> `make' keeps re-running `makeinfo' in the doc/misc directory.  Could you
> check?

This happens because of this line in gnutls.texi:

> +@setfilename ../../info/gnutls

which is not what you told Make:

> +emacs-gnutls : $(infodir)/emacs-gnutls
> +$(infodir)/emacs-gnutls: emacs-gnutls.texi
> +	$(mkinfodir)
> +	cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $<

So Make wants to produce 'emacs-gnutls', while your makeinfo command
above produces 'gnutls'.

> --- doc/misc/emacs-gnutls.texi	1970-01-01 00:00:00 +0000
> +++ doc/misc/emacs-gnutls.texi	2012-04-09 11:58:41 +0000

Looks good to me.  Please also change info/dir by adding the
appropriate menu item there at the right place.

> +Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.

Are the copyright years correct? did this file really exist prior to
year 2012?

Re: GnuTLS docs

[Ted Zlatanov]

On Mon, 09 Apr 2012 15:43:51 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

EZ> So Make wants to produce 'emacs-gnutls', while your makeinfo command
EZ> above produces 'gnutls'.

OK, fixed.  Thanks for catching that.

EZ> Looks good to me.  Please also change info/dir by adding the
EZ> appropriate menu item there at the right place.

>> +Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.

EZ> Are the copyright years correct? did this file really exist prior to
EZ> year 2012?

Both fixed and it's pushed to trunk.  It could safely go into 24.1.

Ted

Re: GnuTLS docs

[Glenn Morris]

Ted Zlatanov wrote:

> Both fixed and it's pushed to trunk.  It could safely go into 24.1.

Thanks for writing this. Surely there was no question that this should
go to the emacs-24 branch? Also, it was recently noticed that $< is not
portable in ordinary make rules, so please replace all uses of that with
its expansion.

Re: GnuTLS docs

[Glenn Morris]

Glenn Morris wrote:

> Surely there was no question that this should go to the emacs-24 branch?

That was unclear. I meant: obviously this should be in the emacs-24 branch.

Re: GnuTLS docs

[Ted Zlatanov]

On Mon, 09 Apr 2012 12:17:25 -0400 Glenn Morris <rgm@gnu.org> wrote: 

GM> Ted Zlatanov wrote:
>> Both fixed and it's pushed to trunk.  It could safely go into 24.1.

GM> Thanks for writing this. Surely there was no question that this should
GM> go to the emacs-24 branch?

I didn't want to assume it was OK and I'm not experienced at merging
commits between Bazaar branches.  If the answer is "yes" and "just do
it" OK, but I'm being cautious with the release so close.

GM> Also, it was recently noticed that $< is not portable in ordinary
GM> make rules, so please replace all uses of that with its expansion.

Sorry, I don't understand what you mean.  Is there an example I should
follow?  I copied the auth.texi rules, assuming those were OK.

Ted

Re: GnuTLS docs

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Mon, 09 Apr 2012 12:55:10 -0400
> 
> GM> Thanks for writing this. Surely there was no question that this should
> GM> go to the emacs-24 branch?
> 
> I didn't want to assume it was OK and I'm not experienced at merging
> commits between Bazaar branches.

What Glenn meant is that you should have pushed to the emacs-24 branch
instead, and let it be merged to trunk at some later date, as part of
periodical merges.

But now, since you already pushed to the trunk, what should be done is
install the same changes on the branch, with a "don't merge to trunk"
comment somewhere in the commit message.

Re: GnuTLS docs

[Glenn Morris]

Ted Zlatanov wrote:

> I didn't want to assume it was OK and I'm not experienced at merging
> commits between Bazaar branches.

Well, that's the thing. There would not have been a need for you to
merge it between branches. Just install it in emacs-24 and let Someone
merge it to the trunk along with all the other emacs-24 changes. Now
Someone needs to backport it to emacs-24, so this way is slightly more
work (and leads to a slightly messier history). It's not a big deal; but
if you aren't sure where something should go, just ask first.

> GM> Also, it was recently noticed that $< is not portable in ordinary
> GM> make rules, so please replace all uses of that with its expansion.
>
> Sorry, I don't understand what you mean.  Is there an example I should
> follow? 

The ones in the emacs-24 branch doc Makefiles. :)

Re: GnuTLS docs

[Ted Zlatanov]

On Mon, 09 Apr 2012 13:28:07 -0400 Glenn Morris <rgm@gnu.org> wrote: 

GM> Ted Zlatanov wrote:
>> I didn't want to assume it was OK and I'm not experienced at merging
>> commits between Bazaar branches.

GM> Well, that's the thing. There would not have been a need for you to
GM> merge it between branches. Just install it in emacs-24 and let Someone
GM> merge it to the trunk along with all the other emacs-24 changes. Now
GM> Someone needs to backport it to emacs-24, so this way is slightly more
GM> work (and leads to a slightly messier history). It's not a big deal; but
GM> if you aren't sure where something should go, just ask first.

I really was trying to be careful; sorry for the trouble.  There are
actually two commits I made today, one of which (the GnuTLS handshake
limit) also should be backported but I didn't have approval.

GM> Also, it was recently noticed that $< is not portable in ordinary
GM> make rules, so please replace all uses of that with its expansion.
>> 
>> Sorry, I don't understand what you mean.  Is there an example I should
>> follow? 

GM> The ones in the emacs-24 branch doc Makefiles. :)

(I read that thread today; IMHO we should stick with $< )

Just to confirm, you're asking me to be inconsistent with the trunk
doc/misc/Makefile in order to make the merge easier, and to make the
doc/misc/Makefile commit in the "trunk" branch?

Thanks
Ted

Re: GnuTLS docs

[Glenn Morris]

Ted Zlatanov wrote:

> Just to confirm, you're asking me to be inconsistent with the trunk
> doc/misc/Makefile in order to make the merge easier, and to make the
> doc/misc/Makefile commit in the "trunk" branch?

I guess just leave it as it is in the trunk now. Someone will fix it
after it gets backported to emacs-24, then merge the fix back to the
trunk.

Re: GnuTLS docs

[Glenn Morris]

Now that I actually read it, it is so short that I think it should be
merged into the main emacs/elisp manuals (the style would need adapting).
Unless it is expected to grow significantly in future?

Re: GnuTLS docs

[Ted Zlatanov]

On Mon, 09 Apr 2012 15:59:50 -0400 Glenn Morris <rgm@gnu.org> wrote: 

GM> Now that I actually read it, it is so short that I think it should be
GM> merged into the main emacs/elisp manuals (the style would need adapting).
GM> Unless it is expected to grow significantly in future?

Yes, this was a quick writeup.  We will need to cover priority strings,
fallback strategies, W32 installation and DLLs, the W32 installer I will
work on after 24.1 is out, and probably discuss the peculiarities of the
Emacs integration of GnuTLS.  Mac OS X should also get some coverage;
for me it Just Works but the trustfile location may need adjusting.

I think the W32 DLL glue should also have its own section so it can be
used as a model for other W32 integrations, but I was not involved in
that work and don't know how exemplary that glue was :)  To me it seems
quite good and I haven't heard any complaints about it so far.

Ted

Re: GnuTLS docs

[Glenn Morris]

Ted Zlatanov wrote:

> Yes, this was a quick writeup.  We will need to cover priority strings,
> fallback strategies, W32 installation and DLLs, the W32 installer I will
> work on after 24.1 is out, and probably discuss the peculiarities of the
> Emacs integration of GnuTLS.  Mac OS X should also get some coverage;
> for me it Just Works but the trustfile location may need adjusting.

Some of that sounds a bit overly-detailed to me; but in the absence of
other comments I backported the addition of this manual to the emacs-24
branch. Please make any future improvements to the manual that are
appropriate for 24.1 on that branch rather than the trunk.