Re: on changing fop documentation sources to markdown
On Sat, Apr 21, 2012 at 9:42 AM, Clay Leeds the.webmaes...@gmail.comwrote:
On Apr 20, 2012, at 1:36 AM, Pascal Sancho pascal.san...@takoma.fr
wrote:
But there has to be a better way. Can we, as a start, change the CSS file
xmlgraphics.css so it doesn't have body {color: white;}?
Note that I have to be very patient when editing the (very long)
compliance page directly, since it is rendered directly in the preview
pane. Don't try it if your processor is a little out of age (;-|
[1] http://www.apache.org/dev/cmsref.html#markdown
Thanks again for the assistance!
Clay
I've committed a change to the CSS, which at least makes it black text on
white background (white on white is difficult to read unless you're a
wizard!).
We'll still need to figure out a solution for the coloring and such... We
should be able to come up with some solution... If nothing else, we could
always commit an HTML file, but we need to find a method to make it so the
CMS doesn't replace it or something silly...
Hand editing all the lines in that file just doesn't seem efficient!
Re: on changing fop documentation sources to markdown
On Apr 20, 2012, at 1:36 AM, Pascal Sancho pascal.san...@takoma.fr wrote:
Hi,
great job, Clay!
I've looked at the compliance page closer, and it seems that rendering
doesn't support markdown extras (like table or headerid), when it is said
here [1] that such features are enabled for the CMS.
As a workaround, we can insert html markup inside the markdown, I tried it
successfully with the legend table (in the preview pane).
In staging view, there is a CSS issue:
xmlgraphics.css@17 body {color: white;} is taken into acccount,
regardless this rule:
xmlgraphics.css@17 #content {color: #33;}
Wow! Nice work! It's nice to have help on this!
But there has to be a better way. Can we, as a start, change the CSS file
xmlgraphics.css so it doesn't have body {color: white;}?
Note that I have to be very patient when editing the (very long) compliance
page directly, since it is rendered directly in the preview pane. Don't try
it if your processor is a little out of age (;-|
[1] http://www.apache.org/dev/cmsref.html#markdown
Thanks again for the assistance!
Clay
Re: on changing fop documentation sources to markdown
Hi,
great job, Clay!
I've looked at the compliance page closer, and it seems that rendering
doesn't support markdown extras (like table or headerid), when it is
said here [1] that such features are enabled for the CMS.
As a workaround, we can insert html markup inside the markdown, I tried
it successfully with the legend table (in the preview pane).
In staging view, there is a CSS issue:
xmlgraphics.css@17 body {color: white;} is taken into acccount,
regardless this rule:
xmlgraphics.css@17 #content {color: #33;}
Note that I have to be very patient when editing the (very long)
compliance page directly, since it is rendered directly in the preview
pane. Don't try it if your processor is a little out of age (;-|
[1] http://www.apache.org/dev/cmsref.html#markdown
Le 20/04/2012 04:43, The Web Maestro a écrit :
On Thu, Apr 19, 2012 at 12:40 AM, Chris Bowditch
bowditch_ch...@hotmail.com mailto:bowditch_ch...@hotmail.com wrote:
On 19/04/2012 02:02, Clay Leeds wrote:
I replaced the logo for all sites a month or so ago.
Thanks Clay - I can see the new logo fine. I was referring to the
TM characters in the text. I can see it everywhere except the top
level XML Graphics home page, which is a page I definitely changed.
Sorry, thought you were talking about the graphic. I fixed the text.
BTW, it's pretty easy for anyone to edit with the CMS now. Here's the
Apache CMS Reference:
http://www.apache.org/dev/cmsref.html
That will give you a bookmarklet you can use to edit any STAGING page:
Here's your starting point for the XML Graphics Staging site:
http://xmlgraphics.staging.apache.org/
Once we're good to go, anyone will also be able to start editing the
markdown files themselves...
--
Pascal
Re: on changing fop documentation sources to markdown
On 19/04/2012 02:02, Clay Leeds wrote: I replaced the logo for all sites a month or so ago. Thanks Clay - I can see the new logo fine. I was referring to the TM characters in the text. I can see it everywhere except the top level XML Graphics home page, which is a page I definitely changed. I'm not at a place I can publish, but if someone can publish the PRODUCTION sites, the logo will show up (be sure to clear cache!). Cache definitely cleared. I know its only 1 page, but since its the top page it's important that it adheres to Apache Branding rules. Thanks, Chris Clay My religion is simple. My religion is kindness. - HH The Dalai Lama of Tibet On Apr 18, 2012, at 7:09 AM, Chris Bowditchbowditch_ch...@hotmail.com wrote: On 18/04/2012 13:52, Clay Leeds wrote: On Apr 18, 2012, at 5:12 AM, Chris Bowditchbowditch_ch...@hotmail.com wrote: On 18/04/2012 07:24, The Web Maestro wrote: Hi Clay, I added the logo (in GIF, JPG, PNG SVG formats... ;-) Thanks, but I don't yet see it on the staging website. Is there a delay before that appears? Hi Clay, Strange. The new logo showed up when I refreshed it. Perhaps it's your cache? Try loading only the logo. Yes you are right. It was my browser cache. I can now see the updated logo. Sponsorship Thanks were already there. License is on the Legal page, which is there, but I've added it to the sidebar as well, along with the Security page. ;-) Thanks. I can now see the 4 required links. I also got the Compliance table working. Unfortunately, the CMS is stripping the 'class=ForrestTable', so the coloring is White-On-White (but if you select the text, you'll see the content and layout is there). As for the navigation menu, I'd like it to collapse most of the links, except the section you're in. Anyone have a favorite jQuery menu they like for this? If not, I'll see about finding one... All the TM logos are missing from the content and headers though. It took me quite some time to add them to all the pages. Will you be able to re-sync the content with the latest xdocs as it would take quite some time to re-apply them and I want to tell the board that FOP, Commons and XML Graphics sites are now brand compliant in the upcoming report. The current LIVE site has it, so we should be good informing the board it's there, no? Weird. When I added the content, I did an `svn up` to ensure it was recent content. I'm sure I'll have to re-synch, anyway, so we'll see. I wish it were a caching thing! I can see the TM logos in most of the content after clearing the cache. Just the XML Graphics top page doesn't appear to have them now. Thanks, Chris Thanks, Chris - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
Re: on changing fop documentation sources to markdown
On Thu, Apr 19, 2012 at 12:40 AM, Chris Bowditch bowditch_ch...@hotmail.com wrote: On 19/04/2012 02:02, Clay Leeds wrote: I replaced the logo for all sites a month or so ago. Thanks Clay - I can see the new logo fine. I was referring to the TM characters in the text. I can see it everywhere except the top level XML Graphics home page, which is a page I definitely changed. Sorry, thought you were talking about the graphic. I fixed the text. BTW, it's pretty easy for anyone to edit with the CMS now. Here's the Apache CMS Reference: http://www.apache.org/dev/cmsref.html That will give you a bookmarklet you can use to edit any STAGING page: Here's your starting point for the XML Graphics Staging site: http://xmlgraphics.staging.apache.org/ Once we're good to go, anyone will also be able to start editing the markdown files themselves... Cheers! Clay
Re: on changing fop documentation sources to markdown
On Tue, Apr 17, 2012 at 7:52 AM, Chris Bowditch bowditch_ch...@hotmail.comwrote: BACKGROUND: We are discussing moving XML Graphics web site to ASF-CMS. You can see progress here: http://xmlgraphics.staging.**apache.org/http://xmlgraphics.staging.apache.org/ I realize its work in progress but it appears like you used an old snapshot without the TM marks in the content or the new logo that you designed. Also the links need to include License, Sponsorship, Thanks and Security as per the branding guidelines. This content is now live on the main site, so I guess you just started with a snapshot from a few weeks ago? I added the logo (in GIF, JPG, PNG SVG formats... ;-) Sponsorship Thanks were already there. License is on the Legal page, which is there, but I've added it to the sidebar as well, along with the Security page. ;-) I also got the Compliance table working. Unfortunately, the CMS is stripping the 'class=ForrestTable', so the coloring is White-On-White (but if you select the text, you'll see the content and layout is there). As for the navigation menu, I'd like it to collapse most of the links, except the section you're in. Anyone have a favorite jQuery menu they like for this? If not, I'll see about finding one... Clay
Re: on changing fop documentation sources to markdown
On 18/04/2012 07:24, The Web Maestro wrote: Hi Clay, On Tue, Apr 17, 2012 at 7:52 AM, Chris Bowditch bowditch_ch...@hotmail.com mailto:bowditch_ch...@hotmail.com wrote: BACKGROUND: We are discussing moving XML Graphics web site to ASF-CMS. You can see progress here: http://xmlgraphics.staging.apache.org/ I realize its work in progress but it appears like you used an old snapshot without the TM marks in the content or the new logo that you designed. Also the links need to include License, Sponsorship, Thanks and Security as per the branding guidelines. This content is now live on the main site, so I guess you just started with a snapshot from a few weeks ago? I added the logo (in GIF, JPG, PNG SVG formats... ;-) Thanks, but I don't yet see it on the staging website. Is there a delay before that appears? Sponsorship Thanks were already there. License is on the Legal page, which is there, but I've added it to the sidebar as well, along with the Security page. ;-) Thanks. I can now see the 4 required links. I also got the Compliance table working. Unfortunately, the CMS is stripping the 'class=ForrestTable', so the coloring is White-On-White (but if you select the text, you'll see the content and layout is there). As for the navigation menu, I'd like it to collapse most of the links, except the section you're in. Anyone have a favorite jQuery menu they like for this? If not, I'll see about finding one... All the TM logos are missing from the content and headers though. It took me quite some time to add them to all the pages. Will you be able to re-sync the content with the latest xdocs as it would take quite some time to re-apply them and I want to tell the board that FOP, Commons and XML Graphics sites are now brand compliant in the upcoming report. Thanks, Chris Clay
Re: on changing fop documentation sources to markdown
On Apr 18, 2012, at 5:12 AM, Chris Bowditch bowditch_ch...@hotmail.com wrote: On 18/04/2012 07:24, The Web Maestro wrote: Hi Clay, I added the logo (in GIF, JPG, PNG SVG formats... ;-) Thanks, but I don't yet see it on the staging website. Is there a delay before that appears? Strange. The new logo showed up when I refreshed it. Perhaps it's your cache? Try loading only the logo. Sponsorship Thanks were already there. License is on the Legal page, which is there, but I've added it to the sidebar as well, along with the Security page. ;-) Thanks. I can now see the 4 required links. I also got the Compliance table working. Unfortunately, the CMS is stripping the 'class=ForrestTable', so the coloring is White-On-White (but if you select the text, you'll see the content and layout is there). As for the navigation menu, I'd like it to collapse most of the links, except the section you're in. Anyone have a favorite jQuery menu they like for this? If not, I'll see about finding one... All the TM logos are missing from the content and headers though. It took me quite some time to add them to all the pages. Will you be able to re-sync the content with the latest xdocs as it would take quite some time to re-apply them and I want to tell the board that FOP, Commons and XML Graphics sites are now brand compliant in the upcoming report. The current LIVE site has it, so we should be good informing the board it's there, no? Weird. When I added the content, I did an `svn up` to ensure it was recent content. I'm sure I'll have to re-synch, anyway, so we'll see. I wish it were a caching thing! Thanks, Chris
Re: on changing fop documentation sources to markdown
On 18/04/2012 13:52, Clay Leeds wrote: On Apr 18, 2012, at 5:12 AM, Chris Bowditchbowditch_ch...@hotmail.com wrote: On 18/04/2012 07:24, The Web Maestro wrote: Hi Clay, I added the logo (in GIF, JPG, PNG SVG formats... ;-) Thanks, but I don't yet see it on the staging website. Is there a delay before that appears? Hi Clay, Strange. The new logo showed up when I refreshed it. Perhaps it's your cache? Try loading only the logo. Yes you are right. It was my browser cache. I can now see the updated logo. Sponsorship Thanks were already there. License is on the Legal page, which is there, but I've added it to the sidebar as well, along with the Security page. ;-) Thanks. I can now see the 4 required links. I also got the Compliance table working. Unfortunately, the CMS is stripping the 'class=ForrestTable', so the coloring is White-On-White (but if you select the text, you'll see the content and layout is there). As for the navigation menu, I'd like it to collapse most of the links, except the section you're in. Anyone have a favorite jQuery menu they like for this? If not, I'll see about finding one... All the TM logos are missing from the content and headers though. It took me quite some time to add them to all the pages. Will you be able to re-sync the content with the latest xdocs as it would take quite some time to re-apply them and I want to tell the board that FOP, Commons and XML Graphics sites are now brand compliant in the upcoming report. The current LIVE site has it, so we should be good informing the board it's there, no? Weird. When I added the content, I did an `svn up` to ensure it was recent content. I'm sure I'll have to re-synch, anyway, so we'll see. I wish it were a caching thing! I can see the TM logos in most of the content after clearing the cache. Just the XML Graphics top page doesn't appear to have them now. Thanks, Chris Thanks, Chris
Re: on changing fop documentation sources to markdown
I replaced the logo for all sites a month or so ago. I'm not at a place I can publish, but if someone can publish the PRODUCTION sites, the logo will show up (be sure to clear cache!). Clay My religion is simple. My religion is kindness. - HH The Dalai Lama of Tibet On Apr 18, 2012, at 7:09 AM, Chris Bowditch bowditch_ch...@hotmail.com wrote: On 18/04/2012 13:52, Clay Leeds wrote: On Apr 18, 2012, at 5:12 AM, Chris Bowditchbowditch_ch...@hotmail.com wrote: On 18/04/2012 07:24, The Web Maestro wrote: Hi Clay, I added the logo (in GIF, JPG, PNG SVG formats... ;-) Thanks, but I don't yet see it on the staging website. Is there a delay before that appears? Hi Clay, Strange. The new logo showed up when I refreshed it. Perhaps it's your cache? Try loading only the logo. Yes you are right. It was my browser cache. I can now see the updated logo. Sponsorship Thanks were already there. License is on the Legal page, which is there, but I've added it to the sidebar as well, along with the Security page. ;-) Thanks. I can now see the 4 required links. I also got the Compliance table working. Unfortunately, the CMS is stripping the 'class=ForrestTable', so the coloring is White-On-White (but if you select the text, you'll see the content and layout is there). As for the navigation menu, I'd like it to collapse most of the links, except the section you're in. Anyone have a favorite jQuery menu they like for this? If not, I'll see about finding one... All the TM logos are missing from the content and headers though. It took me quite some time to add them to all the pages. Will you be able to re-sync the content with the latest xdocs as it would take quite some time to re-apply them and I want to tell the board that FOP, Commons and XML Graphics sites are now brand compliant in the upcoming report. The current LIVE site has it, so we should be good informing the board it's there, no? Weird. When I added the content, I did an `svn up` to ensure it was recent content. I'm sure I'll have to re-synch, anyway, so we'll see. I wish it were a caching thing! I can see the TM logos in most of the content after clearing the cache. Just the XML Graphics top page doesn't appear to have them now. Thanks, Chris Thanks, Chris
Re: on changing fop documentation sources to markdown
On 15/04/2012 19:52, The Web Maestro wrote: I just added most of the nav for FOP Development (0.95, 1.0, trunk/ and 'dev'): Hi Clay, http://xmlgraphics.staging.apache.org/ As mentioned, there are likely missing things (like java-docs, download.cgi, Batik's DEMO, etc.)... It'd be great if folks could take a look... I haven't figured out how to add other content, but It Might Just Work(tm) if weupload it there via SVN... Many thanks for working on this. Come to think of it, we should probably move this to gene...@xmlgraphics.apache.org mailto:gene...@xmlgraphics.apache.org. Or is there a better mailing list? I'll refrain from sending to other lists, until we figure out where it should go. Any ideas where this discussion should move, since it entails changes to all XML Graphics Project web docs? Yes this discussion should move to general@ as it will affect all sub projects of XML Graphics. Thanks, Chris Kind regards, Clay Leeds -- the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com - http://ourlil.com/ My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet On Sat, Apr 14, 2012 at 11:53 PM, The Web Maestro the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com wrote: I've updated the docs a bit, and gotten much (but not all!) of the FOP, Batik Commons content into the CMS... We're still missing an adequate navigation system, so I did a preliminary job of getting a few links in the sidenav, but it's incomplete and ugly as sin. We'll need to build a mechanism to hide (collapse?) non-relevant links, but that shouldn't be too hard. We also need to figure out java-docs, download.cgi, and perhaps some other issues... Without further ado: http://xmlgraphics.staging.apache.org/ Kind regards, Clay Leeds -- the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com - http://ourlil.com/ My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet On Thu, Apr 12, 2012 at 10:03 PM, Clay Leeds the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com wrote: On Apr 12, 2012, at 6:41 AM, Glenn Adams gl...@skynav.com mailto:gl...@skynav.com wrote: Agreed that removing forrest dependency is desirable. However, presumably the current xdocs would need to be converted to MD, in which case someone will need to construct an XSLT to do so. That begs the question of whether it would be necessary (at this time) to convert the source format to MD, or if an additional step in the CMS based process could merely perform that step automatically. If so, then it should not be necessary to change the authoring format at this time. It could be done as a separate step later. I am using Forrest 0.8 w markdown plugin. Conversion could be scripted, but that would negate the benefit of the CMS. What I don't know yet is what we will lose from the conversion to MD in terms of ability to markup our source docs. Clearly, MD is not as semantically or syntactically rich as an XML based source. But do we lose anything of consequence? I don't know yet. One thing we may lose if we don't convert to MD is the ability to use CMS in-page editing. So that is a consideration. Perhaps that option is sufficient to justify other potential negatives in converting. G. One of my goals, was to see some discussion in the DEVers, before I complete the task of converting the docs. The MarkDown format is not nearly as semantic as xdoc, but it serves a different purpose. It'll take some time, and I'm still prepared to take it on. But I was hoping for some discussion ;-)
Re: on changing fop documentation sources to markdown
NOTE: Moving discussion to general@. Please make all further responses to general@. BACKGROUND: We are discussing moving XML Graphics web site to ASF-CMS. You can see progress here: http://xmlgraphics.staging.apache.org/ ToDo: - Lots. - Style templating work - Non-HTML content (figure out how to handle java-docs, download.cgi, demo stuff, etc.--might not be too difficult, just a matter of committing to CMS content/ dirs?) Done: - most HTML content Clay My religion is simple. My religion is kindness. - HH The Dalai Lama of Tibet On Apr 17, 2012, at 1:19 AM, Chris Bowditch bowditch_ch...@hotmail.com wrote: On 15/04/2012 19:52, The Web Maestro wrote: I just added most of the nav for FOP Development (0.95, 1.0, trunk/ and 'dev'): Hi Clay, http://xmlgraphics.staging.apache.org/ As mentioned, there are likely missing things (like java-docs, download.cgi, Batik's DEMO, etc.)... It'd be great if folks could take a look... I haven't figured out how to add other content, but It Might Just Work(tm) if weupload it there via SVN... Many thanks for working on this. Come to think of it, we should probably move this to gene...@xmlgraphics.apache.org mailto:gene...@xmlgraphics.apache.org. Or is there a better mailing list? I'll refrain from sending to other lists, until we figure out where it should go. Any ideas where this discussion should move, since it entails changes to all XML Graphics Project web docs? Yes this discussion should move to general@ as it will affect all sub projects of XML Graphics. Thanks, Chris Kind regards, Clay Leeds -- the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com - http://ourlil.com/ My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet On Sat, Apr 14, 2012 at 11:53 PM, The Web Maestro the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com wrote: I've updated the docs a bit, and gotten much (but not all!) of the FOP, Batik Commons content into the CMS... We're still missing an adequate navigation system, so I did a preliminary job of getting a few links in the sidenav, but it's incomplete and ugly as sin. We'll need to build a mechanism to hide (collapse?) non-relevant links, but that shouldn't be too hard. We also need to figure out java-docs, download.cgi, and perhaps some other issues... Without further ado: http://xmlgraphics.staging.apache.org/ Kind regards, Clay Leeds -- the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com - http://ourlil.com/ My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet On Thu, Apr 12, 2012 at 10:03 PM, Clay Leeds the.webmaes...@gmail.com mailto:the.webmaes...@gmail.com wrote: On Apr 12, 2012, at 6:41 AM, Glenn Adams gl...@skynav.com mailto:gl...@skynav.com wrote: Agreed that removing forrest dependency is desirable. However, presumably the current xdocs would need to be converted to MD, in which case someone will need to construct an XSLT to do so. That begs the question of whether it would be necessary (at this time) to convert the source format to MD, or if an additional step in the CMS based process could merely perform that step automatically. If so, then it should not be necessary to change the authoring format at this time. It could be done as a separate step later. I am using Forrest 0.8 w markdown plugin. Conversion could be scripted, but that would negate the benefit of the CMS. What I don't know yet is what we will lose from the conversion to MD in terms of ability to markup our source docs. Clearly, MD is not as semantically or syntactically rich as an XML based source. But do we lose anything of consequence? I don't know yet. One thing we may lose if we don't convert to MD is the ability to use CMS in-page editing. So that is a consideration. Perhaps that option is sufficient to justify other potential negatives in converting. G. One of my goals, was to see some discussion in the DEVers, before I complete the task of converting the docs. The MarkDown format is not nearly as semantic as xdoc, but it serves a different purpose. It'll take some time, and I'm still prepared to take it on. But I was hoping for some discussion ;-)
Re: on changing fop documentation sources to markdown
On 17/04/2012 14:59, Clay Leeds wrote: NOTE: Moving discussion to general@. Please make all further responses to general@. Hi Clay, Thanks for moving to general@ BACKGROUND: We are discussing moving XML Graphics web site to ASF-CMS. You can see progress here: http://xmlgraphics.staging.apache.org/ I realize its work in progress but it appears like you used an old snapshot without the TM marks in the content or the new logo that you designed. Also the links need to include License, Sponsorship, Thanks and Security as per the branding guidelines. This content is now live on the main site, so I guess you just started with a snapshot from a few weeks ago? ToDo: - Lots. - Style templating work - Non-HTML content (figure out how to handle java-docs, download.cgi, demo stuff, etc.--might not be too difficult, just a matter of committing to CMS content/ dirs?) Done: - most HTML content Thanks, Chris Clay My religion is simple. My religion is kindness. - HH The Dalai Lama of Tibet On Apr 17, 2012, at 1:19 AM, Chris Bowditchbowditch_ch...@hotmail.com wrote: On 15/04/2012 19:52, The Web Maestro wrote: I just added most of the nav for FOP Development (0.95, 1.0, trunk/ and 'dev'): Hi Clay, http://xmlgraphics.staging.apache.org/ As mentioned, there are likely missing things (like java-docs, download.cgi, Batik's DEMO, etc.)... It'd be great if folks could take a look... I haven't figured out how to add other content, but It Might Just Work(tm) if weupload it there via SVN... Many thanks for working on this. Come to think of it, we should probably move this to gene...@xmlgraphics.apache.orgmailto:gene...@xmlgraphics.apache.org. Or is there a better mailing list? I'll refrain from sending to other lists, until we figure out where it should go. Any ideas where this discussion should move, since it entails changes to all XML Graphics Project web docs? Yes this discussion should move to general@ as it will affect all sub projects of XML Graphics. Thanks, Chris Kind regards, Clay Leeds -- the.webmaes...@gmail.commailto:the.webmaes...@gmail.com -http://ourlil.com/ My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet On Sat, Apr 14, 2012 at 11:53 PM, The Web Maestrothe.webmaes...@gmail.commailto:the.webmaes...@gmail.com wrote: I've updated the docs a bit, and gotten much (but not all!) of the FOP, Batik Commons content into the CMS... We're still missing an adequate navigation system, so I did a preliminary job of getting a few links in the sidenav, but it's incomplete and ugly as sin. We'll need to build a mechanism to hide (collapse?) non-relevant links, but that shouldn't be too hard. We also need to figure out java-docs, download.cgi, and perhaps some other issues... Without further ado: http://xmlgraphics.staging.apache.org/ Kind regards, Clay Leeds -- the.webmaes...@gmail.commailto:the.webmaes...@gmail.com - http://ourlil.com/ My religion is simple. My religion is kindness. - HH The 14th Dalai Lama of Tibet On Thu, Apr 12, 2012 at 10:03 PM, Clay Leeds the.webmaes...@gmail.commailto:the.webmaes...@gmail.com wrote: On Apr 12, 2012, at 6:41 AM, Glenn Adamsgl...@skynav.com mailto:gl...@skynav.com wrote: Agreed that removing forrest dependency is desirable. However, presumably the current xdocs would need to be converted to MD, in which case someone will need to construct an XSLT to do so. That begs the question of whether it would be necessary (at this time) to convert the source format to MD, or if an additional step in the CMS based process could merely perform that step automatically. If so, then it should not be necessary to change the authoring format at this time. It could be done as a separate step later. I am using Forrest 0.8 w markdown plugin. Conversion could be scripted, but that would negate the benefit of the CMS. What I don't know yet is what we will lose from the conversion to MD in terms of ability to markup our source docs. Clearly, MD is not as semantically or syntactically rich as an XML based source. But do we lose anything of consequence? I don't know yet. One thing we may lose if we don't convert to MD is the ability to use CMS in-page editing. So that is a consideration. Perhaps that option is sufficient to justify other potential negatives in converting. G. One of my goals, was to see some discussion in the DEVers, before I complete the task of converting the docs. The MarkDown format is not nearly as semantic as xdoc, but it serves a different purpose. It'll take some time, and I'm still prepared to take it on. But I was hoping for some discussion ;-)
Re: on changing fop documentation sources to markdown
I've updated the docs a bit, and gotten much (but not all!) of the FOP, Batik Commons content into the CMS... We're still missing an adequate navigation system, so I did a preliminary job of getting a few links in the sidenav, but it's incomplete and ugly as sin. We'll need to build a mechanism to hide (collapse?) non-relevant links, but that shouldn't be too hard. We also need to figure out java-docs, download.cgi, and perhaps some other issues... Without further ado: http://xmlgraphics.staging.apache.org/ 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 On Thu, Apr 12, 2012 at 10:03 PM, Clay Leeds the.webmaes...@gmail.comwrote: On Apr 12, 2012, at 6:41 AM, Glenn Adams gl...@skynav.com wrote: Agreed that removing forrest dependency is desirable. However, presumably the current xdocs would need to be converted to MD, in which case someone will need to construct an XSLT to do so. That begs the question of whether it would be necessary (at this time) to convert the source format to MD, or if an additional step in the CMS based process could merely perform that step automatically. If so, then it should not be necessary to change the authoring format at this time. It could be done as a separate step later. I am using Forrest 0.8 w markdown plugin. Conversion could be scripted, but that would negate the benefit of the CMS. What I don't know yet is what we will lose from the conversion to MD in terms of ability to markup our source docs. Clearly, MD is not as semantically or syntactically rich as an XML based source. But do we lose anything of consequence? I don't know yet. One thing we may lose if we don't convert to MD is the ability to use CMS in-page editing. So that is a consideration. Perhaps that option is sufficient to justify other potential negatives in converting. G. One of my goals, was to see some discussion in the DEVers, before I complete the task of converting the docs. The MarkDown format is not nearly as semantic as xdoc, but it serves a different purpose. It'll take some time, and I'm still prepared to take it on. But I was hoping for some discussion ;-)
Re: on changing fop documentation sources to markdown
I just added most of the nav for FOP Development (0.95, 1.0, trunk/ and 'dev'): http://xmlgraphics.staging.apache.org/ As mentioned, there are likely missing things (like java-docs, download.cgi, Batik's DEMO, etc.)... It'd be great if folks could take a look... I haven't figured out how to add other content, but It Might Just Work(tm) if weupload it there via SVN... Come to think of it, we should probably move this to gene...@xmlgraphics.apache.org. Or is there a better mailing list? I'll refrain from sending to other lists, until we figure out where it should go. Any ideas where this discussion should move, since it entails changes to all XML Graphics Project web docs? 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 On Sat, Apr 14, 2012 at 11:53 PM, The Web Maestro the.webmaes...@gmail.comwrote: I've updated the docs a bit, and gotten much (but not all!) of the FOP, Batik Commons content into the CMS... We're still missing an adequate navigation system, so I did a preliminary job of getting a few links in the sidenav, but it's incomplete and ugly as sin. We'll need to build a mechanism to hide (collapse?) non-relevant links, but that shouldn't be too hard. We also need to figure out java-docs, download.cgi, and perhaps some other issues... Without further ado: http://xmlgraphics.staging.apache.org/ 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 On Thu, Apr 12, 2012 at 10:03 PM, Clay Leeds the.webmaes...@gmail.comwrote: On Apr 12, 2012, at 6:41 AM, Glenn Adams gl...@skynav.com wrote: Agreed that removing forrest dependency is desirable. However, presumably the current xdocs would need to be converted to MD, in which case someone will need to construct an XSLT to do so. That begs the question of whether it would be necessary (at this time) to convert the source format to MD, or if an additional step in the CMS based process could merely perform that step automatically. If so, then it should not be necessary to change the authoring format at this time. It could be done as a separate step later. I am using Forrest 0.8 w markdown plugin. Conversion could be scripted, but that would negate the benefit of the CMS. What I don't know yet is what we will lose from the conversion to MD in terms of ability to markup our source docs. Clearly, MD is not as semantically or syntactically rich as an XML based source. But do we lose anything of consequence? I don't know yet. One thing we may lose if we don't convert to MD is the ability to use CMS in-page editing. So that is a consideration. Perhaps that option is sufficient to justify other potential negatives in converting. G. One of my goals, was to see some discussion in the DEVers, before I complete the task of converting the docs. The MarkDown format is not nearly as semantic as xdoc, but it serves a different purpose. It'll take some time, and I'm still prepared to take it on. But I was hoping for some discussion ;-)
Re: on changing fop documentation sources to markdown
On Sun, Apr 15, 2012 at 12:52 PM, The Web Maestro the.webmaes...@gmail.comwrote: I just added most of the nav for FOP Development (0.95, 1.0, trunk/ and 'dev'): http://xmlgraphics.staging.apache.org/ initial comments: - the navigation panel on the left needs to start in a collapsed mode, and remember its settings as you move to sub-projects and their descendants; possibly better would be to limit what is in the navigation panel to the content of each currently selected sub-project or home, while retaining expansion within that set of content; - table formatting is broken, cf. compliance.htmlhttp://xmlgraphics.staging.apache.org/fop/compliance.htmland complexscripts.htmlhttp://xmlgraphics.staging.apache.org/fop/trunk/complexscripts.html - header margins seem strange; h[134] are aligned (on left) but h2 is indented; cf. complexscripts.htmlhttp://xmlgraphics.staging.apache.org/fop/trunk/complexscripts.html also, since you are now in the process of making these changes, what should we do with current site doc updates? i.e., can i continue to commit changes to fop/src/documentation/content/xdocs and you will pick up these changes at some point? or should we hold off on any changes until you have finished?
Re: on changing fop documentation sources to markdown
Thx for the comments Glenn, On Apr 15, 2012, at 12:50 PM, Glenn Adams gl...@skynav.com wrote: initial comments: the navigation panel on the left needs to start in a collapsed mode, and remember its settings as you move to sub-projects and their descendants; possibly better would be to limit what is in the navigation panel to the content of each currently selected sub-project or home, while retaining expansion within that set of content; I'll likely make it collapse everything but the section you are in. I don't think it'll remember state, so much as be aware of where you are. I'm thinking we'll be using jQuery for that but perhaps that'll include state? But I'm open to code additions... ;-) table formatting is broken, cf. compliance.html and complexscripts.html Excellent! Thank you so much for checking up. We might just paste that code in as straight HTML. header margins seem strange; h[134] are aligned (on left) but h2 is indented; cf. complexscripts.html I need to format the page templates and such (the Nav collapse stuff will be a part of that). also, since you are now in the process of making these changes, what should we do with current site doc updates? i.e., can i continue to commit changes to fop/src/documentation/content/xdocs and you will pick up these changes at some point? or should we hold off on any changes until you have finished? I'm not sure. I think we should probably do both. The CMS process is simple enough but I hate the prospect of double work for anyone. We should tag the web content for XML Graphics, FOP, Batik, Commons, so we could have a reference point. Clay
Re: on changing fop documentation sources to markdown
On 09/04/12 15:47, Glenn Adams wrote: On Mon, Apr 9, 2012 at 6:50 AM, Clay Leeds the.webmaes...@gmail.com wrote: On Apr 8, 2012, at 7:21 PM, Glenn Adams 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 pluginhttp://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. 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. 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
Re: on changing fop documentation sources to markdown
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
Re: on changing fop documentation sources to markdown
On Apr 12, 2012, at 6:41 AM, Glenn Adams gl...@skynav.com wrote: Agreed that removing forrest dependency is desirable. However, presumably the current xdocs would need to be converted to MD, in which case someone will need to construct an XSLT to do so. That begs the question of whether it would be necessary (at this time) to convert the source format to MD, or if an additional step in the CMS based process could merely perform that step automatically. If so, then it should not be necessary to change the authoring format at this time. It could be done as a separate step later. I am using Forrest 0.8 w markdown plugin. Conversion could be scripted, but that would negate the benefit of the CMS. What I don't know yet is what we will lose from the conversion to MD in terms of ability to markup our source docs. Clearly, MD is not as semantically or syntactically rich as an XML based source. But do we lose anything of consequence? I don't know yet. One thing we may lose if we don't convert to MD is the ability to use CMS in-page editing. So that is a consideration. Perhaps that option is sufficient to justify other potential negatives in converting. G. One of my goals, was to see some discussion in the DEVers, before I complete the task of converting the docs. The MarkDown format is not nearly as semantic as xdoc, but it serves a different purpose. It'll take some time, and I'm still prepared to take it on. But I was hoping for some discussion ;-)
Re: on changing fop documentation sources to markdown
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.
Re: on changing fop documentation sources to markdown
On Apr 8, 2012, at 7:21 PM, Glenn Adams 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... Clay
Re: on changing fop documentation sources to markdown
On Mon, Apr 9, 2012 at 6:50 AM, Clay Leeds the.webmaes...@gmail.com wrote: On Apr 8, 2012, at 7:21 PM, Glenn Adams 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 pluginhttp://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. 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. :) Regards, G.
Re: on changing fop documentation sources to markdown
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.comwrote: 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
Re: on changing fop documentation sources to markdown
On Sun, Apr 8, 2012 at 7:45 PM, The Web Maestro the.webmaes...@gmail.comwrote: 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. 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?
Re: on changing fop documentation sources to markdown
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). 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. Web Maestro Clay My religion is simple. My religion is kindness. - HH The Dalai Lama of Tibet On Mar 29, 2012, at 9:22 PM, Glenn Adams gl...@skynav.com wrote: If I understand correctly, it is proposed that the FOP doc sources be changed from the current forrest based format (and XML format) to markdown format. If this is correct, then I would like to voice my objection to making this change. I am all for improving FOP documentation and management process; however, I am very leery about changing from an XML source format to a non-XML format, especially one that is as semantically sparse as the markdown format. If a change is to be made, then I would suggest that some XML format remain as the source format, and that markdown be one of a number of possible output (publishing) formats. Overall, I would prefer spending scarce resources on improving the depth, breadth, accuracy, and currency of FOP documentation content, rather than on switching to a different source format, management, or publishing format. I also feel it is very important to continue using FOP documentation to create some output format. I am not prepared to give up our dog food, as that provides one more set of tests on FOP, that would otherwise be missing. Given the sparseness of FOP test coverage, the more content we formally run FOP on, the better. G.
Re: on changing fop documentation sources to markdown
On Fri, Mar 30, 2012 at 7:00 AM, Clay Leeds the.webmaes...@gmail.comwrote: 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. 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. 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. 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. Web Maestro Clay My religion is simple. My religion is kindness. - HH The Dalai Lama of Tibet On Mar 29, 2012, at 9:22 PM, Glenn Adams gl...@skynav.com wrote: If I understand correctly, it is proposed that the FOP doc sources be changed from the current forrest based format (and XML format) to markdown format. If this is correct, then I would like to voice my objection to making this change. I am all for improving FOP documentation and management process; however, I am very leery about changing from an XML source format to a non-XML format, especially one that is as semantically sparse as the markdown format. If a change is to be made, then I would suggest that some XML format remain as the source format, and that markdown be one of a number of possible output (publishing) formats. Overall, I would prefer spending scarce resources on improving the depth, breadth, accuracy, and currency of FOP documentation content, rather than on switching to a different source format, management, or publishing format. I also feel it is very important to continue using FOP documentation to create *some* output format. I am not prepared to give up our dog food, as that provides one more set of tests on FOP, that would otherwise be missing. Given the sparseness of FOP test coverage, the more content we formally run FOP on, the better. G.
Re: on changing fop documentation sources to markdown
On Thu, Mar 29, 2012 at 10:22 PM, Glenn Adams gl...@skynav.com wrote: I also feel it is very important to continue using FOP documentation to create *some* output format. I am not prepared to give up our dog food, as that provides one more set of tests on FOP, that would otherwise be missing. Given the sparseness of FOP test coverage, the more content we formally run FOP on, the better. s/FOP documentation/FOP processing/
