Re: [Dhis2-documenters] asciidoctor

2016-04-29 Thread Morten Olav Hansen 
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 
> 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  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

Re: [Dhis2-documenters] asciidoctor

2016-04-29 Thread Jason Pickering 
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  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  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

Re: [Dhis2-documenters] asciidoctor

2016-04-29 Thread Bob Jolliffe 
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  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

[Dhis2-documenters] asciidoctor

2016-04-29 Thread Lars Helge Øverland 
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