Yes, we are already planing to use asciidoctor for web-api docs (it was decided on the call today). We are also including spring rest test in that.
I'm not saying it's better than the alternatives, but if its good enough for spring docs.... at least from the web-api standpoint,it should be good enough.... (it also includes self-testing docs etc etc... using spring test mvc) -- Morten Olav Hansen Senior Engineer, DHIS 2 University of Oslo http://www.dhis2.org On Sat, Apr 30, 2016 at 12:15 AM, Jason Pickering < jason.p.picker...@gmail.com> wrote: > I like the "simplicity" of ASCIDOC as well. DocBook is a bit heavy, but > for good reason. With great structure, comes many possibilities, so even if > it is a bit heavy, it works for us right now. I certainly don't think we > should change the main docs at the moment. > > I think it would be good alternative for guides, white papers and other > artifacts which are less structured than our current manual, and more stand > alone. > > When we reach that point, which I think is not right now, it will be easy > enough to convert from a highly structured format like DocBook, to > something like AsciiDoc, although, I think we should carefully consider the > level of effort we have put into it. Although a lot of project are jumping > on these newer formats, I still aspire to raise the docs to the level of > Postgres, which has stuck with SGML/Docbook. > > One thing I would like to challenge you on Lars, would be to include > AsciiDoc or similar markup in the application itself. I think it could be > very useful for "internal documentation", for data elements, indicators, > validation rules, SQL views and even textual data elements. Right now, we > only support text, but including support for marking up these (meta)data > elements could be very useful, and help implementers to document their own > system, through the system itself. > > Regards, > Jason > > > On Fri, Apr 29, 2016 at 7:00 PM, Bob Jolliffe <bobjolli...@gmail.com> > wrote: > >> Yes I noticed asciidoc is also part of O'Reilly's new html5 based >> toolchain, htmlbook. In earlier discussions with Jason I figured that >> it would make sense to move maybe a year or so down the line. For the >> moment docbook5 seems to be working ok. >> >> Currently there aren't good open source tools for doing the pdf >> generation (from html5+css3) but they are coming. Tools like prince >> (http://www.princexml.com/) work well but are pricey. Though you can >> use it for non-commercial purposes if you don't mind the prince logo >> you get stuck on your document. I've tried it on the o'reilly >> htmlbook output and it does work :-) >> >> I'm sure the open source convertors are on the horizon. >> >> >> On 29 April 2016 at 18:49, Lars Helge Øverland <l...@dhis2.org> wrote: >> > Seems asciidoc and asciidoctor are getting traction, Spring is using it >> now >> > for guides: >> > >> > >> https://spring.io/blog/2013/12/13/spring-s-getting-started-guides-migrated-to-asciidoctor >> > >> > Seems like something to consider if we want to move to a more >> light-weight >> > alternative than docbook. It lets you generate nice html5 layouts with >> menus >> > like these: >> > >> > >> http://docs.spring.io/spring-restdocs/docs/1.0.x/reference/html5/#documenting-your-api >> > >> > http://infinispan.org/docs/8.2.x/user_guide/user_guide.html >> > >> > >> > -- >> > Lars Helge Øverland >> > Lead developer, DHIS 2 >> > University of Oslo >> > Skype: larshelgeoverland >> > http://www.dhis2.org >> > >> > >> > _______________________________________________ >> > Mailing list: https://launchpad.net/~dhis2-documenters >> > Post to : dhis2-documenters@lists.launchpad.net >> > Unsubscribe : https://launchpad.net/~dhis2-documenters >> > More help : https://help.launchpad.net/ListHelp >> > >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~dhis2-documenters >> Post to : dhis2-documenters@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~dhis2-documenters >> More help : https://help.launchpad.net/ListHelp >> > > > > -- > Jason P. Pickering > email: jason.p.picker...@gmail.com > tel:+46764147049 > > _______________________________________________ > Mailing list: https://launchpad.net/~dhis2-documenters > Post to : dhis2-documenters@lists.launchpad.net > Unsubscribe : https://launchpad.net/~dhis2-documenters > More help : https://help.launchpad.net/ListHelp > >
_______________________________________________ Mailing list: https://launchpad.net/~dhis2-documenters Post to : dhis2-documenters@lists.launchpad.net Unsubscribe : https://launchpad.net/~dhis2-documenters More help : https://help.launchpad.net/ListHelp
