From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751558AbcBNQ13 (ORCPT ); Sun, 14 Feb 2016 11:27:29 -0500 Received: from home.keithp.com ([63.227.221.253]:50404 "EHLO elaine.keithp.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751496AbcBNQ11 (ORCPT ); Sun, 14 Feb 2016 11:27:27 -0500 From: Keith Packard To: Daniel Vetter Cc: Jonathan Corbet , LKML , linux-doc@vger.kernel.org, Jani Nikula Subject: Re: Kernel docs: muddying the waters a bit In-Reply-To: References: <20160213145317.247c63c7@lwn.net> <86fuwwcdmd.fsf@hiro.keithp.com> User-Agent: Notmuch/0.21 (http://notmuchmail.org) Emacs/24.5.1 (x86_64-pc-linux-gnu) Date: Sun, 14 Feb 2016 08:27:23 -0800 Message-ID: <86d1rzcl5g.fsf@hiro.keithp.com> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable Daniel Vetter 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... =2D-=20 =2Dkeith --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQIVAwUBVsCq69siGmkAAAARAQhFDBAAs1c0ZessiB/w3yLvh0FDki4CJkPTPBl4 VzQeHneait8qhEL10pBw14nAQDzK31pBW45ULT3cATCK4bYqbPSJv+7ZET7lq3SR Gr7nR0gjha1F2DuR+U9HZCxOET1AW98Iqu/S8y9teEMopa1EiQlYSYH/ZQHh+Ekq tUlX5KbQxe/4N3HrZj9aBaZ/WeJw4Ty5meHOWdZagvIduDFd8Vqythy3V13cH3s2 atfP+0AbcRzzalfK9qaueeYbUENHowxWolpltAuXNXBWq96sZvUfEWbOwI/Fj6R+ 34hcx/tuVhQtHNCSeea/sNjoR3jARsWS/UjxAsDPd23Rz94nKRG4C05mWZW9WIjY l++RJu3V6QvwPQy6acBLm4bdyQQuE5wA3vvheylQYx56JT/YfAR91Wg41tavzFYI nEoe/mj+FIHcsz6+7HARXE4ZhfYLOWicr3a7bLa2tbeCZobr30B6hZzLaqFMrfDS VBXD62yDd+/NqwRwi9Mh1EgtHGspr4gZPWN0h+89f0H3mwPMoLpyo67HoJLuxwm1 up8gUheuufks4cHDGtZvvSv5xFy47YqKwB99azG2Pte3TlzFdDv/jomBRMHvMVTc szi8Z08siwgnFxNWS3fMtG/aw20TYsiZQkY+JNbENzpdv5eVRcXAVd6P6fLFhA2C a7UYlfP1Vpk= =GBDY -----END PGP SIGNATURE----- --=-=-=--