linux-kernel - Re: [PATCH] doc: flat-table directive

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] [thread-next>] [day] [month] [year] [list]

Message-Id: <BD7AE7E8-5F9F-4271-B870-5F291A6F2EE8@darmarit.de>
Date:	Fri, 1 Jul 2016 14:18:34 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Mauro Carvalho Chehab <mchehab@....samsung.com>
Cc:	Jonathan Corbet <corbet@....net>, jani.nikula@...el.com,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	hverkuil@...all.nl, daniel.vetter@...ll.ch, airlied@...il.com,
	grant.likely@...retlab.ca, rdunlap@...radead.org, keithp@...thp.com
Subject: Re: [PATCH] doc: flat-table directive

Am 01.07.2016 um 11:38 schrieb Mauro Carvalho Chehab <mchehab@....samsung.com>:

> Btw, yesterday, I tried to add references to a C code, at video.rst,
> just like we did with DocBook:
> 
> .. code-block:: c
>   :caption: Example 2: Switching to the first video input
> 
>   int index;
> 
>   index = 0;
> 
>   if (-1 == ioctl(fd, :ref:`VIDIOC_S_INPUT <vidioc-s-input>`, &index)) {
>       perror("VIDIOC_S_INPUT");
>       exit(EXIT_FAILURE);
>   }
> 
> But Sphinx didn't allow doing it. I was unable to find any syntax
> on it that would make Sphinx use a monospaced font but still parse
> the references at the code. While for those small examples this would
> be ok, This is something that we do want for the header files that
> we put at V4L and DVB annexes. For DocBook, we do a lot of things like
> this at the DocBook/media/Makefile:
> 	sed -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" videodev2.h

In Sphinx, the code-block directive is a literal block, no refs or markup
will be interpreted. This is different to what you know from DocBook.
I will look for a solution, that matches your requirement.

> The actual code is a way more complex, but basically the idea is that
> it escapes anything that DocBook might interpret as a command, and adds
> <link> tags for every enum, typedef, ioctl, struct, syscall and define
> it founds at the header files. the xmllint will produce errors when
> links are not solved, and we'll be able to detect that the API is not
> fully documented.

OK, checking dead internal links might be one requirement more. Normally 
sphinx reports internal refs which are broken with a WARNING, but I have to
analyze what xmllint checks and how we could realize something similar
in sphinx / or if it is enough what sphinx reports. 

> We need to do a similar process with Sphinx. A side effect is that, if
> someone looks at the header files in the anexes, it can click on any
> symbol at the API and see the full documentation.

Yes, altogether, it seems to be a nice feature, I have to think about. But
I will point it in a separate thread.

> --
> 
> Btw, in the case of the above example, I had to manually number it as
> "Example 2", because I was unable to find a way with Sphinx to auto
> numerate code-block captions. This is also something we want to fix,
> as it is very hard to manually number things on a 600+ page document.
> 

This needs a sphinx extension, I have seen similar solutions for 
numbering figures on the net ... I will try to find a small solution.

But before I will send out some small patches which are needed 
first (IMHO). E.g. customizing the RTD theme for rendering large 
tables in HTML well and activation of useful extensions like todolist.
I have this in my "chaotic bulk" patch :-) ... I will separate it out
an send it to Jon one by one.

-- Markus --

> Regards,
> Mauro