Twiki Module Enhancements

[Abhijit Bagri]

Hi,

I am Abhijit and work in a platform team at Yahoo! We recently moved
documentation of our project from our Twiki web to mvn, primarily so
that we could maintain our documentation more effectively and keep it in
sync with rapidly changing feature set of our platform.

I tried using the twiki module. I found it quite a bit done, but there
were a bunch of features we needed for us to use it. I have
enhanced/modified the twiki module for the following features:

1. Enable doxia macros in twiki-module. The syntax I have chosen for
this is %MACRO_NAME|param=value|param2=value2%
This was most important for the toc macro. A related change which was
needed is #2

2. Since toc needed the whole doc source to be supplied, I had to modify
ByLineSource implementation to have the entire source. Since changing
the whole line based implementation was taknig too much, I just emulated
whole source reading and supporting the getLine method in the new
implementation.

3. Enable linking of wiki words.

Earlier a [[MyWikiWord]] would get likned to ./MyWikiWord. I am not sure
why it was this way. Some light on this? I needed it to point it to
./MyWikiWord.html to be useful. Similarly for linking up wikiwords in
[[][]].

4. Enable HTML tags. I saw a JIRA on this. Its not assigned so I guess I
can put in my patch there

5. Enabling verbatim and blockquote. verbatim did not seem to work
properly for me.

We are currently using a patched version of alpha-9 successfully at
Yahoo! (for internal usage only). However, We though that the community
may benefit from this and decided to contribute back.

I see that the current tag is 11-alpha. I would appreciate if someone
could let me know progress on these issues. I will create necessary JIRA
for this and add my patch after that.

Thanks
Abhijit

[Jason van Zyl-2]

If you create a JIRA issue and attach a patch, I'll apply it. I've  
been playing with the confluence parser in the last few days and the  
twiki parser is very similar so I can work on it.

On 22-May-08, at 11:41 PM, Abhijit Bagri wrote:

> Hi,
>
> I am Abhijit and work in a platform team at Yahoo! We recently moved  
> documentation of our project from our Twiki web to mvn, primarily so  
> that we could maintain our documentation more effectively and keep  
> it in sync with rapidly changing feature set of our platform.
>
> I tried using the twiki module. I found it quite a bit done, but  
> there were a bunch of features we needed for us to use it. I have  
> enhanced/modified the twiki module for the following features:
>
> 1. Enable doxia macros in twiki-module. The syntax I have chosen for  
> this is %MACRO_NAME|param=value|param2=value2%
> This was most important for the toc macro. A related change which  
> was needed is #2
>
> 2. Since toc needed the whole doc source to be supplied, I had to  
> modify ByLineSource implementation to have the entire source. Since  
> changing the whole line based implementation was taknig too much, I  
> just emulated whole source reading and supporting the getLine method  
> in the new implementation.
>
> 3. Enable linking of wiki words.
>
> Earlier a [[MyWikiWord]] would get likned to ./MyWikiWord. I am not  
> sure why it was this way. Some light on this? I needed it to point  
> it to ./MyWikiWord.html to be useful. Similarly for linking up  
> wikiwords in [[][]].
>
> 4. Enable HTML tags. I saw a JIRA on this. Its not assigned so I  
> guess I can put in my patch there
>
> 5. Enabling verbatim and blockquote. verbatim did not seem to work  
> properly for me.
>
> We are currently using a patched version of alpha-9 successfully at  
> Yahoo! (for internal usage only). However, We though that the  
> community may benefit from this and decided to contribute back.
>
> I see that the current tag is 11-alpha. I would appreciate if  
> someone could let me know progress on these issues. I will create  
> necessary JIRA for this and add my patch after that.
>
> Thanks
> Abhijit
>
>

Thanks,

Jason

----------------------------------------------------------
Jason van Zyl
Founder,  Apache Maven
jason at sonatype dot com
----------------------------------------------------------

believe nothing, no matter where you read it,
or who has said it,
not even if i have said it,
unless it agrees with your own reason
and your own common sense.

-- Buddha

[Vincent Siveton]

Hi Abhijit,

I recommend you to provide a patch under the trunk and not under alpha
tag. The trunk is Doxia beta-1.

Thanks,

Vincent

2008/5/23, Abhijit Bagri <abagri@...>:

> Hi,
>
>  I am Abhijit and work in a platform team at Yahoo! We recently moved
> documentation of our project from our Twiki web to mvn, primarily so that we
> could maintain our documentation more effectively and keep it in sync with
> rapidly changing feature set of our platform.
>
>  I tried using the twiki module. I found it quite a bit done, but there were
> a bunch of features we needed for us to use it. I have enhanced/modified the
> twiki module for the following features:
>
>  1. Enable doxia macros in twiki-module. The syntax I have chosen for this
> is %MACRO_NAME|param=value|param2=value2%
>  This was most important for the toc macro. A related change which was
> needed is #2
>
>  2. Since toc needed the whole doc source to be supplied, I had to modify
> ByLineSource implementation to have the entire source. Since changing the
> whole line based implementation was taknig too much, I just emulated whole
> source reading and supporting the getLine method in the new implementation.
>
>  3. Enable linking of wiki words.
>
>  Earlier a [[MyWikiWord]] would get likned to ./MyWikiWord. I am not sure
> why it was this way. Some light on this? I needed it to point it to
> ./MyWikiWord.html to be useful. Similarly for linking up wikiwords in
> [[][]].
>
>  4. Enable HTML tags. I saw a JIRA on this. Its not assigned so I guess I
> can put in my patch there
>
>  5. Enabling verbatim and blockquote. verbatim did not seem to work properly
> for me.
>
>  We are currently using a patched version of alpha-9 successfully at Yahoo!
> (for internal usage only). However, We though that the community may benefit
> from this and decided to contribute back.
>
>  I see that the current tag is 11-alpha. I would appreciate if someone could
> let me know progress on these issues. I will create necessary JIRA for this
> and add my patch after that.
>
>  Thanks
>  Abhijit
>
>
>

[Juan F. Codagnone-4]

Abhijit,

I am really glad to hear that you guys at Yahoo are using and
contribuiting to the twiki module.

On Friday 23 May 2008, Abhijit Bagri wrote:
...
> 2. Since toc needed the whole doc source to be supplied, I had to modify
> ByLineSource implementation to have the entire source. Since changing
> the whole line based implementation was taknig too much, I just emulated
> whole source reading and supporting the getLine method in the new
> implementation.

Couldn't be the TOC be generated transversing the block tree returned by the
parser?

> 3. Enable linking of wiki words.
>
> Earlier a [[MyWikiWord]] would get likned to ./MyWikiWord. I am not sure
> why it was this way. Some light on this? I needed it to point it to
> ./MyWikiWord.html to be useful. Similarly for linking up wikiwords in
> [[][]].

This was fixed in http://jira.codehaus.org/browse/DOXIA-194.  

I just added a test to my working copy in the file
http://svn.apache.org/repos/asf/maven/doxia/doxia/trunk/doxia-modules/doxia-module-twiki/src/test/java/org/apache/maven/doxia/module/twiki/parser/WordsTest.java
(where the test cases for WikiWords links lives) and i get ./MyWikiWord.html.

    public void testHtml() throws ParseException  
    {
        final StringWriter sw = new StringWriter();
        final Sink sink = new XhtmlBaseSink(sw);
        twikiParser.parse("[[MyWikiWord]]", sink);
        assertEquals("<p><a href=\"./MyWikiWord.html\">MyWikiWord</a></p>",
                 sw.toString());
    }

The links are generated by the strategy WikiWordLinkResolver and can be
replaced.

...

> 5. Enabling verbatim and blockquote. verbatim did not seem to work
> properly for me.

verbatim worked well on our pages, but i think it can be more bulletproof and
more general.  Don't forget to add the broken cases for regression in:

http://svn.apache.org/repos/asf/maven/doxia/doxia/trunk/doxia-modules/doxia-module-twiki/src/test/java/org/apache/maven/doxia/module/twiki/parser/VerbatimTest.java


I wrote most of the twiki module code, so do not hesitate to send me especific
questions.

Regards,
  Juan.

--
Buenos Aires, Argentina                             19°C with winds at 0 km/h
http://www.zauber.com.ar/                           http://juan.zauber.com.ar/