Re: [PATCH 6/6] format-patch --notes: show notes after three-dashes

From: "Junio C Hamano" <redacted>

"Philip Oakley" [off-list ref] writes:

quoted

From: "Junio C Hamano" <redacted>

quoted

When inserting the note after the commit log message to format-patch
output, add three dashes before the note.  Record the fact that we
did so in the rev_info and omit showing duplicated three dashes in
the usual codepath that is used when notes are not being shown.

Signed-off-by: Junio C Hamano <redacted>

Should this also include a documentation update to make this
substantive benefit visible, whether that be in the format-patch man
pages, the SubmittingPatches guide, in the git-notes description of 
'A
typical use...', or even in the user-manual?

Eric Blake (http://mid.gmane.org/507EB310.8020904@redhat.com) was

Added to distribution.

already working on a documentation updates already, I thought.

As long as what it does is explained in format-patch, that is fine.

I do not think this deserves to be in the SubmittingPatches.  We do
tell people to hide "here is the context of the change" additional
explanation after three dashes, but how the submitters prepare that
text is entirely up to them (and I personally do not think notes is
not necessarily the right tool to do so).

I've prepared a short set of patches for the documenation I mentioned.

I, like Eric, feel some of the methods available are a bit of a Catch 
22.
We do need to at least hint about capabilities as a way of helping new
users who aren't already experts (the inverse Kruger Dunning problem).

I have tried hard to make the patches concise so hopefully they will be
acceptable.

Philip