On 09/04/12 15:47, Glenn Adams wrote: > On Mon, Apr 9, 2012 at 6:50 AM, Clay Leeds <the.webmaes...@gmail.com> wrote: > >> On Apr 8, 2012, at 7:21 PM, Glenn Adams <gl...@skynav.com> wrote: >> >> Yes, we'd lose the XML-based nature of the documentation. That's a fairly >>> large loss, but I don't know if that's a showstopper, considering the >>> benefits of having CMS-based documentation. >>> >> >> What prevents you from using the existing xdoc format as source, then >> using an XSLT to map to MD whence it can be imported into / processed by >> the CMS. Or can you incorporate this translation process into the CMS? >> >> >> Nothing prevents, but the goal is in this exercise is to minimize launch >> preparation time. ;-) >> >> If we continue to use xdoc, the CMS is skipped. It's certainly possible, >> but... >> > > Could you not use the "dynamic content" approach indicated by > http://www.apache.org/dev/cms.html#dynamic-content? For example, use > buildbot to run the forrest markdown > plugin<http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.output.Markdown/>. > Or > use an External Build <http://www.apache.org/dev/cms.html#external>? > > My main issue is switching our source format for FOP docs from XML to MD. > I'm not comfortable with making this change. However, if my position is a > minority among FOP committers, I will defer to the majority.
My preference is to keep things as simple as possible. If keeping the docs in xdoc format complicates the publishing process, then I’m not in favour of it. In particular, I’d like to remove the dependency on Forrest. Publishing with Forrest is too heavy and involves too many manual steps. Also, customizing the output implies to get your hands dirty in Forrest’s internals, and given the status of Forrest I don’t think it’s worth the investment. I think the Markdown approach should fully fulfil our goal to have the documentation up-to-date and easily published on a modern-looking website. The only interest of keeping the xdoc format is to create some PDF output, but I question the interest of it. As I’ve already mentioned the current output looks terrible and doesn’t do any honour to FOP. Even if we were able to improve the look, I don’t think the content itself is suitable for a print output (think book). Converting every page to a PDF document like can currently be done seems useless to me. It would be more useful to aggregate a whole tab (for example, all the documentation for version 1.0) into one document laid out like a book with a TOC and everything. However, doing this requires a significant amount of work that I don’t know if anybody is prepared to do. And book documents are not the area where FOP excels anyway, so having a really good-looking output may involve too much manual tweaking. And I’m not sure what that brings us in terms of testing if there is no automatic way to check to outputs. Therefore, I think the potential benefits of keeping the xdoc format doesn’t justify the loss of convenience in updating the website. > Again, I don't particularly see a problem that needs to be solved with > switching to CMS. True, publishing FOP site docs is presently a little > clunky, but I was able to figure it out (from scratch) in a few hours, and > can reproduce it at will. Of course, if people.apache.org is really going > away in 2012, then I agree something has to be done. > > If you have cycles to spend on FOP documentation, I would prefer you spend > it on updating the site and wiki docs, which are, in many cases, quite out > of date. However, how you use your time is your call. :) I see that Clay has done some work in styling the experimental website and it’s already looking better than what we currently have. Keep up the good work Clay! > Regards, > G. Vincent
