threads / patch / 11597

patchmanpages: linking all mail-related commands

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

## tl;dr

3 messages between Jan 11, 2008 and Jan 12, 2008. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Humberto Diogenes· Jan 11, 2008, 23:48 UTC · lore
From: humberto <humberto@digi.com.br>
---
 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(-)
Show changes to 5 files +23 −5

Documentation/git-am.txt, Documentation/git-apply.txt, Documentation/git-format-patch.txt, Documentation/git-imap-send.txt, Documentation/git-send-email.txt

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 <torvalds@osdl.org>
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 <ryan@michonline.com>

-- 
1.5.3.6
Junio C Hamano· Jan 12, 2008, 00:53 UTC · re: Humberto Diogenes · lore

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

Humberto Diogenes <humberto@digi.com.br> writes:
Show 14 quoted lines
> 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).

Show 11 quoted lines
> 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· Jan 12, 2008, 01:44 UTC · re: Junio C Hamano · lore

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:
Show 20 quoted lines
> Humberto Diogenes <humberto@digi.com.br> 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.
Show 16 quoted lines
>> 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. :)
Show 17 quoted lines
>> -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

← back to recent threads