Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754841AbcKUPlv (ORCPT ); Mon, 21 Nov 2016 10:41:51 -0500 Received: from bedivere.hansenpartnership.com ([66.63.167.143]:54748 "EHLO bedivere.hansenpartnership.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754061AbcKUPlt (ORCPT ); Mon, 21 Nov 2016 10:41:49 -0500 Message-ID: <1479742905.2309.16.camel@HansenPartnership.com> Subject: Re: [Ksummit-discuss] Including images on Sphinx documents From: James Bottomley To: Mauro Carvalho Chehab , Johannes Berg Cc: ksummit-discuss@lists.linuxfoundation.org, "open list:DOCUMENTATION" , Linux Kernel Mailing List , Linus Torvalds , Linux Media Mailing List Date: Mon, 21 Nov 2016 07:41:45 -0800 In-Reply-To: <20161121120657.31eaeca4@vento.lan> References: <20161107075524.49d83697@vento.lan> <11020459.EheIgy38UF@wuerfel> <20161116182633.74559ffd@vento.lan> <2923918.nyphv1Ma7d@wuerfel> <20161119101543.12b89563@lwn.net> <1479724781.8662.18.camel@sipsolutions.net> <20161121120657.31eaeca4@vento.lan> Content-Type: text/plain; charset="UTF-8" X-Mailer: Evolution 3.16.5 Mime-Version: 1.0 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2123 Lines: 43 On Mon, 2016-11-21 at 12:06 -0200, Mauro Carvalho Chehab wrote: > Em Mon, 21 Nov 2016 11:39:41 +0100 > Johannes Berg escreveu: > > On Sat, 2016-11-19 at 10:15 -0700, Jonathan Corbet wrote: > > > > > Rather than beating our heads against the wall trying to convert > > > between various image formats, maybe we need to take a step > > > back. We're trying to build better documentation, and there is > > > certainly a place for diagrams and such in that > > > documentation. Johannes was asking about it for the 802.11 docs, > > > and I know Paul has run into these issues with the RCU docs as > > > well. Might there be a tool or an extension out there that would > > > allow us to express these diagrams in a text-friendly, editable > > > form? > > > > > > With some effort, I bet we could get rid of a number of the > > > images, and perhaps end up with something that makes sense when > > > read in the .rst source files as an extra benefit. > > > > I tend to agree, and I think that having this readable in the text > > would be good. > > > > You had pointed me to this plugin before > > https://pythonhosted.org/sphinxcontrib-aafig/ > > > > but I don't think it can actually represent any of the pictures. > > No, but there are some ascii art images inside some txt/rst files > and inside some kernel-doc comments. We could either use the above > extension for them or to convert into some image. The ascii art > images I saw seem to be diagrams, so Graphviz would allow replacing > most of them, if not all. Please don't replace ASCII art that effectively conveys conceptual diagrams. If you do, we'll wind up in situations where someone hasn't built the docs and doesn't possess the tools to see a diagram that was previously shown by every text editor (or can't be bothered to dig out the now separate file). In the name of creating "prettier" diagrams (and final doc), we'll have damaged capacity to understand stuff by just reading the source if this diagram is in kernel doc comments. I think this is a good application of "if it ain't broke, don't fix it". James