On 12/04/2012 10:09, Vincent Hennebert wrote:
Hi Vincent,
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.
Thanks for explaining. Based on the above I agree keeping xdocs seems
overkill. I'm happy to move to markdown if that is the best alternative.
Are there any options?
Thanks,
Chris
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
