The guys at asciidoctor have created a transformation tool for markdown to asciidoctor. I wonder if we can use that to write a transformer for the wiki markup into asciidoctor.
https://github.com/bodiam/markdown-to-asciidoc Martijn On Sun, Dec 7, 2014 at 7:23 PM, Martin Funk <[email protected]> wrote: > With slow, but hopefully steady, pace I kept on working on transforming the > wicket user guide. > > Currently all *.gdoc files are renamed to *.adoc and they are included into > index.adoc. > So all previous gdoc files should be somehow visible in the generated html. > Quite a lot of things are still broken, but at least the document is already > recognizable. > > The lowest hanging fruits for me were: > - the import of the *.png and their visiblity in the html > - property rendering of the code blocks > > But there are still lots of low hanging fruits left. > I opened up a issue list on github: > https://github.com/mafulafunk/wicket/issues/ > > Any pull request, help, new issues and advice are welcome. > > The code can for the asciidoc can be found in the user-guide-6 branch or my > wicket fork. > https://github.com/mafulafunk/wicket/tree/user-guide-6 > > The global build should render the html but a simple "mvn" in the > wicket-user-guide folder should be > fine too. > > Martin > >> Am 30.11.2014 um 20:42 schrieb Martijn Dashorst <[email protected]>: >> >> Hey Martin, >> >> Great initiative! >> >> The gendocs script is a workaround for a bug in the >> asciidoctor-maven-plugin when you use section includes from XML files. >> If you didn't use those, the generation works fine. With 1.5.2 this >> should be solved according to the asciidoctor folks. >> >> I am going to try an automated approach to transcoding the gdocs to >> asciidoctor format. Transcoding 226 pages manually is not my cup of >> tea. From there we can go in and fix formatting issues, use actual >> includes etc. >> >> I have been looking at several projects at apache and it appears we >> are not the only ones trying to do this: >> >> http://mail-archives.apache.org/mod_mbox/deltaspike-dev/201408.mbox/%3CCAAxZHdd8VQL3CZSwbg9Xeexdm5uevNDwAZ6Hbtvd=Ptkp2=z...@mail.gmail.com%3E >> >> So this seems to be a good approach. >> >> Martijn >> >> On Sun, Nov 30, 2014 at 8:20 PM, Martin Funk <[email protected]> wrote: >>> Hi Martijn, >>> >>> taking your suggestion, my pick on this can be found here: >>> https://github.com/mafulafunk/wicket/tree/user-guide-6 >>> Most of the contribution can be found in the wicket-user-guide subdir >>> >>> I just dug through the first 4 Chapters, to get my own feel for it. >>> >>> Things that work: >>> -the asciidoctor generation works using mvn (something get generated) >>> >>> Things I'm not sure about or haven't tested yet: >>> -where to place the example source code >>> -haven't tested the gendocs.sh >>> -internal cross references >>> -code block insertions from other files >>> [...] >>> >>> I'm not all that unsatisfied with it, so I'll try to let it grow the next >>> days. >>> >>> Any help and feedback welcome, >>> >>> Martin >>> >>>> Am 03.11.2014 um 13:20 schrieb Martijn Dashorst >>>> <[email protected]>: >>>> >>>> Currently we generate our awesome reference documentation using gdoc, >>>> which was developed to generate groovy? and grails documentation. >>>> However groovy has migrated to asciidoctor and from what I have heard >>>> grails is following suit. >>>> >>>> As I am familiar with asciidoctor due to work related documentation >>>> efforts I did a trial migration for one chapter of the reference >>>> guide. >>>> >>>> The idea is to make this a module of Wicket (6.x, 7.x and 8.x) and >>>> have the example code actually be runnable as a project and have the >>>> documentation reference (parts of) the example code. This way we can >>>> make sure our documentation and code are in sync and that folks >>>> copy/pasting example code have a decent shot of it working in one go. >>>> >>>> You can find the trial project here: >>>> >>>> https://github.com/dashorst/wicketguide >>>> >>>> And a generated example here: >>>> >>>> http://dashorst.github.io/wicketguide/ >>>> >>>> An example of a document that includes live code: >>>> >>>> https://github.com/dashorst/wicketguide/blob/master/src/main/asciidoc/ajax/ajaxbehaviours.adoc >>>> >>>> The live code that is included: >>>> >>>> https://github.com/dashorst/wicketguide/blob/master/src/main/java/org/apache/wicket/guide/ajax/behavior/HomePage.java >>>> >>>> I know that it is a lot of work to convert documentation, and there >>>> are still some buts and ifs (like how to incorporate this in our site, >>>> have a multi-page html generation, the in the README mentioned include >>>> bug, or how to automate the conversion in a reasonable way). >>>> >>>> I find the idea of executable and executing example code rather >>>> enticing and I'd like to see if more folks see this happening. This >>>> would mean more work than just a plain conversion as we need to get >>>> (most of) the examples in working order (not all examples are intended >>>> to compile, just to show a concept). >>>> >>>> What do you think? >>>> >>>> Martijn >>> >> >> >> >> -- >> Become a Wicket expert, learn from the best: http://wicketinaction.com > -- Become a Wicket expert, learn from the best: http://wicketinaction.com
