Re: [PATCH] manpages: linking all mail-related commands

   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 [off-list ref] writes:

quoted

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.

quoted

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. :)

quoted

-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