No, the Markdown documentation "build" doesn't presently integrate with the CAS software build process.
The "makepdf" script <https://github.com/apetro/CAS-Documentation/blob/master/latex/makepdf> build-to-PDF is a heroic shell script that relies on LaTeX, Pandoc, and XeTeX. It presently works for me on Ubuntu producing the PDF I linked -- I don't think it's cross-platform but I haven't tried. It's not triggered from Maven and it's not implemented in Java. The Markdown route involves more pain in getting to successful scripts to building to documentation deliverable artifacts. The upsides are in ease of authoring and reading the source of the documentation. Part of the pitch of Markdown is that the source of Markdown is itself readable <https://raw.github.com/apetro/CAS-Documentation/master/en/07-services-management/07-chapter07.markdown>. Folks won't be that unhappy reading Markdown -- it's mostly the plaintext conventions that we'd use if the documentation were solely plaintext files under source control and there were no attempt to build it to anything else at all. Philosophically, building from that source is all bonus. In practice, building from the source is actually pretty important to get to a polished, marketable, meets-due-diligence-sanity-test review documentation. That current "makepdfs" script is concerning, but it already mostly works. Presumably images would work better if scaled down, and Pro Git is doing something entirely different to include images, needs some followup to figure that out. Anyway, the current state of the build process is that DocBook is a lot more attractive -- there's Maven tooling for building DocBook, but presently no Maven tooling for building Markdown documentation. The DocBook build process builds chunked and whole HTML as well as a PDF, whereas the Markdown build process only builds a PDF so far (Pro Git also builds eBooks -- .mobi, e.g., so presumably that's in reach too.) I'm not sure what Pro Git is doing to go from the Markdown to the website representation, but there was mention of Jekyll which if I understand correctly is a tool for building websites from Markdown. GitHub itself also has a "Pages" feature that basically lets you have a website managed in git and presented on github. It's mostly static but supports generation from Markdown. So there might be a path to building from Markdown documentation source to an arrangement of Markdown and other configuration that looks good on GitHub's website hosting, and then have a process to build and push that periodically. Then we'd have website, PDF, and source. Certainly don't have all the answers yet. Both the DocBook and the Markdown examples are exercises in discovering what the problems are going to be and how hard they're going to be to work through. But if we can figure out which looks more promising, then that can focus efforts on that working through. Andrew On 09/14/2011 08:42 AM, Scott Battaglia wrote: > I'm all for making our lives easier, and if Markdown will accomplish > that, +1 > > Does it integrate well with our build process? > > Cheers, > Scott > > On Tue, Sep 13, 2011 at 5:25 PM, Andrew Petro <[email protected] > <mailto:[email protected]>> wrote: > > Folks, > > DocBook continues to have potential, but documenting XML in XML > gets rough fast. Bill Thompson suggested a second look at Pro Git > <https://github.com/progit/progit> for inspiration. It's a book > <http://progit.org/book/> about Git written in Markdown > <http://daringfireball.net/projects/markdown/>. > > Pro Git proves that it's possible to author and manage > book-looking documentation in Markdown. > > Here's a stab at porting > <https://github.com/apetro/CAS-Documentation> all of the > DocBookified CAS manual documentation > <https://github.com/Jasig/cas/tree/master/cas-server-documentation> over > to Markdown and the PDF generated from that source > <https://github.com/downloads/apetro/CAS-Documentation/casmanual.en.pdf>. > > GitHub's built-in Markdown support is also nice. This > > <https://github.com/apetro/CAS-Documentation/blob/master/en/07-services-management/07-chapter07.markdown> > has pleasant automatic formatting absent here > > <https://github.com/Jasig/cas/blob/master/cas-server-documentation/src/docbkx/services-management.xml>. > > But even without cute Github tricks, I'm concerned that, as > source, XML looks like this in Docbook source XML: > > <programlisting> > <sec:user-service id="userDetailsService"> > <sec:user name="some_trusted_username" > password="notused" > authorities="ROLE_ADMIN" /> > <sec:user name="another_trusted_username" > password="notused" > authorities="ROLE_ADMIN" /> > </sec:user-service> > </programlisting> > > Contrastingly, it looks like this in Markdown: > > <sec:user-service id="userDetailsService"> > <sec:user name="some_trusted_username" password="notused" > authorities="ROLE_ADMIN" /> > <sec:user name="another_trusted_username" password="notused" > authorities="ROLE_ADMIN" /> > </sec:user-service> > > It's a lot more pleasant to read and write the source of the > documentation in the latter. > > > So, what problems are we trying to solve with a documentation reboot: > > 1) Produce and maintain documentation specific to specific > versions / branches of CAS server development. Less with the three > different ways of doing everything depending on what version we're > talking about, and more with documentation maintained in source > control with the code doing its best to document that branch of > the code. Using source control should help make merging / diffing > across branches of documentation feasible. > > 2) Separate the formal part-of-the-product documentation from the > less-formal community-contributed documentation. There have been > good contributions in the wiki and lots of sharing -- and that's a > good thing. That's what wikis are for. But it's a bit of a mess > and it's hard to get a handle on, what's the documentation of the > product that's being collaboratively developed in the course of > the product development process, vs what's a great external > contribution that isn't documenting CAS-as-product. > > 3) Yet, keep barrier to entry to documentation contribution low. > That the documentation's in source control rather than in > Confluence shouldn't mean that only committers ever write > documentation. Au contraire, tracking in source control via > github should welcome forks and pull requests and so forth. > > > Given that, I figure Markdown is a more promising direction. > It's just an easier format for authoring, not having to escape > XML, and the Github support means that you can fork the repo, edit > a page *in your web browser*, and post a pull request to get your > change back into the blessed repo, so github's attempt to mostly > render the Markdown is adding quite a bit of value. > > > The Markdown documentation prototype isn't perfect, just as the > DocBook prototype isn't perfect either. In particular, image > handling looks problematic, and the borrowed-from-pro-git process > for producing a PDF is pretty heroic. On the other hand, images > in DocBook aren't that much fun either. But since Pro Git is > successfully working through this pain, I expect CAS can work > through this too -- and it seems wiser to accept pain in > implementing the post-authoring automation in order to get lower > barrier to entry to edit the documentation. > > > > All that said, format isn't the most important thing here. In > principle we could succeed with Confluence. Or DocBook. Or > Markdown. By far the most important factor is, what are CAS > developers willing to work on? All of the value is in the content. > > So, what looks promising? Which direction to go forward with? > > Andrew > > > > > On 08/31/2011 09:43 AM, Andrew Petro wrote: >> Folks, >> >> I've some incremental progress on the rebirth of the more-formal >> CAS server manual documentation as DocBook. >> >> Blog post with files posted >> >> <http://www.unicon.net/content/early-progress-new-docbookified-jasig-cas-server-manual> >> thereby avoiding sending attachments to list. >> >> It clearly needs a lot more work, but is roughly follows the >> outline of and slurps in the content from Marvin's new user >> manual outline <https://wiki.jasig.org/display/CASUM/User+Manual> >> and partially resolves the image inclusion issues that were >> blocking this effort as of the Jasig conference. >> >> >> Feedback and collaboration welcome. >> >> Andrew >> >> >> -- >> You are currently subscribed [email protected] >> <mailto:[email protected]> as:[email protected] >> <mailto:[email protected]> >> To unsubscribe, change settings or access archives, >> seehttp://www.ja-sig.org/wiki/display/JSG/cas-dev > > -- > You are currently subscribed [email protected] > <mailto:[email protected]> as:[email protected] > <mailto:[email protected]> > > > To unsubscribe, change settings or access archives, > seehttp://www.ja-sig.org/wiki/display/JSG/cas-dev > > > -- > You are currently subscribed [email protected] > <mailto:[email protected]> as: [email protected] > To unsubscribe, change settings or access archives, see > http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev
