You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@oozie.apache.org by Mohammad Islam <mi...@yahoo.com> on 2011/10/11 21:33:19 UTC

Oozie documentation in Apache using APT

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

Re: Oozie documentation in Apache using APT

Posted by Alejandro Abdelnur <tu...@gmail.com>.

* 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 <sm...@yahoo-inc.com> 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:tucu@cloudera.com]
> Sent: Tuesday, October 11, 2011 1:30 PM
> To: oozie-dev@incubator.apache.org
> Subject: Re: Oozie documentation in Apache using APT
>
> Sorry, meant Params.
>
> Thanks.
>
> On Tue, Oct 11, 2011 at 1:29 PM, Alejandro Abdelnur <tu...@cloudera.com>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 <pa...@gmail.com> 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 ( doxia-users-subscribe@maven.apache.org 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 <mi...@yahoo.com>
>>> 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
>>>
>>
>>
>