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.

From: "Junio C Hamano" <redacted>

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.

--

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')"

From: "Stefan Näwe" <redacted>
[...]

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

--

Am 16.01.2014 22:14, schrieb Philip Oakley:

From: "Stefan Näwe" <redacted>
[...]

quoted

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')"

From: "Stefan Näwe" <redacted>

Am 16.01.2014 22:14, schrieb Philip Oakley:

quoted

From: "Stefan Näwe" <redacted>
[...]

quoted

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