linux-kernel - Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20160917065846.2dc2a259@vento.lan>
Date:   Sat, 17 Sep 2016 06:58:46 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        LKML <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST
 markup

Em Fri, 16 Sep 2016 17:34:26 -0300
Mauro Carvalho Chehab <mchehab@...pensource.com> escreveu:

> Em Fri, 16 Sep 2016 11:13:14 -0600
> Jonathan Corbet <corbet@....net> escreveu:
> 
> > On Wed, 14 Sep 2016 08:06:36 -0300
> > Mauro Carvalho Chehab <mchehab@...pensource.com> 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