On Fri, Mar 30, 2012 at 8:55 AM, Glenn Adams <gl...@skynav.com> wrote:

> On Fri, Mar 30, 2012 at 7:00 AM, Clay Leeds <the.webmaes...@gmail.com>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

> 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

[2] HTML2fo

Kind regards,

Clay Leeds
<the.webmaes...@gmail.com> - <http://ourlil.com/>
My religion is simple. My religion is kindness.
- HH The 14th Dalai Lama of Tibet

Reply via email to