From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S935023AbcIQJ64 (ORCPT ); Sat, 17 Sep 2016 05:58:56 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:49085 "EHLO s-opensource.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754949AbcIQJ6y (ORCPT ); Sat, 17 Sep 2016 05:58:54 -0400 Date: Sat, 17 Sep 2016 06:58:46 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Linux Doc Mailing List , Mauro Carvalho Chehab , Markus Heiser , Jani Nikula , LKML Subject: Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup Message-ID: <20160917065846.2dc2a259@vento.lan> In-Reply-To: <20160916173426.697d61d4@vento.lan> References: <20160916111314.5baa4f97@lwn.net> <20160916173426.697d61d4@vento.lan> Organization: Samsung X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Fri, 16 Sep 2016 17:34:26 -0300 Mauro Carvalho Chehab escreveu: > Em Fri, 16 Sep 2016 11:13:14 -0600 > Jonathan Corbet escreveu: > > > On Wed, 14 Sep 2016 08:06:36 -0300 > > Mauro Carvalho Chehab wrote: > > > > > - Fix all chapter identation; > > > - add c blocks where needed; > > > > Here is where I think we need a bit of a philosophical discussion... > > > > > - Chapter 1: Indentation > > > +Indentation > > > +----------- > > > > You're a fan of having sphinx do the numbering, and I have no problem > > understanding why. But this will defeat people who say "look in chapter 3 > > of Documentation/CodingStyle". We're removing a bit of information from > > the plain-text file and reserving it for the formatted version. If we're > > really going to do that, we should do it consciously, with the knowledge > > that there is a cost involved. > > > > We'll see this even more with SubmittingPatches, where it is quite common > > for people to cite the number of the section they think is being violated > > in any given situation. > > I see your point. However, AFAICT, there's no way to disable automatic > numbering for LaTeX and PDF formats: it will always generate an index. > > It is actually worse than that: the numbering for the LaTeX and PDF > versions of the document don't match with the numbering for html and ePub, > and Sphinx restricts to just one numbered TOC index for the entire document. > > Currently, I don't know any way to fix it. > > So, keeping the current numeration there will produce a very messy > PDF output, with the two numerations altogether. I found a way to trick Sphinx LaTeX output... not an elegant one, though. We can add a tag at development-process/index.rst like: .. raw:: latex \renewcommand\thesection{\fnsymbol{section}} \renewcommand\thesubsection{\thesection.\fnsymbol{subsection}} To use symbols instead of numbers for chapter numbering, or something like: .. raw:: latex \renewcommand\thesection* \renewcommand\thesubsection* To use "*" for both sections and subsections. That makes it to hide the numbers on the LaTeX output. There's an issue, though: it will internally keep numbering it. So, the page feet will still be numbering the chapters/sections like: Chapter 12. Email clients info for Linux *. Some email client (MUA) hints And the chapter will still be numbered like: CHAPTER TWELVE -------------------------------------- EMAIL CLIENTS INFO FOR LINUX Maybe we could get better results if we do something at the LaTex preamble, but the preamble is global to *ALL* books that use the same conf.py. As we chose to have just one global conf.py for the "normal" output, IMHO, we should not put book-specific stuff at the latex_elements preamble. Also, please notice that this will also affect numeration at the documents of the development-process.rst sub-book. One alternative would be: 1) remove the :numbered: from the TOC tree. This will disable numbering for HTML/ePub outputs; 2) use a \renewcommand just for \thesubsection (as doing it for the chapter doesn't really work fine); 3) keep the already existing numeration for CodingStyle/SubmitPatches/... Maybe we could find a way to change the top-level "chapter" numeration to "part", but, I suspect that such change would need to be done via LaTeX preamble. Comments? PoC patch enclosed. Thanks, Mauro diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst index e38f44729a21..92055353a598 100644 --- a/Documentation/development-process/index.rst +++ b/Documentation/development-process/index.rst @@ -1,10 +1,17 @@ +.. raw:: latex + + \renewcommand\thesection* +.. \renewcommand\thesubsection* +.. \renewcommand\thesection{\fnsymbol{section}} +.. \renewcommand\thesubsection{\thesection.\fnsymbol{subsection}} + + Linux Kernel Development Documentation ====================================== Contents: .. toctree:: - :numbered: :maxdepth: 2 HOWTO