# [PATCH] manpages: linking all mail-related commands 3 messages from 2008-01-11 to 2008-01-12. Participants: Humberto Diogenes, Junio C Hamano. Thread: https://gitlist.dev/t/11597 ## Humberto Diogenes, 2008-01-11 23:48 Subject: [PATCH] manpages: linking all mail-related commands Message-ID: <1200095286-2621-1-git-send-email-humberto@digi.com.br> URL: https://gitlist.dev/e/1200095286-2621-1-git-send-email-humberto%40digi.com.br ``` From: humberto --- Documentation/git-am.txt | 6 ++++-- Documentation/git-apply.txt | 4 ++++ Documentation/git-format-patch.txt | 7 ++++--- Documentation/git-imap-send.txt | 5 +++++ Documentation/git-send-email.txt | 6 ++++++ 5 files changed, 23 insertions(+), 5 deletions(-) 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] Author ------ 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] + Author ------ Written by Linus Torvalds diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index f0617ef..0221b6d 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -184,10 +184,11 @@ git-format-patch -3:: Extract three topmost commits from the current branch and format them as e-mailable patches. -See Also +SEE ALSO -------- -gitlink:git-am[1], gitlink:git-send-email[1] - +gitlink:git-am[1], +gitlink:git-imap-send[1], +gitlink:git-send-email[1] Author ------ diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index eca9e9c..8397dcb 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -48,6 +48,11 @@ BUGS ---- Doesn't handle lines starting with "From " in the message body. +SEE ALSO +-------- +gitlink:git-am[1], +gitlink:git-format-patch[1], +gitlink:git-send-email[1] Author ------ diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 16bfd7b..9214596 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -143,6 +143,12 @@ sendemail.chainreplyto:: sendemail.smtpserver:: Default smtp server to use. +SEE ALSO +-------- +gitlink:git-am[1], +gitlink:git-format-patch[1], +gitlink:git-imap-send[1] + Author ------ Written by Ryan Anderson -- 1.5.3.6 ``` ## Junio C Hamano, 2008-01-12 00:53 Subject: Re: [PATCH] manpages: linking all mail-related commands Message-ID: <7vy7avzwx4.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vy7avzwx4.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1200095286-2621-1-git-send-email-humberto@digi.com.br> ``` 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). 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). > 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. 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). > -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. ``` ## Humberto Diogenes, 2008-01-12 01:44 Subject: Re: [PATCH] manpages: linking all mail-related commands Message-ID: URL: https://gitlist.dev/e/B4D45D5C-618B-46E4-B66A-27914EF810A7%40digi.com.br 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 ```