From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933479AbcAYX2v (ORCPT ); Mon, 25 Jan 2016 18:28:51 -0500 Received: from tex.lwn.net ([70.33.254.29]:60354 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932544AbcAYX2t (ORCPT ); Mon, 25 Jan 2016 18:28:49 -0500 From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Daniel Vetter Subject: [RFC] A first shot at asciidoc-based formatted docs Date: Mon, 25 Jan 2016 16:28:38 -0700 Message-Id: <1453764522-29030-1-git-send-email-corbet@lwn.net> X-Mailer: git-send-email 2.7.0 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org So here is a proof-of-concept series showing how a fully asciidoc-based toolchain might work. Lots of hackery here, this isn't meant to be applied to anything at this point, but it's a good start. What this series has is: - Jani Nikula's patch adding asciidoc output to kernel-doc. Thanks for doing this! It was the kickstart that was needed to get this process going. - Tweak docproc to handle asciidoc template files. If a template ends in ".adt", it's an asciidoc template; it's processed pretty much the same way, except that kernel-doc gets the -asciidoc argument. - Bash on the Makefile to get it to process asciidoc templates into HTML. Naturally this was where most of the time got spent. *Only* HTML output works at the moment. - Convert tracepoints.html to tpoint.adt as a proof of concept. It works, and the output is much pleasing, IMO. I'm sure there's a thousand details to deal with, and there is the issue of the other output formats. asciidoctor claims to be able to create man pages, but I've not tried that yet; neither tool will do PDF. Maybe we could rely on pandoc to do that. Otherwise, getting to asciidoc to XML is straightforward, so it should be possible to use xmlto as is done now. It's all in the doc/asciidoc branch of git://git.lwn.net/linux.git if anybody wants to mess with it. Comments? jon