ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicolas Lalevée <nicolas.lale...@hibnet.org>
Subject Re: xooki to asciidoc, a proof of concept
Date Tue, 30 Dec 2014 19:57:47 GMT

> Le 30 déc. 2014 à 17:16, Jean-Louis Boudart <jeanlouis.boudart@gmail.com> a écrit
:
> 
> Hi Nicolas,
> 
> Definitively yes !
> 
> I was trying a similar approach with Jelly/markdown, but due to several
> issues and  lack of time i stopped there.
> I'm fine with asciidoc.
> 
> Could you tell us how you imagine the next steps ?

The next step would be to continue to write the migration, in the xooki2asciidoc.js (see the
htmltags filter, line 855). I have seen that tables, and h1, h2, etc.. are still not handled
properly.
As soon as we are satisfied by the result, we actually do the migration and check in the asciidoc
files. We would then remove evrything about xooki. And probably there will be some last manual
edition to do that the automatic migration didn’t handled well.

> Will xooki only be used to produced toc ?

No need of xooki. I have managed to make asciidoctor read the toc.json, and generate the proper
html, exactly as xooki is doing it. See that nasty ruby file, helpers.rb. :)

> What will be the flow to edit documentation pages ?

The flow to edit the doc would simply to edit the .adoc files directly, there won’t be any
xooki files, we won’t need xooki anymore. The toc.json would still be there too, to be edited
manually. And there would be the asciidoctor ant task to generate the .html files.

Nicolas

> 
> 2014-12-29 23:21 GMT+01:00 Nicolas Lalevée <nicolas.lalevee@hibnet.org>:
> 
>> Hi,
>> 
>> I like xooki because it manages well the templating of the web pages, and
>> it manage well how to build a toc. I hate when documentation is not «
>> browsable », like in a wiki, and xooki handle it well.
>> 
>> But is is quite slow, generating Ivy’s documentation can takes minutes.
>> And on macos jrunscript is considered as a graphical app, so it get the
>> focus. Launching it repeatedly makes the Mac unusable because every few
>> second there is a new jrunscript app getting the focus.
>> And the only web browser in which you can do inline editing is Firefox. It
>> is a good web browser but unfortunately it is not my default one.
>> 
>> Manually rewriting the entire doc in another template engine is out the
>> question. And I don’t want to lose the automatic build of the toc.
>> 
>> So, as a defi, I wondered if I could make xooki.js generate something in a
>> template language rather than .html, and still generate that toc.
>> 
>> I don’t know much any template language, even Markdown. On paper, asciidoc
>> looks better to me, and some Linus recommends it, so let’s try it so I can
>> have a little experience with it.
>> 
>> A few hours of hacking later, doing dirty code in js, using Asciidoctor,
>> coming down to write some Ruby (oh my!), I have something working. Hence my
>> last commit in a dedicated branch in Ivy: xooki2asciidoc
>> 
>> You can test it. To generate the asciidoc files:
>> ant -f build-doc.xml generate-asciidoc
>> To generate the html files from the asciidoc files (in few seconds!):
>> ant -f build-doc.xml generate-doc
>> And open build/doc/index.html to see the result
>> 
>> This is a proof of concept, the conversion of the html tags barely works,
>> but the toc is functional.
>> 
>> So what do you think ? Would you consider changing of template language ?
>> If so would it be asciidoc ?
>> 
>> Is there any objection ? I spent some time on it for fun (and passing time
>> because of some quite late trains), I won’t mind if this is thrown away;
>> but I would like to know if there are some so I won’t continue it.
>> 
>> Nicolas
>> 
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
>> For additional commands, e-mail: dev-help@ant.apache.org
>> 
>> 
> 
> 
> -- 
> Jean Louis Boudart
> Independent consultant
> Apache EasyAnt commiter http://ant.apache.org/easyant/


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message