Re: [PATCH] manpages: linking all mail-related commands
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:44:04
Humberto Diogenes [off-list ref] writes:
quoted hunk
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).
quoted hunk
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.