From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932560AbcFIQj5 (ORCPT ); Thu, 9 Jun 2016 12:39:57 -0400 Received: from mga03.intel.com ([134.134.136.65]:56798 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751815AbcFIQj4 (ORCPT ); Thu, 9 Jun 2016 12:39:56 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,445,1459839600"; d="scan'208";a="998685439" From: Jani Nikula To: Jonathan Corbet Cc: Markus Heiser , Daniel Vetter , Grant Likely , Mauro Carvalho Chehab , Keith Packard , LKML , linux-doc@vger.kernel.org, Hans Verkuil Subject: Re: [PATCH v2 29/38] kernel-doc: limit the "section header:" detection to a select few In-Reply-To: <20160609090327.762bbd41@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20160609090327.762bbd41@lwn.net> User-Agent: Notmuch/0.22+9~g73339ad (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Thu, 09 Jun 2016 19:39:34 +0300 Message-ID: <87y46e9v09.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, 09 Jun 2016, Jonathan Corbet wrote: > On Sat, 4 Jun 2016 14:37:30 +0300 > Jani Nikula wrote: > >> kernel-doc currently identifies anything matching "section header:" >> (specifically a string of word characters and spaces followed by a >> colon) as a new section in the documentation comment, and renders the >> section header accordingly. >> >> Unfortunately, this turns all uses of colon into sections, mostly >> unintentionally. > > I've been looking at how the patch series changes (traditional) htmldocs > generation, and this one is responsible for a lot of them. Those changes > are almost all good! There is a lot of cruft out there. Just FWIW, I'm > going to add a patch putting "note|examples|" into the list, since those > appear to be intentional. Heh, you scared me a bit until the "almost all good" part. :) I'm fine with adding more to the list, although I intentionally tried to keep them to a minimum initially. I had this vague idea of turning some of the "note" and "warning" type things into rst admonitions [1] later on, but I don't really have a concrete plan yet. BR, Jani. [1] http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions -- Jani Nikula, Intel Open Source Technology Center