Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
From: Junio C Hamano gits...@pobox.com Philip Oakley philipoak...@iee.org writes: I already have a local patch that creates a stalenote.txt file, and includes that in a release-notes(7) man page, but it still leaves the actual release notes in a separate plain text file, linked from the man page, rather than being right at hand, which is what I think readers would expect. Sorry, but I still do not get it. If you have a script Ah, no, it's not a script. I had simply moved the content of the stalenotes section into its own file 'stalenotes.txt' which could then be included both within the git(1) section it came from, and a new release-notes(7) man page. With that set up the Documentation/Makefile would generate the man pages, with their appropriate links, which can be accessed via the 'git help' command. The big 'however' was that this would not actually include the latest release notes as literal text for immediate reading into the release-notes(7) man page, which would be my aim, and I think what Stefan had suggested as a preferred style. that reads git.txt and extracts its stale-notes section to generate the source to be processed into release-notes(7), why can't that script also include the contents of the latest release notes inline into its output? My release notes are _not_ written to be compatible with/processable by AsciiDoc (they are meant to be mere plain text)---perhaps you are wondering if that would make it harder to maintain your script that produces release-notes.txt? Confused... My thought was that the latest release note would be included as literal text, as noted above. Like you say, it may need to be a script, but I was being cautious about what extra work that would entail for each release. My other question would be to ask how you normally manage the up-issue of the stalenotes, and when you would normally create that section in git(1) as I didn't see any ifdef::stalenotes[] being defined anywhere else. I'm not sure if I am understanding the question right (up-issue?), but it used to be that the preformatted and web-reachable manual pages at k.org were processed with stalenotes defined (which by the way was disabled with adaa3caf Meta/dodoc.sh: adjust to the new layout, 2011-11-15 on the todo branch), and 26cfcfbf Add release notes to the distribution., 2007-02-13 used that facility to prepare something like this: I hadn't looked back into that part of history. I was somehow expecting to see 'stalenotes' being defined somewhere in the current documenation preparation options, hence my question about when you would set 'stalenotes'. I'll have a look back at that to see how it was used back then. docs/git.html /git-cat-file.html ... docs/vX.Y.Z/git.html docs/vX.Y.Z/git-cat-file.html ... where the latest one lived immediately underneath docs/*, while older ones were in versioned subdirectories. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
From: Stefan Näwe stefan.na...@atlas-elektronik.com Am 16.01.2014 22:14, schrieb Philip Oakley: From: Stefan Näwe stefan.na...@atlas-elektronik.com [...] I'd really like to see 'git help relnotes' working as well... Stefan Stefan, Were you thinking that all the release notes would be quoted verbatim in the one long man page? Or that it would be a set of links to each of the individual text files (see the ifdef::stalenotes[] in git/Documentation/git.txt)? The latter allows individual release notes to be checked, but still leaves folks with a difficult search problem if they want to find when some command was 'tweaked'. Obviously, any method would need to be easy to maintain. And the RelNotes symlink would need handling. 'git help relnotes' should show the current release note with a link to the previous. OK, that seems very sensible, as the concatenated release notes run to 15k lines! Determining which is the current release note is possibly more problematic, which should be when making the documentation. And 'git help git' should link to the current release note. In some sense that 'current' should be the same as the 'git --version', but through an assumption of a common distribution of git and the documentation, rather than any run time determination. At the moment the Documenation/git.txt 'stalenotes' section could be separated into its own file to act as the basis for the links, but as yet I don't have a good view as to how the current release notes (with / without maint notes?) would be embedded without a maintenance burden for Junio. Philip -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
Philip Oakley philipoak...@iee.org writes: Determining which is the current release note is possibly more problematic, which should be when making the documentation. Hmmm Why? You are already aware of the stale-notes section, no? Isn't the top one the latest? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
From: Junio C Hamano gits...@pobox.com Philip Oakley philipoak...@iee.org writes: Determining which is the current release note is possibly more problematic, which should be when making the documentation. Hmmm Why? You are already aware of the stale-notes section, no? Isn't the top one the latest? It's that the 'git help release-notes' would _include_ the latest release notes, not just link to them (which is what the stalenotes currently does). Or at least that was the idea. Trying to determine the latest version, and then include those release notes, and the subsequent maint notes, into the putative release-notes(7) man page, without causing you any maintenance hassle, was the conceptual problem. I already have a local patch that creates a stalenote.txt file, and includes that in a release-notes(7) man page, but it still leaves the actual release notes in a separate plain text file, linked from the man page, rather than being right at hand, which is what I think readers would expect. My other question would be to ask how you normally manage the up-issue of the stalenotes, and when you would normally create that section in git(1) as I didn't see any ifdef::stalenotes[] being defined anywhere else. Philip -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
Philip Oakley philipoak...@iee.org writes: I already have a local patch that creates a stalenote.txt file, and includes that in a release-notes(7) man page, but it still leaves the actual release notes in a separate plain text file, linked from the man page, rather than being right at hand, which is what I think readers would expect. Sorry, but I still do not get it. If you have a script that reads git.txt and extracts its stale-notes section to generate the source to be processed into release-notes(7), why can't that script also include the contents of the latest release notes inline into its output? My release notes are _not_ written to be compatible with/processable by AsciiDoc (they are meant to be mere plain text)---perhaps you are wondering if that would make it harder to maintain your script that produces release-notes.txt? Confused... My other question would be to ask how you normally manage the up-issue of the stalenotes, and when you would normally create that section in git(1) as I didn't see any ifdef::stalenotes[] being defined anywhere else. I'm not sure if I am understanding the question right (up-issue?), but it used to be that the preformatted and web-reachable manual pages at k.org were processed with stalenotes defined (which by the way was disabled with adaa3caf Meta/dodoc.sh: adjust to the new layout, 2011-11-15 on the todo branch), and 26cfcfbf Add release notes to the distribution., 2007-02-13 used that facility to prepare something like this: docs/git.html /git-cat-file.html ... docs/vX.Y.Z/git.html docs/vX.Y.Z/git-cat-file.html ... where the latest one lived immediately underneath docs/*, while older ones were in versioned subdirectories. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
Am 16.01.2014 22:14, schrieb Philip Oakley:
From: Stefan Näwe stefan.na...@atlas-elektronik.com
[...]
I'd really like to see 'git help relnotes' working as well...
Stefan
Stefan,
Were you thinking that all the release notes would be quoted verbatim in
the one long man page?
Or that it would be a set of links to each of the individual text files
(see the ifdef::stalenotes[] in git/Documentation/git.txt)?
The latter allows individual release notes to be checked, but still
leaves folks with a difficult search problem if they want to find when
some command was 'tweaked'.
Obviously, any method would need to be easy to maintain. And the
RelNotes symlink would need handling.
'git help relnotes' should show the current release note with
a link to the previous.
And 'git help git' should link to the current release note.
Stefan
--
/dev/random says: We now return you to your regularly scheduled flame-throwing
python -c print
'73746566616e2e6e616577654061746c61732d656c656b74726f6e696b2e636f6d'.decode('hex')
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work - relnotes
From: Stefan Näwe stefan.na...@atlas-elektronik.com [...] I'd really like to see 'git help relnotes' working as well... Stefan Stefan, Were you thinking that all the release notes would be quoted verbatim in the one long man page? Or that it would be a set of links to each of the individual text files (see the ifdef::stalenotes[] in git/Documentation/git.txt)? The latter allows individual release notes to be checked, but still leaves folks with a difficult search problem if they want to find when some command was 'tweaked'. Obviously, any method would need to be easy to maintain. And the RelNotes symlink would need handling. Philip -- -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
From: Junio C Hamano gits...@pobox.com
Philip Oakley philipoak...@iee.org writes:
From: Junio C Hamano gits...@pobox.com
I think we already use a nicer way to set up a page alias to keep
old links working than making a copy in Documentation/; please mimic
that if possible.
This was mainly about ensuring that the 'git help' command could
access these extra extra guides that it currently misses. (Tt also
misses the 'user-manual', which isn't a man page, but could have a
link page to guide the seeker of truth between 'git help' and the
actual user-manual)
The only method I can see for that (via help.c) is to get the
filename
format correct. Where you thinking of something else?
I do not have an objection against the creation of giteveryday.txt;
I was questioning the way the original everyday.txt was left behind
to bit-rot. It is good to keep _something_ there, because there may
be old URLs floating around that point at Documentation/everyday.txt,
but the contents of that file does not have to be a stale copy.
Cf. bd4a3d61 (Rename {git- = git}remote-helpers.txt, 2013-01-31)
for how we renamed git-remote-helpers.txt to gitremote-helpers.txt
The commit also highlighted a couple of other places I needed to update
What's the right set of options for format-patch to avoid the bulk
deletions and bulk insertions between the old an new versions? That
commit was amended in situ, so never had the three way
delete/move/create problem.
We have:
everyday.txt (old) - delete
everyday.txt (new) -create (5% similarity)
everyday.txt (old) - giteveryday.txt (95% similarity)
It just feels that 400+ lines of complete deletion doesn't need to be in
the summary patch. I have it in my mind that we always end up with the
deletions being listed.
Philip
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
From: Junio C Hamano gits...@pobox.com I think we already use a nicer way to set up a page alias to keep old links working than making a copy in Documentation/; please mimic that if possible. This was mainly about ensuring that the 'git help' command could access these extra extra guides that it currently misses. (Tt also misses the 'user-manual', which isn't a man page, but could have a link page to guide the seeker of truth between 'git help' and the actual user-manual) The only method I can see for that (via help.c) is to get the filename format correct. Where you thinking of something else? It may be overdue to refresh the suggested set of top 20 commands, as things have vastly changed over the past 8 years. Perhaps we should do that after reorganizing with something like this series. Agreed. -- -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
Am 10.01.2014 00:49, schrieb Junio C Hamano:
I think we already use a nicer way to set up a page alias to keep
old links working than making a copy in Documentation/; please mimic
that if possible.
It may be overdue to refresh the suggested set of top 20 commands,
as things have vastly changed over the past 8 years. Perhaps we
should do that after reorganizing with something like this series.
I'd really like to see 'git help relnotes' working as well...
Stefan
--
/dev/random says: Despite the high cost of living, it remains popular.
python -c print
'73746566616e2e6e616577654061746c61732d656c656b74726f6e696b2e636f6d'.decode('hex')
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
Philip Oakley philipoak...@iee.org writes:
From: Junio C Hamano gits...@pobox.com
I think we already use a nicer way to set up a page alias to keep
old links working than making a copy in Documentation/; please mimic
that if possible.
This was mainly about ensuring that the 'git help' command could
access these extra extra guides that it currently misses. (Tt also
misses the 'user-manual', which isn't a man page, but could have a
link page to guide the seeker of truth between 'git help' and the
actual user-manual)
The only method I can see for that (via help.c) is to get the filename
format correct. Where you thinking of something else?
I do not have an objection against the creation of giteveryday.txt;
I was questioning the way the original everyday.txt was left behind
to bit-rot. It is good to keep _something_ there, because there may
be old URLs floating around that point at Documentation/everyday.txt,
but the contents of that file does not have to be a stale copy.
Cf. bd4a3d61 (Rename {git- = git}remote-helpers.txt, 2013-01-31)
for how we renamed git-remote-helpers.txt to gitremote-helpers.txt
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
Hi, Philip Oakley wrote: The Everyday GIT With 20 Commands Or So guide is not accessible via the git help system. Fix that. Neat. :) Junio covered everything I'd want to say about patch 1/6. After fixing that, I'd suggest squashing all 6 patches into a single patch. They all are part of accomplishing the same task, they are not too hard to read together, and the intermediate state after applying a few but not the rest doesn't make much sense. The details of patches 2-6/6 look good to me. Alternatively, this could be two patches: 1 - modify everyday.txt in place to be a suitable manpage 2 - rename it, add a placeholder for the old name, and modify the build rules to treat it as an actual manpage Hope that helps, Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
From: Junio C Hamano gits...@pobox.com
Philip Oakley philipoak...@iee.org writes:
From: Junio C Hamano gits...@pobox.com
I think we already use a nicer way to set up a page alias to keep
old links working than making a copy in Documentation/; please mimic
that if possible.
This was mainly about ensuring that the 'git help' command could
access these extra extra guides that it currently misses. (Tt also
misses the 'user-manual', which isn't a man page, but could have a
link page to guide the seeker of truth between 'git help' and the
actual user-manual)
The only method I can see for that (via help.c) is to get the
filename
format correct. Where you thinking of something else?
I do not have an objection against the creation of giteveryday.txt;
I was questioning the way the original everyday.txt was left behind
to bit-rot. It is good to keep _something_ there, because there may
be old URLs floating around that point at Documentation/everyday.txt,
but the contents of that file does not have to be a stale copy.
Ah, OK. I had indicated it would be deprecated, but had resisted stating
a date for deletion (e.g. git 2.0).
I was thinking of a moderate two step deprecation period with the next
step being a severely cut down residual stub, before it's removal.
Cf. bd4a3d61 (Rename {git- = git}remote-helpers.txt, 2013-01-31)
for how we renamed git-remote-helpers.txt to gitremote-helpers.txt
I'll have a look at re-using that approach.
Anything else needed before a re-roll?
Philip
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 0/6] Make 'git help everyday' work
The Everyday GIT With 20 Commands Or So guide is not accessible via the git help system. Fix that. The git everyday file does not use the appropriate filenaming convention for help files, and is not suitably formatted for display as a man page. First copy everyday.txt to giteveryday.txt Second modify giteveryday to fit man page formatting. Include the standard Git footer. Third add giteveryday to the manpages make list. Fourth add deprecation note to older everday.txt. Include link to new man page. Fifth add 'everyday' to the help --guides list. Finally, update the git(1) link. The series could be squashed together once any foible have been eliminated. Philip Oakley (6): copy everyday.txt to giteveryday.txt Update giteveryday.txt to fit man page formatting add giteveryday to the manpages make list Add deprecation note to old everyday.txt add 'everyday' to the help --guides list Update git(1) link to giteveryday Documentation/Makefile| 1 + Documentation/everyday.txt| 4 + Documentation/git.txt | 2 +- Documentation/giteveryday.txt | 428 ++ builtin/help.c| 1 + 5 files changed, 435 insertions(+), 1 deletion(-) create mode 100644 Documentation/giteveryday.txt -- 1.8.3.msysgit.0 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/6] Make 'git help everyday' work
I think we already use a nicer way to set up a page alias to keep old links working than making a copy in Documentation/; please mimic that if possible. It may be overdue to refresh the suggested set of top 20 commands, as things have vastly changed over the past 8 years. Perhaps we should do that after reorganizing with something like this series. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
