From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752931AbeAJVHk (ORCPT + 1 other); Wed, 10 Jan 2018 16:07:40 -0500 Received: from mx0b-001b2d01.pphosted.com ([148.163.158.5]:54184 "EHLO mx0a-001b2d01.pphosted.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752531AbeAJVHg (ORCPT ); Wed, 10 Jan 2018 16:07:36 -0500 Date: Wed, 10 Jan 2018 13:08:16 -0800 From: "Paul E. McKenney" To: "Tobin C. Harding" Cc: Jonathan Corbet , Josh Triplett , Linux docs , LKML Subject: Re: [RFC] doc: fix code snippet build warnings Reply-To: paulmck@linux.vnet.ibm.com References: <1515557093-7036-1-git-send-email-me@tobin.cc> <20180110163702.GF9671@linux.vnet.ibm.com> <20180110203007.GB25272@eros> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20180110203007.GB25272@eros> User-Agent: Mutt/1.5.21 (2010-09-15) X-TM-AS-GCONF: 00 x-cbid: 18011021-0048-0000-0000-000002226FDA X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00008355; HX=3.00000241; KW=3.00000007; PH=3.00000004; SC=3.00000245; SDB=6.00973133; UDB=6.00493052; IPR=6.00753083; BA=6.00005772; NDR=6.00000001; ZLA=6.00000005; ZF=6.00000009; ZB=6.00000000; ZP=6.00000000; ZH=6.00000000; ZU=6.00000002; MB=3.00018968; XFM=3.00000015; UTC=2018-01-10 21:07:34 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 18011021-0049-0000-0000-000043BB4069 Message-Id: <20180110210816.GN9671@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2018-01-10_11:,, signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 impostorscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1709140000 definitions=main-1801100289 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: On Thu, Jan 11, 2018 at 07:30:07AM +1100, Tobin C. Harding wrote: > On Wed, Jan 10, 2018 at 08:37:02AM -0800, Paul E. McKenney wrote: > > On Wed, Jan 10, 2018 at 03:04:53PM +1100, Tobin C. Harding wrote: > > > Posting as RFC in the hope that someone knows how to massage sphinx > > > correctly to fix this patch. > > > > I would welcome that. ;-) > > > > > Currently function kernel-doc contains a multi-line code snippet. This > > > is causing sphinx to emit 5 build warnings > > > > > > WARNING: Unexpected indentation. > > > WARNING: Unexpected indentation. > > > WARNING: Block quote ends without a blank line; unexpected unindent. > > > WARNING: Block quote ends without a blank line; unexpected unindent. > > > WARNING: Inline literal start-string without end-string. > > > > > > And the snippet is not rendering correctly in HTML. > > > > > > We can stop shpinx complaining by using '::' instead of the currently > > > used '``' however this still does not render correctly in HTML. The > > > rendering is [arguably] better but still incorrect. Sphinx renders two > > > function calls thus: > > > > > > :c:func:`rcu_read_lock()`; > > > > > > The rest of the snippet does however have correct spacing. > > > > > > Use '::' to pre-fix code snippet. Clears build warnings but does not > > > render correctly. > > > > If the usual docbook suspects ack this, I would be happy to carry it. > > > > Cue debate over silent vs. noisy errors. ;-) > > Besides making me laugh out loud I did not think of this issue while > patching. FWIW, now you have mentioned it, I favour noisy errors :) Very good, will leave this one alone, then. ;-) Thanx, Paul