patchProvide a release-notes man page / guide

A few days too late for the 1.9.0 release cycle :(

This responds to Stefan N�we's request for a 'git help' command that would access the release notes. ($gmane/240595 17 Jan 2014).

I've used the full name "release-notes" for the help guide rather than Stefan's original 'git help relnotes'.

The release-notes man page lists just the notes for the current release. The combined notes for all releases is nearing 15k lines.

The one formatting niggle is that the included text is column shifted such that the the raw text now starts at col 12 for the man page and reaches past col 80. Is there an attribute setting to not indent the included block text within a man page? It looks fine in --web format.

I used the code.google link, rather than kernel.org, for the previous release notes to match the link currently used in git(1).

Philip Oakley (1):
  Provide a release-notes man page / guide

 Documentation/Makefile             |  1 +
 Documentation/gitrelease-notes.txt | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 Documentation/gitrelease-notes.txt

Use the symlinked RelNote file as a list-block to act as the core of the release-notes man page.

The mantainers work load should not be affected.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---

The included lines are inset 11 spaces by the man page asciidoc formatting so some are more than 80 characters long. No negative indent mechanism for the list block was found - suggestions welcomed.

The use of the stalenotes section from git(1) was rejected.

The stalenotes, with over two hundred links, has greater than 2 digits allowed in the trailing link list on the man page, so would miss the hundreds digit.

Also the html links for the "documentation for release x.y.z"
(at kerenel.org) are to html files that are not actually made
by the makefile.
---
 Documentation/Makefile             |  1 +
 Documentation/gitrelease-notes.txt | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 Documentation/gitrelease-notes.txt

Philip Oakley <philipoakley@iee.org> writes:

RelNotes are incremental and only useful for those who know what the immediately previous release contained, but for most people who get their Git from distros, I have this impression that the versions of Git they get skip versions, and seeing the notable changes since the previous source release will not give them wrong information---they may have this warm fuzzy feeling that they know what is going on, but they are missing information on all the accumulated changes that were added in earlier versions their distro skipped---these changes are still in the version they are running. I do not understand why it is even a good idea to show release notes from the command line "git" interface.

From: "Junio C Hamano" <gitster@pobox.com>

That's a reasonable argument. I did look at trying to get the "stalenotes" to work as an alternative, that is extract the stalenotes section from the git.txt, and create a release notes man page from that. However there were two issues there that I couldn't solve (noted in the cover letter).

The first is that the man page generator does not expect more than 99 references so the link numbers repeat themselves. I'm sure that is fixable by someone who knows the insides of acsiidoc.

The other was that the links for the main version documentation appear to been to be made at kernel.org, so that links back there are created. Again I wasn't sure how that should be resolved.

My looking at this came from Stefan's suggestion noted above $gmane/240595. So it had at least one follower ;-)

Philip

Am 18.02.2014 23:54, schrieb Philip Oakley:

Yes, but I could definitely live without it. I compile git myself on most systems and that would just be a convenient way to get an overview of the latest changes.

Regards,
  Stefan

"Philip Oakley" <philipoakley@iee.org> writes:

I am not making an "argument" in order to reject the notion of making release-notes available, though. I am only raising concerns, pointing out why showing a single release notes as if that were the only one that matter is misleading.

I am not opposed to the idea of making release notes available to those who do not install from the source, by the way. Being able to grep the release notes through may help people who are writing scripts using Git to learn when a feature they want to use appeared to make sure that they do not depend on something their users may not have yet. But for that kind of users, it would be more helpful to point them at the file location they can find the plain text version of release notes, instead of giving them a bunch of web links they need to read through page by page.

I am not sure if stale-notes section meshes well with this; the primary purpose of it was to point at the whole documentation set, not just release-notes, for versions previously released, so those who came to a website that hosts them can pick the version, possibly a stale one, that they are using and read the manual pages for that version, without seeing newer features that are not available to them. I do not think it is very useful in the context of your "You received this single version of software, and you can access its documentation off-line" feature---you cannot reasonably expect that such a software release to contain all the past documentation sets, but even if you could do so, that is not how normal people use the installed documentation, i.e. to learn about older releases that they no longer have.

Junio C Hamano <gitster@pobox.com> writes:

Ehh,, s/will not give them/will give them/; obviously...