[skin][fluido] APT vs XDOC
Hi, One problem with using APT for writing docs is that code can only be included within the +-- tags. This is rendeder as two nested elements div class=sourcepre Then you add the prettpyrint class by javascript to all pre elements within code elements. This does not allow for non-prettified pre blocks and makes some pages look pretty weird, e.g.: http://people.apache.org/~olamy/maven/site/license.html The only reasonable alternative i discovered is using XDOC and specifying your own blocks as either: a) pre b) pre class=prettyprint c) pre class=prettyprint linenums This allows for much more flexibility, but requires usage of XDOC format to have code prettification. APT +-- syntax always produces plain pre blocks. Again, the problem is that maven transforms pre class=prettyprint to div class=prettyprintpre (why o why?) but this can also be fixed by javascript. To conclude, I'm migrating most of log4php docs to XDOC format because of this and some other APT limitations. It is a bit more difficult to write, but it is more flexible. If you like the solution I can transfer it to the sandbox. Regards, Ivan - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [skin][fluido] APT vs XDOC
I recently did a bit of work with the markdown module, which is a good alternative to APT. I'd be interested in exploring supporting GitHub Flavored Markdown so that you can mark up blocks a bit more: ```java ``` etc. - Brett On 18/10/2011, at 5:28 PM, Ivan Habunek wrote: Hi, One problem with using APT for writing docs is that code can only be included within the +-- tags. This is rendeder as two nested elements div class=sourcepre Then you add the prettpyrint class by javascript to all pre elements within code elements. This does not allow for non-prettified pre blocks and makes some pages look pretty weird, e.g.: http://people.apache.org/~olamy/maven/site/license.html The only reasonable alternative i discovered is using XDOC and specifying your own blocks as either: a) pre b) pre class=prettyprint c) pre class=prettyprint linenums This allows for much more flexibility, but requires usage of XDOC format to have code prettification. APT +-- syntax always produces plain pre blocks. Again, the problem is that maven transforms pre class=prettyprint to div class=prettyprintpre (why o why?) but this can also be fixed by javascript. To conclude, I'm migrating most of log4php docs to XDOC format because of this and some other APT limitations. It is a bit more difficult to write, but it is more flexible. If you like the solution I can transfer it to the sandbox. Regards, Ivan - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org -- Brett Porter br...@apache.org http://brettporter.wordpress.com/ http://au.linkedin.com/in/brettporter - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [skin][fluido] APT vs XDOC
Hi Ivan! the License page doesn't look good indeed in this way, we have to do something. As you noticed, applying the `prettyprint` class to div class=sourcepre elements, would warrant that feature even to formats where classes cannot be set (due to some limitations of the language). Suggesting our users to port their existing sites to xdoc to have the prettification feature wouldn't be so nice - the maven site itself is written in APT and is a lot of documentation! - so what I suggest is trying to understand when is not appropriate applying the current document modification. Maybe the License page - and few other cases that I don't know - are just exceptions. My 2 cents, Simo http://people.apache.org/~simonetripodi/ http://simonetripodi.livejournal.com/ http://twitter.com/simonetripodi http://www.99soft.org/ 2011/10/18 Ivan Habunek ivan.habu...@gmail.com: Hi, One problem with using APT for writing docs is that code can only be included within the +-- tags. This is rendeder as two nested elements div class=sourcepre Then you add the prettpyrint class by javascript to all pre elements within code elements. This does not allow for non-prettified pre blocks and makes some pages look pretty weird, e.g.: http://people.apache.org/~olamy/maven/site/license.html The only reasonable alternative i discovered is using XDOC and specifying your own blocks as either: a) pre b) pre class=prettyprint c) pre class=prettyprint linenums This allows for much more flexibility, but requires usage of XDOC format to have code prettification. APT +-- syntax always produces plain pre blocks. Again, the problem is that maven transforms pre class=prettyprint to div class=prettyprintpre (why o why?) but this can also be fixed by javascript. To conclude, I'm migrating most of log4php docs to XDOC format because of this and some other APT limitations. It is a bit more difficult to write, but it is more flexible. If you like the solution I can transfer it to the sandbox. Regards, Ivan - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
