9

I am currently starting to write a documentation for one of our projects. For reasons of simplicity we chose to use the Almost Plain Text (APT) Format, see more info here: http://maven.apache.org/doxia/references/apt-format.html

APT is great documentation format, since it uses a minimal syntax and hence it is very easy to create and make changes to the documentation without knowing a lot about APT.

However, I couldn't find a way to format code in a nice way. Is there a code tag or similar, which can be used to include some source code? I'm aware I could use FML, but this would be less desirable.

Thanks

evgeni
  • 1,675
  • 3
  • 22
  • 29
  • just saw this plugin: http://code.google.com/p/m2-site-tools/wiki/UserGuide however, the hightlight feature doesn't seem to work nether for java nor for xml. – evgeni Sep 22 '11 at 15:10
  • there is also this project: http://doxia-include.sourceforge.net/usageAndReference.html. However, I could not build my pom.xml since the dependencies were missing: Project build error: Unresolveable build extension: Plugin org.apache.maven.plugins:maven-site-plugin:3.0-beta-3 or one of its dependencies could not be resolved: Could not find artifact org.tinyjee:doxia-include-macro:jar:1.0 in central (http://repo1.maven.org/maven2) – evgeni Sep 22 '11 at 15:24
  • same problem with this project: http://syntax-highlighted-snippet.googlecode.com/svn/site/index.html – evgeni Sep 22 '11 at 15:28

5 Answers5

11

For those who are still wondering how to make a code snipped in APT:

     This is regular text
+---------------------
This is a code snippet
+---------------------
      More regular text
josh-cain
  • 4,997
  • 7
  • 35
  • 55
3

Apache Maven Fluido Skin highlights syntax out of the box. Here you can find an example. Information about syntax highlighting in Fluido: "Source code sections are enhanced by Google Code Prettify, users can optionally enable line numbers rendering (disabled by default)" from Fluido website.

Marcin
  • 1,469
  • 14
  • 23
  • The page of the link you provide in your example seems to be created with xdoc, not with APT (see https://svn.apache.org/repos/asf/logging/log4j/log4j2/trunk/src/site/xdoc/manual/markers.xml). Do you happen to know an example utilizing Fluido/Google Code Prettify with APT? (cannot make it happen with my project it seems... maybe I should resort to xdoc too) – evandor Sep 29 '13 at 09:38
  • @evandor Maven Fluido Skin project itself uses APT; [maven-fluido-skin](http://maven.apache.org/skins/maven-fluido-skin/) site is made using APT ([source](http://svn.apache.org/viewvc/maven/skins/tags/maven-fluido-skin-1.3.0/src/site/apt/index.apt.vm?view=markup)). – Marcin Sep 29 '13 at 14:06
3

The

+---------------------
code
+---------------------

syntax is correct. And Fluido does highlight using Prettify out of the box as others have mentioned.

However, a Doxia change in Site Plugin 3.3 broke Fluido. MSKINS-86 fixes this, but hasn't been released yet.

Workarounds

  1. Use the site.xml workaround <body> <head> <script type="text/javascript"> $(document).ready(function () { $("div.source pre").addClass("prettyprint"); prettyPrint(); }); </script> </head> </body>
  2. Use Site Plugin 3.2
  3. Build the unreleased Fluido 1.4 that contains MSKINS-86 fix and use it instead of 1.3.1
Keegan
  • 11,345
  • 1
  • 25
  • 38
2

I ended up using the snippet macro from the Doxia Macros Guide: http://maven.apache.org/doxia/macros/index.html#Snippet_Macro

It puts the code from the snippet file in a verbatim box. However it does not provide a syntax highlightning.

evgeni
  • 1,675
  • 3
  • 22
  • 29
0

Version 1.0 of doxia include macro is not at maven central however the following versions are: http://mvnrepository.com/artifact/org.tinyjee.dim/doxia-include-macro

jkellerer
  • 11