Anomalous AUTHOR and DOCUMENTATION sections in manpages

Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Michael Haggerty]

I just noticed that there are exactly four Git manpages with an "AUTHOR"
section and five with a "DOCUMENTATION" section:

    $ make doc
    $ grep -nIE -e '^\.SH "DOCUMENTATION|AUTHOR"' Documentation/*.[0-9]
    Documentation/git-column.1:80:.SH "AUTHOR"
    Documentation/git-for-each-ref.1:272:.SH "AUTHOR"
    Documentation/git-for-each-ref.1:275:.SH "DOCUMENTATION"
    Documentation/git-http-backend.1:404:.SH "AUTHOR"
    Documentation/git-http-backend.1:407:.SH "DOCUMENTATION"
    Documentation/git-notes.1:395:.SH "AUTHOR"
    Documentation/git-notes.1:398:.SH "DOCUMENTATION"
    Documentation/git-remote-ext.1:133:.SH "DOCUMENTATION"
    Documentation/git-remote-fd.1:71:.SH "DOCUMENTATION"

These sections are inconsistent with the other manpages and seem
superfluous in a project that has, on the one hand, a public history
and, on the other hand, hundreds of contributors.  Would the mentioned
authors (CCed) consent to the removal of these sections?

I don't want to step on any feet here.  If you want to keep these
sections, I have no objection.  But my guess is that people added them
in these few instances without realizing that these sections are not
commonly used in Git documentation.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Duy Nguyen]

On Wed, Jan 22, 2014 at 6:22 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> These sections are inconsistent with the other manpages and seem
> superfluous in a project that has, on the one hand, a public history
> and, on the other hand, hundreds of contributors.  Would the mentioned
> authors (CCed) consent to the removal of these sections?

No problem from me.
-- 
Duy

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Johan Herland]

On Wed, Jan 22, 2014 at 12:39 PM, Duy Nguyen <pclouds@gmail.com> wrote:
> On Wed, Jan 22, 2014 at 6:22 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
>> These sections are inconsistent with the other manpages and seem
>> superfluous in a project that has, on the one hand, a public history
>> and, on the other hand, hundreds of contributors.  Would the mentioned
>> authors (CCed) consent to the removal of these sections?
>
> No problem from me.

No problems here.


-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Johannes Schindelin]

Hi Michael,

On Wed, 22 Jan 2014, Michael Haggerty wrote:

> Would the mentioned authors (CCed) consent to the removal of these
> sections?

Fine by me!
Dscho

P.S.: Congrats on your new job!

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Junio C Hamano]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> I just noticed that there are exactly four Git manpages with an "AUTHOR"
> section and five with a "DOCUMENTATION" section:
>
>     $ make doc
>     $ grep -nIE -e '^\.SH "DOCUMENTATION|AUTHOR"' Documentation/*.[0-9]
>     Documentation/git-column.1:80:.SH "AUTHOR"
>     Documentation/git-for-each-ref.1:272:.SH "AUTHOR"
>     Documentation/git-for-each-ref.1:275:.SH "DOCUMENTATION"
>     Documentation/git-http-backend.1:404:.SH "AUTHOR"
>     Documentation/git-http-backend.1:407:.SH "DOCUMENTATION"
>     Documentation/git-notes.1:395:.SH "AUTHOR"
>     Documentation/git-notes.1:398:.SH "DOCUMENTATION"
>     Documentation/git-remote-ext.1:133:.SH "DOCUMENTATION"
>     Documentation/git-remote-fd.1:71:.SH "DOCUMENTATION"
>
> These sections are inconsistent with the other manpages and seem
> superfluous in a project that has, on the one hand, a public history
> and, on the other hand, hundreds of contributors.

We decided at 48bb914e (doc: drop author/documentation sections from
most pages, 2011-03-11) to remove them for that exact reason.  I'd
be happy to see the one in for-each-ref under my name go.

Thanks.

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Shawn Pearce]

On Wed, Jan 22, 2014 at 3:22 AM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> I just noticed that there are exactly four Git manpages with an "AUTHOR"
> section and five with a "DOCUMENTATION" section:
>
>     $ make doc
>     $ grep -nIE -e '^\.SH "DOCUMENTATION|AUTHOR"' Documentation/*.[0-9]
>     Documentation/git-column.1:80:.SH "AUTHOR"
>     Documentation/git-for-each-ref.1:272:.SH "AUTHOR"
>     Documentation/git-for-each-ref.1:275:.SH "DOCUMENTATION"
>     Documentation/git-http-backend.1:404:.SH "AUTHOR"
>     Documentation/git-http-backend.1:407:.SH "DOCUMENTATION"
>     Documentation/git-notes.1:395:.SH "AUTHOR"
>     Documentation/git-notes.1:398:.SH "DOCUMENTATION"
>     Documentation/git-remote-ext.1:133:.SH "DOCUMENTATION"
>     Documentation/git-remote-fd.1:71:.SH "DOCUMENTATION"
>
> These sections are inconsistent with the other manpages and seem
> superfluous in a project that has, on the one hand, a public history
> and, on the other hand, hundreds of contributors.  Would the mentioned
> authors (CCed) consent to the removal of these sections?

Fine by me, authorship is documented by history and blame anyway.  :-)

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Ilari Liusvaara]

On Wed, Jan 22, 2014 at 12:22:23PM +0100, Michael Haggerty wrote:
> I just noticed that there are exactly four Git manpages with an "AUTHOR"
> section and five with a "DOCUMENTATION" section:
> 
> These sections are inconsistent with the other manpages and seem
> superfluous in a project that has, on the one hand, a public history
> and, on the other hand, hundreds of contributors.  Would the mentioned
> authors (CCed) consent to the removal of these sections?
 
Sure (it has been copyedited a lot anyway).

-Ilari

Re: Anomalous AUTHOR and DOCUMENTATION sections in manpages

[Michael Haggerty]

On 01/22/2014 12:22 PM, Michael Haggerty wrote:
> I just noticed that there are exactly four Git manpages with an "AUTHOR"
> section and five with a "DOCUMENTATION" section:
> 
>     $ make doc
>     $ grep -nIE -e '^\.SH "DOCUMENTATION|AUTHOR"' Documentation/*.[0-9]
>     Documentation/git-column.1:80:.SH "AUTHOR"
>     Documentation/git-for-each-ref.1:272:.SH "AUTHOR"
>     Documentation/git-for-each-ref.1:275:.SH "DOCUMENTATION"
>     Documentation/git-http-backend.1:404:.SH "AUTHOR"
>     Documentation/git-http-backend.1:407:.SH "DOCUMENTATION"
>     Documentation/git-notes.1:395:.SH "AUTHOR"
>     Documentation/git-notes.1:398:.SH "DOCUMENTATION"
>     Documentation/git-remote-ext.1:133:.SH "DOCUMENTATION"
>     Documentation/git-remote-fd.1:71:.SH "DOCUMENTATION"
> 
> These sections are inconsistent with the other manpages and seem
> superfluous in a project that has, on the one hand, a public history
> and, on the other hand, hundreds of contributors.  Would the mentioned
> authors (CCed) consent to the removal of these sections?
> 
> I don't want to step on any feet here.  If you want to keep these
> sections, I have no objection.  But my guess is that people added them
> in these few instances without realizing that these sections are not
> commonly used in Git documentation.

Thanks for the quick responses, everybody.  I'll prepare a patch.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/