From: Philip Oakley Date: Wed, 19 Sep 2012 07:19:16 GMT Subject: Re: [PATCHv2 4/8] Doc: 'git' has a discussion section Message-ID: In-Reply-To: <7vr4pyisc3.fsf@alter.siamese.dyndns.org> From: "Junio C Hamano" > Philip Oakley writes: > >> Highlight there is a further discussion section later in >> git man page >> >> Signed-off-by: Philip Oakley >> >> diff --git a/Documentation/git.txt b/Documentation/git.txt >> index 34d8a1b..d932a3e 100644 >> --- a/Documentation/git.txt >> +++ b/Documentation/git.txt >> @@ -30,6 +30,7 @@ After you mastered the basic concepts, you can come >> back to this >> page to learn what commands git offers. You can learn more about >> individual git commands with "git help command". linkgit:gitcli[7] >> manual page gives you an overview of the command line command >> syntax. >> +See also the Discussion and Further Documentation sections below. >> >> Formatted and hyperlinked version of the latest git documentation >> can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. > > I am not sure if this is appropriate. > > The primary objective of this paragraph is to nudge people who try > to dive into the body of this document without understanding the > fundamentals (which tends to waste their time) without spending too > many words. After they visit these pages, they are armed with > sufficient prerequisite knowledge and are free to go directly to > documentation for individual subcommands, and this page is one of > such pages. I do not think Discussion and Further Documentation > sections are such prerequisites they should read before coming back > here and looking at the list of subcommands. > It was more that _all_ man pages link back here, and these (hopefully useful ;-) Discussion and Further Documentation sections are waaay off the bottom of the screen, so are easy to never see. Actually I would have liked to make it an active link to the section for any html version, but wasn't sure how to achieve that - is there a method to link within a document? Philip