Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751663AbcCHNaR (ORCPT ); Tue, 8 Mar 2016 08:30:17 -0500 Received: from lists.s-osg.org ([54.187.51.154]:37006 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751424AbcCHNaK (ORCPT ); Tue, 8 Mar 2016 08:30:10 -0500 Date: Tue, 8 Mar 2016 10:30:03 -0300 From: Mauro Carvalho Chehab To: Dan Allen Cc: Jani Nikula , Russel Winder , Keith Packard , Jonathan Corbet , LKML , linux-doc@vger.kernel.org, Daniel Vetter , Hans Verkuil , linux-media@vger.kernel.org, Graham Whaley Subject: Re: Kernel docs: muddying the waters a bit Message-ID: <20160308103003.5747c76e@recife.lan> In-Reply-To: References: <20160213145317.247c63c7@lwn.net> <87y49zr74t.fsf@intel.com> <20160303071305.247e30b1@lwn.net> <20160303155037.705f33dd@recife.lan> <86egbrm9hw.fsf@hiro.keithp.com> <1457076530.13171.13.camel@winder.org.uk> <87a8m9qoy8.fsf@intel.com> Organization: Samsung X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.29; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 1905 Lines: 49 Em Tue, 08 Mar 2016 05:09:40 -0700 Dan Allen escreveu: > Jani wrote: > > > there was no support for chunked, or split > > to chapters, HTML, and the single page result was simply way too big. > > > > That's not entirely true. First, you can pre-split at the source level > using includes and generate output for each of the masters. That's what I > tend to do and it works really well since these are logical split points. The problem on pre-splitting the documents and process them in separate is that this will break cross-references. At the media uAPI Docbook, we use a lot of cross references. Btw, we use a lot of includes. Currently, it has 187 separate files. We even parse the header files looking for typedefs, structs, enums, #defines and functions, in order to produce a document that will cross-reference the documentation. > Second, there is a custom converter in the works to split post-generate > (which is really what we're talking about when we compare it to the DocBook > toolchain). > > https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/multipage-html5-converter.rb > > It's just a prototype, but proves it is possible by design. I didn't test it, but I saw some comments at the web that the part that would handle cross-references between files is not ready. > Personally, I don't like most chunked HTML approaches because they split > arbitrarily. We are trying to find the right balance so that the output is > actually sensible. There's still work to do, but there are options in the > meantime. Well, if it is capable of creating one chunk per include file, and do cross-references between chunks, this would work for media UAPI book. Yet, it would be good to have the multi-chunk extension packaged on major distros, as I don't like the idea of installing it without using my distro's package manager. -- Thanks, Mauro