Re: Kernel docs: muddying the waters a bit

[Keith Packard]

Mauro Carvalho Chehab  writes:

> On my tests, Sphinix seemed too limited to format tables. Asciidoc
> produced an output that worked better.

Yes, asciidoc has much more flexibility in table formatting, including
the ability to control text layout within cells and full control over
borders.

However, I think asciidoc has two serious problems:

  1) the python version (asciidoc) appears to have been abandoned in
 favor of the ruby version. 

  2) It really is just a docbook pre-processor. Native html/latex output
 is poorly supported at best, and exposes only a small subset of the
 full capabilities of the input language.

As such, we would have to commit to using the ruby version and either
committing to fixing the native html output backend or continuing to use
the rest of the docbook toolchain.

We could insist on using the python version, of course. I spent a bit of
time hacking that up to add 'real' support for a table-of-contents in
the native HTML backend and it looks like getting those changes
upstreamed would be reasonably straightforward. However, we'd end up
'owning' the code, and I'm not sure we want to.

-- 
-keith


signature.asc
Description: PGP signature

Re: Kernel docs: muddying the waters a bit

[Keith Packard]

Jonathan Corbet  writes:

> Indeed, I doubt many people want the DocBook itself.

Might be nice to actually have a set of requirements before anyone tries
to select a suitable system then :-)

Here's my current set:

asciidocsphinx

htmlvia docbook native
native (kinda)
pdf via docbook via rst2pdf
epubvia docbook?native
man ?   native?

-- 
-keith


signature.asc
Description: PGP signature

Re: Kernel docs: muddying the waters a bit

[Keith Packard]

Jonathan Corbet  writes:

> Asciidoc is a credible solution to the formatted documentation problem,
> but it's not the only such; I'd like to be sure that we pick the right
> one.  I worry that asciidoc seems to be aimed mostly at small documents,
> and that the project itself seems a little lifeless - it's not a good
> sign when your main page's link to the repository has been dead for a long
> time.  (Asciidoctor seems more active, with the Github folks behind it,
> but that means bringing Ruby into the picture).

I was surprised when one of the asciidoctor developers said that
asciidoc itself was 'in maintenance mode for existing users'. I've tried
asciidoctor but never got it to the point where I was happy with the
results. Having two tools using the same nominal format doesn't seem
like a great idea to me.

It's also clear from my hacking in asciidoc that docbook is the expected
target for that tool. I've managed to make direct HTML output usable,
but LaTeX doesn't work at all. Something which focuses on direct HTML
(and ePub) output would be pretty nice.

> An alternative we haven't really looked at yet is ReStructuredText (or
> "RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
> YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
> Sphinx is a fairly sophisticated documentation system that uses RST.

I've installed debian's python3-sphinx package; it looks like it doesn't
have a huge dependency chain below it, which is a nice change.

I translated a fairly long document from asciidoc to rst using pandoc by
using the docbook output from asciidoc -- pandoc doesn't have a native
asciidoc reader, only a writer. The result didn't totally suck, although
I haven't messed with fixing the css or using a different theme at all.

http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html

I installed the sphinxcontrib.fulltoc extension so that the whole TOC
was visible from each section; this made navigating a lot easier. Having
search included (if you have javascript) seems like a nice feature.

> Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
> requirements there.

Having functional native latex output means that even PDF generation is
lighterweight though.

> It produces integrated, multi-file HTML natively,
> with a TOC, an index, cross-file cross references, and more.  It can make
> things like function indexes.  It claims output in epub, docbook, and man
> (I've not yet messed with those).  The path to PDF is via latex; clearly
> the docbook path could be used too.

I've tried epub and latex backends; epub seems just fine (it's just
html, after all). LaTeX works, and generates functional PDF, but I'm
going to have to spend a bunch of time making it looks nice.

http://keithp.com/~keithp/altusmetrum-sphinx/AltusMetrum.pdf

> So can we discuss?  I'm not saying we have to use Sphinx, but, should we
> choose not to, we should do so with open eyes and good reasons for the
> course we do take.  What do you all think?

Having spent the afternoon playing with it, I'm definitely
impressed. I've spent a ton of time getting asciidoc to generate html
and pdf that I can tolerate; far too much of that involved hacking XML
files related to the docbook backend.

Pros

 * Credible HTML output without docbook

 * Credible PDF output without docbook.

 * Constructs a unified set of documents across
   multiple files.

 * Written in Python (2 or 3)

 * PanDoc already supports rst for both input and output. So, if we get
   bored with RST, we've got a way out.

Cons

 * Table formatting doesn't seem as sophisticated as asciidoc

Questions

 * Conditional text appears to be harder to manage (I haven't managed to
   make it work at all).

 * Takes over a directory making building more than one
   document in a directory hard/impossible? The config file must be
   named 'conf.py'?
   
-- 
-keith


signature.asc
Description: PGP signature

Re: [RFC] A first shot at asciidoc-based formatted docs

[Keith Packard]

Keith Packard <kei...@keithp.com> writes:

> The goal would be to create an html document which could be used without
> javascript, and that would work without css as well.

I've managed to hack up asciidoc to generate the TOC within the
document, rather than requiring javascript. The changes are fairly
minor, and seem to add a nice generalization to the asciidoc environment
which should be useful in other contexts.

The changes consist of two bits -- the first is to allow the diversion
of some text from .conf file sections, the second is to postpone some
attribute processing to a second pass over the document so that the TOC
can be inserted in the desired location, instead of requiring that it be
placed at the bottom.

I've sent these changes upstream, and also pushed them to a personal
asciidoc git repository at :

git clone git://keithp.com/git/asciidoc

-- 
-keith


signature.asc
Description: PGP signature

Re: [RFC] A first shot at asciidoc-based formatted docs

[Keith Packard]

Jani Nikula  writes:

> One of the chief complaints with the current pipeline (and some of the
> proposals) has been the need to install lots of tools with lots of
> dependencies. I would like to avoid the need to install bleeding edge
> tools and stick to what's already widely available in distros. Thus I
> would like to avoid hacking asciidoc for our needs.

Agreed. That means using docbook for now; the native html output from
asciidoc is simply not usable for anything more complicated than a short
web page. However, getting ready to collapse the pipeline by eliminating
docbook seems like a good medium-term goal.

> Also, I'd really like to not have to decide between asciidoc and
> asciidoctor, and only use features supported by both. Let the users pick
> which one suits them better.

That's harder; you'll have much different output from the two
processors. I'd encourage the selection of one of these two tools
instead of trying to support both. I've settled on using only asciidoc
for my other projects because it doesn't require the installation of a
whole new language environment.

-- 
-keith


signature.asc
Description: PGP signature