Author: wsmoak
Date: Sat Nov 25 12:55:55 2006
New Revision: 479196
URL: http://svn.apache.org/viewvc?view=rev&rev=479196
Log:
Adding some documentation for the snippet macro.
Added:
maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt (with
props)
Modified:
maven/site/trunk/src/site/apt/guides/index.apt
Modified: maven/site/trunk/src/site/apt/guides/index.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/index.apt?view=diff&rev=479196&r1=479195&r2=479196
==============================================================================
--- maven/site/trunk/src/site/apt/guides/index.apt (original)
+++ maven/site/trunk/src/site/apt/guides/index.apt Sat Nov 25 12:55:55 2006
@@ -48,6 +48,8 @@
* {{{mini/guide-site.html}Creating a Site}}
* {{{mini/guide-apt-format.html}The APT Format}}
+
+ * {{{mini/guide-snippet-macro.html}Snippet Macro}}
** Archetypes
Added: maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt?view=auto&rev=479196
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt (added)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt Sat Nov
25 12:55:55 2006
@@ -0,0 +1,94 @@
+ ------
+ Guide to the Snippet Macro
+ ------
+ Wendy Smoak
+ ------
+ 20 November 2006
+ ------
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed under the Apache License, Version 2.0 (the "License");
+~~ you may not use this file except in compliance with the License.
+~~ You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+
+Guide to the Snippet Macro
+
+ When generating your project website with Maven, you have the option of
+ dynamically including <snippet>s of source code in your pages.
+
+ A <snippet> is a section of a source code file that is surrounded by specially
+ formatted comments.
+
+ This functionality is inspired by the
+ {{{http://www.atlassian.com/software/confluence/}Confluence}} snippet macro,
+ and is provided by the Maven Doxia project by way of the Maven Site Plugin.
+
+ To include snippets of source code in your documentation, first add comments
+ in the source document surrounding the lines you want to include, and then
+ refer to the snippet by its id in the documentation file.
+
+ Each snippet must be assigned an id, and the id must be unique within the
+ source document.
+
+ Following are examples of snippets in Java and XML source documents, as well
+ as the corresponding macros in the APT documentation formats.
+
+* Snippets in Sources
+
+** Java
+
+-----
+ // START SNIPPET: snip-id
+ public static void main( String[] args )
+ {
+ System.out.println( "Hello World!" );
+ }
+ // END SNIPPET: snip-id
+-----
+
+** XML
+
+-----
+ <!-- START SNIPPET: snip-id -->
+ <navigation-rule>
+ <from-view-id>/logon.jsp</from-view-id>
+ <navigation-case>
+ <from-outcome>success</from-outcome>
+ <to-view-id>/mainMenu.jsp</to-view-id>
+ </navigation-case>
+ </navigation-rule>
+ <!-- END SNIPPET: snip-id -->
+-----
+
+* Snippets in Documentation
+
+** APT
+
+ Macros in apt <<must not>> be indented.
+
+------
+%{snippet|id=snip-id|url=http://svn.example.com/path/to/Sample.java}
+
+%{snippet|id=snip-id|url=file:///path/to/Sample.java}
+------
+
+** XDOC
+
+ See {{{http://jira.codehaus.org/browse/DOXIA-77}DOXIA-77}} -
+ Snippets do not work in xdoc
+
+~~ ------
+~~ <snippet id="snip-id" url="http://svn.example.com/path/to/Sample.java"/>
+~~
+~~ <snippet id="snip-id"
url="file:///c:/temp/my-app/src/main/java/com/mycompany/app/App.java"/>
+~~ ------
+
Propchange: maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/site/trunk/src/site/apt/guides/mini/guide-snippet-macro.apt
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
