commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From S├ębastien Brisard <sebastien.bris...@m4x.org>
Subject [math] Documentation: xdoc, apt and twiki pros and cons
Date Fri, 21 Sep 2012 03:47:24 GMT
Hello,
I've been playing around with these three formats. Here are my thoughts

xdoc
  + already used by the existing doc,
  + possible to embed XHTML tags,
  - like all xml based languages, it is difficult to read, especially
when it comes to tables.

apt
  + increased readability,
  - not possible to embed XHTML tags.

twiki
  + increased readability,
  + possible to embed XHTML tags,
  - not really superior to apt,
  - last version dates back 2007,
  - I could not find the way to comment out some text, so I could not
include the license in my test file. Looking up the web, <!-- -->
should work; well, I could not make it work.
  - there is no syntax to specify the title of the page (in the sense
of the <head><title>...</title></head> XHTML tags). Using XHTML
embedded code like <title>...</title> does not work, which was to be
expected, since the doc states that the embedded code would go in the
<body>...</body> section.

So, all in all, I would still recommend apt.

S├ębastien

PS: all three options are very easy to learn. twiki requires the
following alteration of the pom.xml in the
<build><plugins>...</plugins></build> section
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-twiki</artifactId>
            <version>1.2</version>
          </dependency>
        </dependencies>
      </plugin>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message