Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1333515

Re: Kernel docs: muddying the waters a bit

Show all headers | View raw

[Multipart message — attachments visible in raw view] - view raw

Daniel Vetter <daniel.vetter@ffwll.ch> writes:

> The other one is graphs - Keith showed me some neat stuff that
> asciidoc can do, and I definitely wanted to integrate something like
> that as a follow-up into the kerneldoc toolchain. Often a diagram is a
> lot more helpful than lots of words. Can sphinx gives us that too?

.. graphviz::

   digraph foo {
	"bar" -> "baz";
   }

Even better than asciidoc -- svg output is supported in both html and
pdf (when using rst2pdf). I had to hack asciidoc to add support for svg
output when using docbook.

> Wrt reformatting: I'm not going to like it, but I hope that with a bit
> of sed we can fix up any of the asciidoc comments we have already
> easily - right now we don't (yet) use much of the more sophisticated
> markup yet. So much better to change now than 1 year down the road.

I used pandoc on the docbook output from asciidoc to get a 100 page
document converted here. It wasn't perfect -- all of the internal links
were busted, and labels for tables were mis-positioned. It might be that
a few minor fixes to pandoc could be done to add 'sphinx'-specific rst
support that could fix this?

I spent (too much) time yesterday playing with sphinx and generated a
new html theme. Here's the result:

        http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html

Here's the PDF output from rst2pdf, a python-based PDF output which
doesn't use docbook *or* latex:

        http://keithp.com/~keithp/altusmetrum-sphinx/Altus%20Metrum.pdf

I need to spend some quality time building my own PDF theme; the default
provided by rst2pdf isn't great. It does, however, use fontconfig, so
switching fonts is *way* easier than with docbook...

There's currently an incompatibility between the rst2pdf and sphnix
packages in debian (and upstream) which I hacked around to generate that
output, but otherwise I'm using packaged bits.

So, another pro for sphinx appears to be native PDF generation...

-- 
-keith

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-13 23:00 +0100
  Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-14 02:00 +0100
    Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-14 13:30 +0100
      Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-14 17:30 +0100
      Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-17 23:20 +0100
        Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-17 23:30 +0100
          Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-18 10:20 +0100
            Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-18 10:30 +0100
              Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 11:30 +0100
                Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-18 12:30 +0100
                Re: Kernel docs: muddying the waters a bit Hans Verkuil <hverkuil@xs4all.nl> - 2016-02-18 13:10 +0100
                Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 13:50 +0100
                Re: Kernel docs: muddying the waters a bit Patrick Boettcher <patrick.boettcher@posteo.de> - 2016-02-18 14:40 +0100
                Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 13:10 +0100
              Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-18 14:10 +0100
                Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-18 15:50 +0100
  Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-16 09:30 +0100
    Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-16 17:10 +0100
      Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-16 18:20 +0100
    Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-16 20:20 +0100
      Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-16 21:00 +0100
        Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-17 01:10 +0100

csiph-web