linux-kernel - Re: [Ksummit-discuss] Including images on Sphinx documents

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: <8737j0hpi0.fsf@intel.com>
Date:   Wed, 09 Nov 2016 13:16:55 +0200
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Markus Heiser <markus.heiser@...marit.de>,
        Josh Triplett <josh@...htriplett.org>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org,
        linux-media@...r.kernel.org,
        ksummit-discuss@...ts.linuxfoundation.org,
        linux-doc@...r.kernel.org
Subject: Re: [Ksummit-discuss] Including images on Sphinx documents

On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@...marit.de> wrote:
> Am 07.11.2016 um 18:01 schrieb Josh Triplett <josh@...htriplett.org>:
>
>> On Mon, Nov 07, 2016 at 07:55:24AM -0200, Mauro Carvalho Chehab wrote:
>>> 2) add an Sphinx extension that would internally call ImageMagick and/or
>>>  inkscape to convert the bitmap;
>> 
>> This seems sensible; Sphinx should directly handle the source format we
>> want to use for images/diagrams.
>> 
>>> 3) if possible, add an extension to trick Sphinx for it to consider the 
>>>  output dir as a source dir too.
>> 
>> Or to provide an additional source path and point that at the output
>> directory.
>
> The sphinx-build command excepts only one 'sourcedir' argument. All
> reST files in this folder (and below) are parsed.
>
> Most (all?) directives which include content like images or literalinclude
> except only relative pathnames. Where *relative* means, relative to the
> reST file where the directive is used. For security reasons relative 
> pathnames outside 'sourcepath' are not excepted.
>
> So I vote for :
>
>> 1) copy (or symlink) all rst files to Documentation/output (or to the
>>  build dir specified via O= directive) and generate the *.pdf there,
>>  and produce those converted images via Makefile.;

We're supposed to solve problems, not create new ones.

> Placing reST files together with the *autogenerated* (intermediate) 
> content from
>
> * image conversions,
> * reST content build from MAINTAINERS,
> * reST content build for ABI
> * etc.
>
> has the nice side effect, that we can get rid of all theses BUILDDIR
> quirks in the Makefile.sphinx
>
> Additional, we can write Makefile targets to build the above listed
> intermediate content relative to the $PWD, which is what Linux's
> Makefiles usual do (instead of quirking with a BUILDDIR).
>
> E.g. with, we can also get rid of the 'kernel-include' directive 
> and replace it, with Sphinx's common 'literaliclude' and we do not
> need any extensions to include intermediate PDFs or whatever
> intermediate content we might want to generate. 

Well, kernel-include is a hack to make parse-headers.pl work, which is
also a hack that IMHO shouldn't exist...

> IMO placing 'sourcedir' to O= is more sane since this marries the
> Linux Makefile concept (relative to $PWD) with the sphinx concept
> (in or below 'sourcedir').
>
>
> -- Markus --
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@...r.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center