Author: fmeschbe
Date: Sat Dec 15 19:59:14 2012
New Revision: 1422336
URL: http://svn.apache.org/viewvc?rev=1422336&view=rev
Log:
FELIX-3816 Add some tips from the readme.txt file to the documentation page
Modified:
felix/site/trunk/content/documentation.mdtext
Modified: felix/site/trunk/content/documentation.mdtext
URL:
http://svn.apache.org/viewvc/felix/site/trunk/content/documentation.mdtext?rev=1422336&r1=1422335&r2=1422336&view=diff
==============================================================================
--- felix/site/trunk/content/documentation.mdtext (original)
+++ felix/site/trunk/content/documentation.mdtext Sat Dec 15 19:59:14 2012
@@ -1,8 +1,8 @@
-Title: documentation
+Title: Documentation
-# Documentation
-
-*The Felix web site and documentation are maintained on our
[wiki](http://cwiki.apache.org/confluence/x/O-).*
+*The Felix web site and documentation are managed with the [Apache
CMS](https://www.apache.org/dev/cms.html).
+For Apache Felix specific extensions see the [Site How-To](#site-how-to)
+section below.*
In an effort to make it easier to find desired documentation, we have divided
our documentation section into the following six areas:
@@ -13,4 +13,106 @@ In an effort to make it easier to find d
* [Subprojects]({{ refs.subprojects.path }}) - This area captures user
documentation for the various Felix subprojects.
* [Tutorials, examples, and presentations]({{
refs.tutorials-examples-and-presentations.path }}) - This area captures general
user documentation that does not necessarily fit into any single subproject.
+In addition a [site map]({{ refs.sitemap.path }}) is available as a table of
+contents of the site.
+
If you are unable to find the documentation you need, please ask on the
[mailing lists]({{ refs.mailinglists.path }}). Also, feedback on improving the
documentation and/or organization of this site is welcome.
+
+
+## Site How-To
+
+The site is managed with the [Apache CMS](https://www.apache.org/dev/cms.html)
+where the source is kept in SVN at
<https://svn.apache.org/repos/asf/felix/site/trunk/content>.
+
+This section lists some Apache Felix features to help with the maintenance
+of the site, such as automatic link generation.
+
+Start the file with a `Title:` line to define the page title and the first H1
tag:
+
+ Title: Page Title
+
+ Here comes the content separated with a blank like from the
+ header ...
+
+The last modification information from SVN (revision, committer, and
+date/time) is automatically added when the page is rendered
+
+Excerpts can be added to a page using the `Excerpt:` header:
+
+ Title: Page Title
+ Excerpt: Summary of the page for inclusion in other pages;
+ continuation of the excerpt must be indented
+
+ Here comes the content separated with a blank like from the
+ header ...
+
+Metadata from child pages can be referred to in the content with the
+Django variable reference notation using the child page name (without
+extension) as its container; e.g. for the child page named `childpage`:
+
+ :::django
+ {{ y|default:"{{" }} children.childpage.headers.excerpt }}
+ {{ y|default:"{{" }} children.childpage.headers.title }}
+
+Content Pages can contain Django templates of the form `{{ y|default:"{{"
}}...}}` and `{{ y|default:"{%" }}...%}`.
+If so, the page content is evaluated as a Django template before running
+it through the page template.
+
+Any page in the site can be referenced with refs.pagename returning properties:
+
+`.path`
+: the absolute path of the page on the site
+
+`.headers`
+: page headers (e.g. `.title`, `.excerpt`)
+
+`.content`
+: the raw page content
+
+All pages in the children namespace are also available in the refs namespace
+
+Some usefull hints:
+
+Printing title of another page "handler":
+
+ :::django
+ {{ y|default:"{{" }} refs.handler.headers.title }}
+
+Printing excerpt of another page "handler":
+
+ :::django
+ {{ y|default:"{{" }} refs.handler.headers.excerpt }}
+
+Linking to another page "handler":
+
+ :::django
+ ({{ y|default:"{{" }} refs.handler.path }})
+
+Printing title as a link to another page "handler":
+
+ :::django
+ [{{ y|default:"{{" }} refs.handler.headers.title }}]({{ y|default:"{{"
}} refs.handler.path }})
+
+Printing excerpt as a link to another page "handler":
+
+ :::django
+ [{{ y|default:"{{" }} refs.handler.headers.excerpt }}]({{
y|default:"{{" }} refs.handler.path }})
+
+Print a bullet pointed child page list:
+
+ :::django
+ {{ y|default:"{%" }} for label, page in children %}* [{{ y|default:"{{"
}} page.headers.title }}]({{ y|default:"{{" }} page.path }})
+ {{ y|default:"{%" }} endfor %}
+
+<div class="note">
+It is important to have the first part as a single line, otherwise
+the Django/Markdown combo will create a list for each entry.
+</div>
+
+Code Highlighting works by indenting code by four blanks. To indicate the
+type of highlighting preced the code style text with either `:::<lexer>` to
+get high lighted code using the given `<lexer>` or `#!<lexer>` to get high
+lighted code with line numbers using the given `<lexer>`. See
+<http://www.apache.org/dev/cmsref.html#code-hilighter> for main info and
+<http://pygments.org/docs/lexers/> for supported lexers
+
