* Easy & simple syntax that is 'graphically' identical to what you see when 'compiled' (which is not the case for XDOC) * 100% integration with Maven * Ease of debugging, you can run mvn site:run and edit pages on the fly and see how they look * I don't know of any APT wysiwyg editor, IMO the syntax is quite simple to worry about one.
because of this i'd say it is good enough. thxs. Alejandro On Tue, Oct 11, 2011 at 2:00 PM, Santhosh Srinivasan <[email protected]> wrote: > Mohammad and Params are sharing their early feedback on the tool. Looking at > the bigger picture, the question centers around the following: > > What are the criteria to determine the choice of documentation > tool/technology for Oozie? > > E.g.: > - Integration with the build system, i.e., Maven > - Ease of use (are there too many quirks) > - Standard editors that will ease the burden of programming/editing > - Ease of debugging > - Feedback from other Apache projects > > It will be good to list criteria, evaluate the pros/cons and then decide to > proceed with APT or choose a different documentation tool. > > Thanks, > Santhosh > > > -----Original Message----- > From: Alejandro Abdelnur [mailto:[email protected]] > Sent: Tuesday, October 11, 2011 1:30 PM > To: [email protected] > Subject: Re: Oozie documentation in Apache using APT > > Sorry, meant Params. > > Thanks. > > On Tue, Oct 11, 2011 at 1:29 PM, Alejandro Abdelnur <[email protected]>wrote: > >> Mohammad, >> >> Would you try the following syntax for snippets: >> >> +---+ >> ... >> <dependency> >> <groupId>com.cloudera.hoop</groupId> >> <artifactId>hoop-client</artifactId> >> <version>${project.version}</version> >> </dependency> >> ... >> +---+ >> >> Thanks. >> >> Alejandro >> >> On Tue, Oct 11, 2011 at 1:19 PM, Params <[email protected]> wrote: >> >>> Hi, >>> >>> Following are the details of the issue we ran into: >>> >>> *Description:* >>> I tried to add the following snippet of xml into my .apt source file >>> inside a 'verbatim' block. >>> >>> >>> --------------------------------------------------------------------- >>> ----------------------- >>> <configuration> >>> <property> >>> <name>mapred.job.queue.name</name> >>> <value>${queueName}</value> >>> </property> >>> <property> >>> <name>error.message</name> >>> <value>Something went wrong: >>> ${wf:errorCode('wordcount')}</value> >>> </property> >>> </configuration> >>> >>> --------------------------------------------------------------------- >>> ----------------------- >>> >>> On trying to build the maven project for the site documentation, $ >>> mvn site >>> >>> I get the following error: >>> >>> [ERROR] org.apache.velocity.runtime.parser.ParseException: Encountered >>> ":errorCode(\'wordcount\')}</message>\n </kill/>\n <end >>> >>> name=\'end\'/>\n</workflow-app>\n------------------------------------ >>> ----------------------------------------------\n\n >>> <<Notes:>>\n\n <<" at line 134, column 44. >>> Was expecting one of: >>> "}" ... >>> <DOT> ... >>> >>> >>> Observations: >>> 1) It appears that whenever I use any text of the format: >>> ${wf:errorCode('wordcount')} , APT throws a parse exception (even if >>> its contained in the verbatim block). >>> >>> 2) Other text like ${queueName} seems to work well. >>> >>> 3) I tried escaping the characters - {, $, :, etc.. but it doesnt >>> work either. >>> >>> 4) I tried using the APT Editor (Eclipse plugin). It does not give >>> any errors on preview, but publishing the .apt using a 'mvn site' still >>> fails. >>> >>> *Workaround (based on response from the maven nabble forum):* >>> Source: >>> >>> http://maven.40175.n5.nabble.com/APT-Issue-with-adding-xml-code-snipp >>> ets-as-Verbatim-tt4831524.html#a4831572 >>> >>> The idea is to assign the "complex" value to a variable, next print >>> that >>> variable: >>> <value>#set($varline = '${wf:errorCode("wordcount")}') >>> ${varline}</value> >>> >>> However, the display text I now get on the html page is: >>> <value> ${wf:errorCode("wordcount")}</value> >>> >>> This is not exactly the output we desire, we would prefer the >>> wordcount to appear inside single-quotes (in the html file generated) as: >>> ${wf:errorCode('wordcount')} >>> >>> The three following combinations (of the workaround described) don't >>> work (fail while running the mvn build): >>> <value>#set($varline = '${wf:errorCode(\'wordcount\')}') >>> ${varline}</value> <value>#set($varline = >>> "${wf:errorCode('wordcount')}") ${varline}</value> >>> <value>#set($varline = "${wf:errorCode(\'wordcount\')}") >>> ${varline}</value> >>> >>> To summarize, it appears that there could be such other issues as >>> well in the future (with other APT document elements) that could slow >>> down the documentation process. It would be a good idea to assess the >>> capabilities and shortcomings of APT. We also found that the doxia >>> mailing lists ( [email protected] and >>> doxia-dev-subscribe@maven >>> .apache.org) have been shutdown and merged into the main maven list: >>> http://maven.40175.n5.nabble.com/ >>> >>> Please let me know if any more information is required. >>> -- >>> Thanks, >>> Params >>> >>> >>> >>> On Tue, Oct 11, 2011 at 12:33 PM, Mohammad Islam <[email protected]> >>> wrote: >>> >>> > Hi, >>> > As previously discussed, we did a POC using APT based documentation >>> > ( http://maven.apache.org/doxia/references/apt-format.html). >>> > In short, we found APT is very simple and easy to use. >>> > However, at least in one common case, we didn't find any good way >>> > of writing the EL functions. >>> > (@Params: Would you please provide more details of the issue?). >>> > >>> > Please give your comments on the followings: >>> > * Should we continue to use APT? Is there any other better option >>> > available? >>> > >>> > * Should we move our existing official Oozie doc from twiki to APT >>> > as >>> well? >>> > Currently we plan to adopt the new documentation framework for >>> > Apache >>> Oozie >>> > site. >>> > >>> > >>> > Regards, >>> > Mohammad >>> > >>> >>> >>> >>> -- >>> params >>> >> >> >
