uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marshall Schor <...@schor.com>
Subject Re: Switching uimaFIT from Docbook to Asciidoc(tor)
Date Tue, 05 Jan 2016 21:28:35 GMT
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.

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

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

The users guide for Asciidoctor says its toolchain can produce PDF (although it
later says Asciidoctor PDF is currently **alpha** software).  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; 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...

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. 

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.

-Marshall

On 12/23/2015 7:45 PM, Richard Eckart de Castilho wrote:
> Hi all,
>
> after having tried Docbook for years and even paying a license for a commercial XML editor
with Docbook support, I'm now a very happy user of Asciitoc(tor). It is a markdown-type format
and comes with a nice Maven plugin.
>
> http://asciidoctor.org
>
> Would anybody mind if I switched uimaFIT documentation from Docbook to Asciidoc?
>
> Further, would anybody mind if there was only an HTML-based documentation and no PDF-based
documentation?
>
> Best,
>
> -- Richard


Mime
View raw message