Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
User-Agent: Cyrus-JMAP/3.1.6-449-gfb3fc5a-fmstable-20190430v1
Mime-Version: 1.0
Message-Id: <f48e76f7-6b95-4cf0-82af-424119bb2eb4@www.fastmail.com>
In-Reply-To: <a3db1384695bbaa051d93c18ac30175fb95165e3.camel@vmware.com>
References: <20190510001747.8767-1-tobin@kernel.org>
 <a3db1384695bbaa051d93c18ac30175fb95165e3.camel@vmware.com>
Date:   Fri, 10 May 2019 16:45:45 -0400
From:   "Tobin C. Harding" <me@tobin.cc>
To:     "Thomas Hellstrom" <thellstrom@vmware.com>,
        "Jonathan Corbet" <corbet@lwn.net>
Cc:     "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        "minyard@acm.org" <minyard@acm.org>,
        "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
        "Tobin C. Harding" <tobin@kernel.org>
Subject: Re: [PATCH] docs: Move kref.txt to core-api/kref.rst
Content-Type: text/plain
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk


On Fri, May 10, 2019, at 20:51, Thomas Hellstrom wrote:
> On Fri, 2019-05-10 at 10:17 +1000, Tobin C. Harding wrote:
> > kref.txt is already written using correct ReStructuredText
> > format.  This
> > can be verified as follows
> > 
> > 	make cleandocs
> > 	make htmldocs 2> pre.stderr
> > 	mv Documentation/kref.txt Documentation/core-api/kref.rst
> > 	// Add 'kref' to core-api/index.rst
> > 	make cleandocs
> > 	make htmldocs 2> post.stderr
> > 	diff pre.stderr post.stderr
> > 
> > While doing the file move, fix the column width to be 72 characters
> > wide
> > as it is throughout the document.  This is whitespace only.  kref.txt
> > is
> > so cleanly written its a shame to have these few extra wide
> > paragraphs.
> > 
> > Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> > ---
> > 
> > I'm always hesitant to do docs patches that seem obvious - is there
> > some reason that this was not done previously?
> 
> Speaking for the two kref.txt paragraphs, the width being too large is
> simply an oversight from my side. I wasn't aware of the restriction.

I'm a stickler for the rules, often to peoples dismay :) AFAIK they say 80 characters for code and 72 for documentation is optimal.  I'm yet to understand why 72 was chosen.  Maybe because its the same length as the git commit long message but that doesn't explain where _that_ came from.  I read once that they used 72 characters on punch cards at times because the other 8 characters got mangled for some reason.  Anyways, its kinda anal and I only change it if it looks like doing so is not going to annoy people _too_ much or, like in this instance, if the file is super clean except for a small portion.  The rest of this file seems to use 72 so I thought it was worth the change.

I'm open to being told otherwise.

Hope this is interesting for you,
Tobin.