+1 regards, gerhard
2011/12/23 Mark Struberg <[email protected]> > Dan, I also like the results Andrew and Aslak had with that for the new > Arquillian page. > > Could you probably provide a skeleton and sample integration which we can > tweak? > > Best would be if you just create a git-clone and provide that on github. > then we play around with it and if it turns out to be good, then we can > just push this branch to ds.asf:master > > wdyt? > > LieGrue, > strub > > > ----- Original Message ----- > > From: Gerhard Petracek <[email protected]> > > To: [email protected] > > Cc: > > Sent: Friday, December 23, 2011 9:20 PM > > Subject: Re: [jira] [Created] (DELTASPIKE-13) Choose documentation > format and tools > > > > hi dan, > > > > i said: >if< there are too many open questions right now,... > > > > we already discussed that we would use as few docbook-tags as possible > (in > > any case). > > however, we are going to commit features quite soon and i would prefer to > > have at least the basic descriptions in the repository from the very > > beginning (instead of just waiting until this topic is resolved). > > > > regards, > > gerhard > > > > > > > > 2011/12/23 Dan Allen <[email protected]> > > > >> On Fri, Dec 23, 2011 at 13:18, Gerhard Petracek > >> <[email protected]>wrote: > >> > >> > if there are too many open questions right now, i would suggest that > > we > >> > start with docbook and evaluate the alternatives within the next > > weeks. > >> > > >> > >> Choosing docbook for this reason seems like just giving up before the > match > >> begins. Jason is absolutely right that docbook is a huge barrier to > open > >> source contributions and totally overkill/bloatware for writing > sentences. > >> Sphinx allows you to do just that, write sentences. No B.S. No special > >> editor. No angled brackets. Just type. It's essentially markdown, or a > >> variant of it [1], put into a scaffolding for a book. > >> > >> The Maven plugin seems very up to date and I really doubt there will be > >> much trouble to get it to run [2]. > >> > >> With Sphinx, you are going to get better docs from day one. Any project > >> should jump at that prospect, given how notorious projects are for > having > >> bad docs. > >> > >> "Sphinx is a tool that makes it easy to create intelligent and > > beautiful > >> documentation" > >> > >> Btw, we aren't necessarily advocating for Sphinx as we are advocating > > for > >> writing docs in plain text. Sphinx just happens to offer the best > >> scaffolding for that purpose. And proven. > >> > >> -Dan > >> > >> [1] > >> > >> > > > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#quick-syntax-overview > >> [2] https://github.com/tomdz/sphinx-maven/blob/master/README.md > >> > >> -- > >> Dan Allen > >> Principal Software Engineer, Red Hat | Author of Seam in Action > >> Registered Linux User #231597 > >> > >> http://www.google.com/profiles/dan.j.allen#about > >> http://mojavelinux.com > >> http://mojavelinux.com/seaminaction > >> > > >
