[ https://issues.apache.org/jira/browse/GORA-106?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13266767#comment-13266767 ]
Lewis John McGibbney commented on GORA-106: ------------------------------------------- OK troops, managed to locate some nice time saving resources for us to use to map the legacy forrest xdoc's to markdown. https://svn.apache.org/repos/infra/websites/cms/conversion-utilities/ In particular the xslt written by Sam Ruby https://svn.apache.org/repos/infra/websites/cms/conversion-utilities/anakia2markdown.xslt > Migrate Gora website documentation to Apache CMS > ------------------------------------------------ > > Key: GORA-106 > URL: https://issues.apache.org/jira/browse/GORA-106 > Project: Apache Gora > Issue Type: Improvement > Components: documentation, website > Affects Versions: 0.2 > Reporter: Lewis John McGibbney > Priority: Minor > Fix For: 0.3 > > Attachments: GORA-106.patch > > > I know in the past we've discussed the pro's and con's of the website etc. > However, currently it is a bit of a pain to actually edit/update, build and > commit/publish web content. This is a pain for committers never-mind any > newer Gora users who may just wish to contribute documentation in a > pain/hassle free manner. To illustrate this point I've pasted a conversation > with a pro-Apache CMS ASF guy, whom I asked to look into the Gora > documentation. > {quote} > So, right now, there's no README. > build.xml suggests I use ant, so I did > But no readme means the first ``ant'' will complain > about forrest missing, and I'll say: > Meh. All I wanted is fix a typo. > You have to make it easy for people to contribute, > and you're not! > If you're living in a happy java world, everyone will > have maven, so maven might be the way to go. If 277 > packages is all I need, then so be it, but I'll already > have them installed. > I fired up this email when I started the forrest checkout > it's only done now, after 3:26.53. > Let's see what else breaks :) > AN EXCEPTION! And a backtrace! OH I LOVE THOSE! > BUILD FAILED > /home/igalic/src/asf/gora-site/build.xml:27: Execute failed: > java.io.IOException: Cannot run program "../forrest/bin/forrest" (in > directory "/home/igalic/src/asf/gora-site/author"): java.io.IOException: > error=2, No such file or directory > I touch author, but that doesn't bring me anywhere. > Of course the error is that ant or forrest can't deal with relative paths, > so I run it again as: > igalic@tynix ~/src/asf/gora-site (svn)-[site:1240598] % ant > -Dforrest.home=$( readlink -f ../forrest) > And it fails again, because I didn't build forrest. > By now I wonder if there's a forrest package in Fedora, but > of course there isn't. So let's build forrest. > Which in turn fails because Fedora has some weird > JAVA_HOME pointing to an OpenJDK JRE. > Back to building gora-site. > It builds in 19s and I'm impressed, or hope I have reason to be. > I go in my browser to /home/igalic/src/asf/gora-site/author/build/site > expecting it to break horribly because it's using fixed URLs > but it works. I'm impressed. I'm also impressed by its ugly, > but that's beside the point. It works. And it only took me > 30 minutes to get there. > {quote} > At this stage I let out a long sigh, and thought that it was about time to > open this issue, taking the following into account. > We need to "make it easy" > * for people to contribute a small fix > * for developers to actually write docs > For the latter it should be in a form and a format they are used to, > something that doesn't break their habits. If anyone has the habit of writing > stuff down in notepad then markdown might be ideal... therefore we arrive @ > APACHE CMS. > http://www.apache.org/dev/cms > https://blogs.apache.org/infra/entry/the_asf_cms -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa For more information on JIRA, see: http://www.atlassian.com/software/jira