From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752047AbdLFSX3 (ORCPT ); Wed, 6 Dec 2017 13:23:29 -0500 Received: from ms.lwn.net ([45.79.88.28]:50868 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751945AbdLFSX1 (ORCPT ); Wed, 6 Dec 2017 13:23:27 -0500 Date: Wed, 6 Dec 2017 11:23:25 -0700 From: Jonathan Corbet To: "Tobin C. Harding" Cc: Randy Dunlap , Andrew Murray , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH] doc: convert printk-formats.txt to rst Message-ID: <20171206112325.1a76727b@lwn.net> In-Reply-To: <1512524729-16051-1-git-send-email-me@tobin.cc> References: <1512524729-16051-1-git-send-email-me@tobin.cc> Organization: LWN.net MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 6 Dec 2017 12:45:29 +1100 "Tobin C. Harding" wrote: > Documentation/printk-formats.txt is a candidate for conversion to > ReStructuredText format. Some effort has already been made to do this > conversion even thought the suffix is currently .txt > > Changes required to complete conversion > > - Add double backticks where needed. > - Add entry to Documentation/index.rst > - Use flat-table instead of ASCII table. > - Fix minor grammatical errors. > - Capitalize headers and correctly order heading adornments. > - Use 'Passed by reference' uniformly. > - Update pointer documentation around %px specifier. > - Fix erroneous double backticks (to commas). > - Simplify documentation for kobject. > - Convert lib/vsnprintf.c function docs to use kernel-docs and > include in Documentation/printk-formats.rst > > Signed-off-by: Tobin C. Harding Some comments from a quick review: - I would just put this into the core-api manual; we don't need to create a separate section for printk formats. - I agree with Markus and others about the table. I think I would go a little further and encourage observance of the "use minimal markup" rule. Lots of ``double backticks`` make for slightly nicer HTML/PDF output, but they come at the expense of plain-text readability, which is something we really don't want to sacrifice. - The vsprintf.c part is probably not for me to take, so it should be split out into a separate patch. Thanks for working on this, jon