From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S965222AbcAZMiz (ORCPT ); Tue, 26 Jan 2016 07:38:55 -0500 Received: from mga09.intel.com ([134.134.136.24]:20496 "EHLO mga09.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S965058AbcAZMiw (ORCPT ); Tue, 26 Jan 2016 07:38:52 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.22,350,1449561600"; d="scan'208";a="901353630" From: Jani Nikula To: Daniel Vetter Cc: Jonathan Corbet , linux-doc@vger.kernel.org, Linux Kernel Mailing List Subject: Re: [RFC] A first shot at asciidoc-based formatted docs In-Reply-To: Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <1453764522-29030-1-git-send-email-corbet@lwn.net> User-Agent: Notmuch/0.21+34~g7dd0d52 (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Tue, 26 Jan 2016 14:38:49 +0200 Message-ID: <87r3h4tt0m.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, 26 Jan 2016, Daniel Vetter wrote: > On Tue, Jan 26, 2016 at 1:08 PM, Jani Nikula wrote: >> I first took roughly the same approach as you did. I was really >> impressed with the speed and the beauty of the produced HTML. The >> trouble is, neither asciidoc nor asciidoctor can produce chunked (split >> to several pages) HTML directly. This is a showstopper for the gpu >> document which turns into 1.3 MB of HTML, which looks pretty but is a >> paint to navigate. To do chunked output, you have to output DocBook and >> handle that like we do now. So while I would like to have asciidoc >> generate HTML directly for speed and beauty, I ended up going the >> asciidoc to DocBook path. The upside is all the output formats are >> supported. > > This is a big bummer since with the parralized kernel-doc processing > using Makefiles and using asciidoctor even building something big like > the gpu docs is down to 2-3 seconds. From a clean tree, so not even > counting incremental speed-ups. Unfortunately asciidoc doesn't have an > built-in tooling (there's some experimental extensions) to split > things up. Basically asciidoc -> HTML is about as fast as asciidoc -> XML, and with parallel kernel-doc it really is fast. Sadly the XML -> HTML part still takes forever. I just want to emphasize that we can get parallel kernel-doc with either pipeline. It is also possible to enable both pipelines, i.e. have a fast path HTML generation with few external dependencies and the Swiss army knife slow path with XML. I should also remind us that the original goal was to enable lightweight markup for documentation. This seems very much achievable now. We don't have to solve all the existing problems with the XML pipeline right now. And asciidoc suits this well, as it can also feed to the existing pipeline. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center