On 09/04/2012 15:47, Glenn Adams wrote:

Hi Glenn, Clay,

On Mon, Apr 9, 2012 at 6:50 AM, Clay Leeds <the.webmaes...@gmail.com <mailto:the.webmaes...@gmail.com>> wrote:

    On Apr 8, 2012, at 7:21 PM, Glenn Adams <gl...@skynav.com
    <mailto: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

    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.

I too am reluctant to lose the current xdoc format as the current docs are very easy to maintain.

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 <http://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. :)

We have to move off the current documentation publishing method that we have. It is an Apache requirement to move to the CMS based approach by the end of 2012. So it is urgent that someone on the team works on the CMS migration right now. If Clay is unable to continue, then someone else must take over. Hopefully Clay still has some time for this?

My preference would be to find a way that allows us to move to CMS whilst keeping the xdoc source format. If it's not possible to keep the xdoc then I'm happy to accept moving to markdown or whatever works best.

Clay, can you comment on Glenn's suggested approach to keep xdoc and move to CMS? Will that be feasible?




Reply via email to