uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Richard Eckart de Castilho <...@apache.org>
Subject Re: Switching uimaFIT from Docbook to Asciidoc(tor)
Date Wed, 06 Jan 2016 22:07:28 GMT
On 05.01.2016, at 22:28, Marshall Schor <msa@schor.com> wrote:
> 
> In general, I don't mind; we have DUCC docs in LaTeX for example.
> 
> The issue may be that others would need to climb learning curves to contribute.
> In this case, it seems the learning curve would be small because the markup is
> probably "familiar", and it has a maven plugin / tool chain for producing the
> results.

The learning curve should be reasonably low. Much lower than DocBook or LaTeX! ;)

> Does this require installing "Ruby" on any workstation used to run the maven
> plugin, or JRuby to run on top of a JVM?

Asciidoctor runs using JRuby on a JVM - no need to install anything. 
Maven handles it all.

> Any licensing issues?

Not aware of any. Asciidoctor is MIT License. Also, we only use it during
build. The CSS that is part of the generated HTML files is MIT license.

https://github.com/asciidoctor/asciidoctor/blob/master/data/stylesheets/asciidoctor-default.css

The original Asciidoc written in Python is GPL, but not planning to use that.

> Is this something that's likely to stick around for many years?

Hard to tell. My feeling is that it is seeing a good adoption in the community.
Several Apache projects are already using it, e.g. Groovy and ISIS.

The download numbers on rubygems also aren't that bad: https://rubygems.org/gems/asciidoctor

The BUS factor appears to be rather low, but given that there is a wide adoption,
I believe somebody would step up if Dan Allen becomes unavailable.

https://github.com/asciidoctor/asciidoctor/graphs/contributors

> The users guide for Asciidoctor says its toolchain can produce PDF (although it
> later says Asciidoctor PDF is currently **alpha** software).

Well, I tried it already. The usual problems with code blocks that may go beyond
the page width (we know those from DocBook) and I had one problem where I had
very long heading causing an exception. Otherwise, it appeared quite ok to me.
But currently, I'm not using it.

> So I'm not sure
> about the motivation for the PDF question in your note. The PDF output may or
> may not be used by users;

The motivation is that we currently offer PDF versions of our documentation.
I personally don't think it is particular important to do it, rather a nice-to-have. 

> I wonder if there are statistics out there on the www
> that we could find to shed light on this, including trends over time.  If we had
> our website instrumented for many years, we could maybe see this directly...

Unfortunately, I believe we won't be able to see that. My understanding is that
Google Analytics counts page views when a user opens a page. This means the following
things cannot be counted:

- clicks on links that go to pages outside our website
- clicks on links that go to pages in our website that do not embed the GA JS,
  e.g. Docbook pages, PDFs, or downloads
- clicks in intra-page links (which just cause the browser to jump, but do not
  trigger the GA JS by default).

> Try searching on something like:
> 
>    technical document pdf vs html trends
> or just
>    pdf vs html
> 
> We could also ask on the user list about who uses PDFs.
> My guess is that both forms are wanted by the broader user population. 

I'd rather just drop it and if people complain about PDF missing, considering
to reinstate it - unless devs have a strong opinion about this.

> One final note: I remember there were a bunch of small issues we had to tackle
> to finally get a working toolchain for pdfs/html from our docbooks, including
> sizing issues for figures.  If I recall correctly, there were some hacks needed
> to get everything working, that are now hidden in the tool chain customizations.

I take this as a warning that there might be things to customize in Asciidoctor.
Sure ;) One customization I've recently played with is including a nicer
table of contents using tocify: 

http://stackoverflow.com/questions/34481638/how-to-use-tocify-with-asciidoctor-for-a-dynamic-toc

Images are not a problem for uimaFIT now - there are no images in the
documentation.

Cheers,

-- Richard


Mime
View raw message