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