From: Humberto Diogenes Date: Sat, 12 Jan 2008 01:44:04 GMT Subject: Re: [PATCH] manpages: linking all mail-related commands Message-ID: In-Reply-To: <7vy7avzwx4.fsf@gitster.siamese.dyndns.org> Wow! I wasn't expecting that amount of reply for such a simple patch. :-) I just found it unnecessarily hard to discover all the email-related commands in git (even though I already used some of them). My point-of-view is that some additional links wouldn't hurt. More answers below. On 11/01/2008, at 21:53, Junio C Hamano wrote: > Humberto Diogenes writes: > >> diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt >> index e4a6b3a..fd00fc1 100644 >> --- a/Documentation/git-am.txt >> +++ b/Documentation/git-am.txt >> @@ -144,8 +144,10 @@ names. >> >> SEE ALSO >> -------- >> -gitlink:git-apply[1]. >> - >> +gitlink:git-apply[1], >> +gitlink:git-format-patch[1], >> +gitlink:git-imap-send[1], >> +gitlink:git-send-email[1] > > I do not see a point in this. "am" is a tool for people who > accept and they do not care how the sender prepared > (format-patch) nor sent (imap-send nor send-email). Well, if I'm reading the docs about how a program works with some input, I'll sure want to know which commands in the package generate that kind of output. I think at least git-format-patch deserves a link (am: read, format-patch: write). And yes, I managed to find git-am and git-send-email but couldn't remember the name of git-format-patch. > On the other hand, as am uses mailinfo and mailsplit, it may be > worth mentioning them (although I suspect not all the readers of > manual page of am are interested in such a low level details). I think it wouldn't hurt. >> diff --git a/Documentation/git-apply.txt b/Documentation/git- >> apply.txt >> index c1c54bf..53fa937 100644 >> --- a/Documentation/git-apply.txt >> +++ b/Documentation/git-apply.txt >> @@ -189,6 +189,10 @@ If --index is not specified, then the >> submodule commits in the patch >> are ignored and only the absence of presence of the corresponding >> subdirectory is checked and (if possible) updated. >> >> +See Also >> +-------- >> +gitlink:git-am[1] > > Why? apply is not about email at all. am uses apply but not > the other way around. Imagine you don't know git, but know there's some command to apply patches from mailboxes. Which one would you try first: git-am or git- apply? "git-am" just doesn't say anything (for beginners, at least). > This feels you are going a bit overboard, as if you are adding > "See Also: git[7]" everywhere (even though it is not that bad). Again: wouldn't hurt. :) >> -See Also >> +SEE ALSO >> -------- > > If you are standardizing between "SEE ALSO" and "See Also", I > think that is a worthy thing to do independent from the > additional links, but (1) please be consistent --- you tried to > add "See Also" yoruself above, (2) please have a separate patch > that does _ONLY_ the standardization to "SEE ALSO", and not > limited to commands that has (maybe remotely) something to do > with emailed patch workflow. > > Right now, I count 14 "SEE ALSO" and 17 "See Also". 127 spell > "Author" and 5 spell "AUTHOR". Everybody says "NAME", "SYNOPSIS", > "DESCRIPTION", and "OPTIONS". > > I think we should spell these in all uppercase. Yes, I could see this one coming. Sorry. -- Humberto Diógenes http://humberto.digi.com.br