dhis2-documenters team mailing list archive

[Jason Pickering <jason.p.pickering@xxxxxxxxx>]

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 <bobjolliffe@xxxxxxxxx> 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 <lars@xxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~dhis2-documenters
> > More help   : https://help.launchpad.net/ListHelp
> >
>
> _______________________________________________
> Mailing list: https://launchpad.net/~dhis2-documenters
> Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~dhis2-documenters
> More help   : https://help.launchpad.net/ListHelp
>



-- 
Jason P. Pickering
email: jason.p.pickering@xxxxxxxxx
tel:+46764147049