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
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.
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?
Thanks,
Chris
Regards,
G.
