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
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
--
<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