On Fri, Mar 30, 2012 at 8:55 AM, Glenn Adams <[email protected]> wrote:
> On Fri, Mar 30, 2012 at 7:00 AM, Clay Leeds <[email protected]>wrote: > >> Makes sense to me. However, I don't think it's necessary to have all >> documentation as such. Perhaps just the Day to day stuff can be translated >> (things that are more likely to change). >> > > There aren't too many docs whose content change on a frequent basis. > Probably only the status.xml content. > > >> That's my current plan, anyway (although I don't yet know how to make >> that happen). Ye olde documentation can remain on xdoc format, or better >> yet get converted to Docbook format. >> > > I certainly have no problem with using MD as the source format for README > and similar content, and would suggest these be converted to MD. I do have > a problem with replacing current XML marked up xdoc sources with MD > sources, though I'd be open to considering this on a case by case basis if > there is good cause. > I understand the desire to retain the XML-based format of the documentation. My primary purpose in doing the migration, was to see if it would be as easy as pie to get the data converted to CMS-based format. I've got more work to do (namely, to get the versioned docs => MarkDown), but it was pretty simple. Updating is *way* more simple than the Forrest-based method. > Regarding XML source formats, right now we have xdoc, and it would take > some effort for probably questionable results to convert to another XML > schema. Plus that would require some additional learning curve or tool > change for authors, so I'm not sure about changing to another XML format. > Thanks to a Forrest 'MarkDown' plugin, it doesn't take too long to convert from xdoc to MarkDown. > For output formats, obviously we need HTML, but if it is useful to output > MD, then I see no problem with someone adding that to the publish build > process. I think it is useful to also continue publishing in PDF output > format as well, if for no other reason than to exercise FOP. Otherwise, I > don't have any strong preferences. For example, I have no love for forrest > if another doc management system will be an improvement. > On the side of losing the FOP part of the docs process, perhaps one possibility for FOP's site eating its own dogfood, would be if we could create a web service to generate PDF from each web page, perhaps using PDFBox[1] or HTML2fo[2], which is a bit stale but useful. So if you can find a way to transition to CMS as the doc management system > while still reusing the existing source formats and output formats (modulo > the above), then I have no objection to that. > 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. [1] Apache PDFBox http://pdfbox.apache.org/ [2] HTML2fo http://html2fo.sourceforge.net/ Kind regards, Clay Leeds -- <[email protected]> - <http://ourlil.com/> My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet
