Author: buildbot
Date: Tue Jan 8 19:05:58 2013
New Revision: 845556
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Jan 8 19:05:58 2013
@@ -1 +1 @@
-1426501
+1430446
Modified: websites/staging/sling/trunk/content/documentation.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation.html (original)
+++ websites/staging/sling/trunk/content/documentation.html Tue Jan 8 19:05:58
2013
@@ -94,9 +94,33 @@
<li><a href="/documentation/configuration.html">Configuration</a></li>
<li><a href="">API Doc</a></li>
</ul>
-<h2 id="how-can-you-contribute">How can you contribute</h2>
+<h1 id="how-can-you-contribute">How can you contribute</h1>
<p>We're on the way to improve the documentation, but it's a long way. If you
would like to contribute to the documentation you are very welcome. Please
directly post your proposals to the <a href="">public wiki</a> or post your
suggestions to the mailing list.</p>
-<h2 id="how-is-the-documentation-generated">How is the documentation
generated</h2>
+<h1 id="how-is-the-documentation-generated">How is the documentation
generated</h1>
+<p><em>The Sling web site and documentation are managed with the <a
href="https://www.apache.org/dev/cms.html";>Apache CMS</a>.
+For Apache Sling specific extensions see the <a href="#the-sling-site">The
Sling Site</a>
+section below.</em></p>
+<div class="info">
+<p>
+The Sling site is being converted from a Confluence exported site to an
+Apache CMS managed site. During this conversion not all pages will display
+correctly. All non-fully converted pages will show a tip box pointing to
+the original Confluence exported page for reference.
+</p>
+
+<p>
+Once migration of a page has completed the <code>translation_pending</code>
+header should be removed from the page source. After that the tip box will not
be
+shown any more.
+</p>
+
+<p>
+While this page has technically been translated already, the
<code>translation-pending</code>
+header is kept to remind us to remove this info box once translation has
+completed.
+</p>
+</div>
+
<p>The basic documentation of Sling is made up of four parts:</p>
<ol>
<li>The Sling Site at http://sling.apache.org/ (you are here)</li>
@@ -105,45 +129,128 @@
<li>The Bundle documentation</li>
</ol>
<p>This page is about how this documentation is maintained and who is allowed
to do what.</p>
-<h3 id="the-sling-site">The Sling Site</h3>
-<h4 id="main-site">Main Site</h4>
-<p>The main Sling Site is maintained in the Confluence Wiki Space
<em>SLINGxSITE</em>. The content of this space is automatically synchronized
with the web server with a simple shell script <a href="">^sling.sh</a> which
is called regularly as per the following <code>crontab</code> entry:</p>
-<div class="codehilite"><pre><span class="c1"># sync wiki autoexport to Sling
site</span>
-<span class="mi">1</span> <span class="o">*</span> <span class="o">*</span>
<span class="o">*</span> <span class="o">*</span> <span class="p">(</span><span
class="sr">/home/</span><span class="n">fmeschbe</span><span
class="o">/</span><span class="n">sling</span><span class="o">.</span><span
class="n">sh</span><span class="p">)</span>
+<h2 id="the-sling-site">The Sling Site</h2>
+<p>The site is managed with the <a
href="https://www.apache.org/dev/cms.html";>Apache CMS</a>
+where the source is kept in SVN at <a
href="https://svn.apache.org/repos/asf/sling/site/trunk/content";>https://svn.apache.org/repos/asf/sling/site/trunk/content</a>.</p>
+<p>This section lists some Apache Sling features to help with the maintenance
+of the site, such as automatic link generation.</p>
+<p>Start the file with a <code>Title:</code> line to define the page title and
the first H1 tag:</p>
+<div class="codehilite"><pre><span class="err">Title:</span> <span
class="err">Page</span> <span class="err">Title</span>
+
+<span class="err">Here</span> <span class="err">comes</span> <span
class="err">the</span> <span class="err">content</span> <span
class="err">separated</span> <span class="err">with</span> <span
class="err">a</span> <span class="err">blank</span> <span
class="err">like</span> <span class="err">from</span> <span
class="err">the</span>
+<span class="err">header</span> <span class="err">...</span>
</pre></div>
-<p>Thus, after editing the site source in the Wiki, the rest happens
automatically, it just takes some time -- in the order 2 hours or so -- before
the changes are visible at http://sling.apache.org/.</p>
-<p>Everybody is allowed to read the SLINGxSITE wiki and to add comments; but
only committers of the Apache Sling project are allowed to edit the content and
to manage the comments.</p>
-<p>The main site is located in the <code>site</code> folder below the Site URL
<a href="">http://sling.apache.org/</a> to which users are redirected
automatically.</p>
-<h4 id="secondary-site">Secondary Site</h4>
-<p>The Sling site contains secondary site parts that are maintained in the
Apache SVN repository at <a
href="">http://svn.apache.org/repos/asf/sling/site</a>. Updates to secondary
parts of the site have to be done in the following steps:</p>
-<ol>
-<li>
-<p>Checkout or update the <a href="">site</a> tree form SVN.</p>
-<p>$ svn checkout https://svn.apache.org/repos/asf/sling/site</p>
-</li>
-<li>
-<p>Apply your changes.</p>
-</li>
-<li>
-<p>Commit the changes back into SVN.</p>
-<p>$ svn commit -m"<enter your message here>"</p>
-</li>
-<li>
-<p>Login to <code>people.apache.org</code></p>
-<p>$ ssh people.apache.org</p>
-</li>
-<li>
-<p>Go to the location from where infrastructure mirroring is getting the
actual sites and update from SVN.</p>
-<p>$ cd /x1/www/sling.apache.org
-$ svn update</p>
-</li>
-</ol>
-<p>After some time, the updates will be synchronized to the web servers and
can be accessed.</p>
-<h3 id="the-public-wiki">The Public Wiki</h3>
+<p>The last modification information from SVN (revision, committer, and
+date/time) is automatically added when the page is rendered</p>
+<p>Excerpts can be added to a page using the <code>Excerpt:</code> header:</p>
+<div class="codehilite"><pre><span class="err">Title:</span> <span
class="err">Page</span> <span class="err">Title</span>
+<span class="err">Excerpt:</span> <span class="err">Summary</span> <span
class="err">of</span> <span class="err">the</span> <span
class="err">page</span> <span class="err">for</span> <span
class="err">inclusion</span> <span class="err">in</span> <span
class="err">other</span> <span class="err">pages;</span>
+ <span class="err">continuation</span> <span class="err">of</span> <span
class="err">the</span> <span class="err">excerpt</span> <span
class="err">must</span> <span class="err">be</span> <span
class="err">indented</span>
+
+<span class="err">Here</span> <span class="err">comes</span> <span
class="err">the</span> <span class="err">content</span> <span
class="err">separated</span> <span class="err">with</span> <span
class="err">a</span> <span class="err">blank</span> <span
class="err">like</span> <span class="err">from</span> <span
class="err">the</span>
+<span class="err">header</span> <span class="err">...</span>
+</pre></div>
+
+
+<p>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
<code>childpage</code>:</p>
+<div class="codehilite"><pre><span class="cp">{{</span> <span
class="nv">children.childpage.headers.excerpt</span> <span
class="cp">}}</span><span class="x"></span>
+<span class="cp">{{</span> <span
class="nv">children.childpage.headers.title</span> <span
class="cp">}}</span><span class="x"></span>
+</pre></div>
+
+
+<p>Content Pages can contain Django templates of the form <code>{{...}}</code>
and <code>{%...%}</code>.
+If so, the page content is evaluated as a Django template before running
+it through the page template.</p>
+<p>Any page in the site can be referenced with refs.pagename returning
properties:</p>
+<dl>
+<dt><code>.path</code></dt>
+<dd>the absolute path of the page on the site</dd>
+<dt><code>.headers</code></dt>
+<dd>page headers (e.g. <code>.title</code>, <code>.excerpt</code>)</dd>
+<dt><code>.content</code></dt>
+<dd>the raw page content</dd>
+</dl>
+<p>All pages in the children namespace are also available in the refs
namespace</p>
+<p>Some usefull hints:</p>
+<p>Printing title of another page "handler":</p>
+<div class="codehilite"><pre><span class="x"> </span><span
class="cp">{{</span> <span class="nv">refs.handler.headers.title</span> <span
class="cp">}}</span><span class="x"></span>
+</pre></div>
+
+
+<p>Printing excerpt of another page "handler":</p>
+<div class="codehilite"><pre><span class="x"> </span><span
class="cp">{{</span> <span class="nv">refs.handler.headers.excerpt</span> <span
class="cp">}}</span><span class="x"></span>
+</pre></div>
+
+
+<p>Linking to another page "handler":</p>
+<div class="codehilite"><pre><span class="x"> (</span><span
class="cp">{{</span> <span class="nv">refs.handler.path</span> <span
class="cp">}}</span><span class="x">)</span>
+</pre></div>
+
+
+<p>Printing title as a link to another page "handler":</p>
+<div class="codehilite"><pre><span class="x"> [</span><span
class="cp">{{</span> <span class="nv">refs.handler.headers.title</span> <span
class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span
class="nv">refs.handler.path</span> <span class="cp">}}</span><span
class="x">)</span>
+</pre></div>
+
+
+<p>Printing excerpt as a link to another page "handler":</p>
+<div class="codehilite"><pre><span class="x"> [</span><span
class="cp">{{</span> <span class="nv">refs.handler.headers.excerpt</span> <span
class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span
class="nv">refs.handler.path</span> <span class="cp">}}</span><span
class="x">)</span>
+</pre></div>
+
+
+<p>Print a bullet pointed child page list:</p>
+<div class="codehilite"><pre><span class="x"> </span><span
class="cp">{%</span> <span class="k">for</span> <span
class="nv">label</span><span class="o">,</span> <span class="nv">page</span>
<span class="k">in</span> <span class="nv">children</span> <span
class="cp">%}</span><span class="x">* [</span><span class="cp">{{</span> <span
class="nv">page.headers.title</span> <span class="cp">}}</span><span
class="x">](</span><span class="cp">{{</span> <span class="nv">page.path</span>
<span class="cp">}}</span><span class="x">)</span>
+<span class="x"> </span><span class="cp">{%</span> <span
class="k">endfor</span> <span class="cp">%}</span><span class="x"></span>
+</pre></div>
+
+
+<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>
+
+<h3 id="code-highlighting">Code Highlighting</h3>
+<p>Code Highlighting works by indenting code by four blanks. To indicate the
+type of highlighting preced the code style text with either
<code>:::<lexer></code> to
+get high lighted code using the given <code><lexer></code> or
<code>#!<lexer></code> to get high
+lighted code with line numbers using the given <code><lexer></code>. See
+<a
href="http://www.apache.org/dev/cmsref.html#code-hilighter";>http://www.apache.org/dev/cmsref.html#code-hilighter</a>
for main info and
+<a
href="http://pygments.org/docs/lexers/";>http://pygments.org/docs/lexers/</a>
for supported lexers</p>
+<h3 id="manual-generation">Manual Generation</h3>
+<p>When commiting changes to pages into SVN the pages are automatically
+generated in <a href="http://felix.staging.apache.org";>the staging
site</a>.</p>
+<p>To manually generate the site or single pages the <a
href="http://svn.apache.org/repos/asf/felix/site";>site</a>
+can be checked out from SVN. In addition Perl and Python must be installed
+for the build tools to work.</p>
+<p>To prepare for site build, the Markdown daemon has to be started:</p>
+<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">export
</span><span class="nv">MARKDOWN_SOCKET</span><span class="o">=</span><span
class="s2">"$PWD/tools/build/../markdown.socket"</span>
+<span class="nv">$ </span><span class="nb">export </span><span
class="nv">PYTHONPATH</span><span class="o">=</span><span
class="s2">"$PWD/tools/build"</span>
+<span class="nv">$ </span>python <span
class="s2">"$PWD/tools/build/markdownd.py"</span>
+</pre></div>
+
+
+<p>The <code>MARKDOWN_SOCKET</code> environment variables is also required by
the <code>build_site.pl</code>
+and <code>build_file.pl</code> scripts to connect to the Markdown daemon.</p>
+<p>To build the complete site use the <code>build_site.pl</code> script:</p>
+<div class="codehilite"><pre><span class="nv">$
</span>tools/build/build_site.pl --source-base <span
class="nv">$PWD</span>/trunk <span class="se">\</span>
+ --target-base <span class="nv">$PWD</span>/trunk/target
+</pre></div>
+
+
+<p>To build a single page use the <code>build_file.pl</code> script:</p>
+<div class="codehilite"><pre><span class="nv">$
</span>tools/build/build_site.pl --source-base <span
class="nv">$PWD</span>/trunk <span class="se">\</span>
+ --target-base <span class="nv">$PWD</span>/trunk/target <span
class="se">\</span>
+ --source content/documentation.mdtext
+</pre></div>
+
+
+<p>The argument to the <code>--source</code> parameter is relative to the
<code>--source-base</code> folder.</p>
+<h2 id="the-public-wiki">The Public Wiki</h2>
<p>The public wiki of Sling is available at http://cwiki.apache.org/SLING and
is maintained in the Confluence space <em>SLING</em>. This is a public wiki, in
that after self-registration, everybody is allowed to edit content.</p>
-<h3 id="the-javadoc">The JavaDoc</h3>
+<h2 id="the-javadoc">The JavaDoc</h2>
<p>Up until now the JavaDoc of the Sling Bundles has not been published.</p>
<p>I just polished the JavaDoc generation setup of Sling a bit, so that I
could generate a first shot of aggregate JavaDocs. This draft can currently be
found on my site at http://people.apache.org/~fmeschbe/slingdocs.762729/. This
JavaDoc has been generated as follows:</p>
<div class="codehilite"><pre><span class="nv">$</span> <span
class="nv">svn</span> <span class="n">export</span> <span
class="o">-</span><span class="n">r</span> <span class="mi">762729</span> <span
class="n">http:</span><span class="sr">//s</span><span class="n">vn</span><span
class="o">.</span><span class="n">apache</span><span class="o">.</span><span
class="n">org</span><span class="sr">/repos/</span><span
class="n">asf</span><span class="sr">/incubator/s</span><span
class="n">ling</span><span class="o">/</span><span class="n">trunk</span> <span
class="n">sling</span>
@@ -152,7 +259,7 @@ $ svn update</p>
<p>I am still unsure whether it makes sense to generate aggregate JavaDoc for
all (or part of) the bundles of Sling. See also below regarding the Sites.</p>
-<h3 id="the-bundle-documentation">The Bundle Documentation</h3>
+<h2 id="the-bundle-documentation">The Bundle Documentation</h2>
<p>Apart from the documentation of Sling on the Site and in the Wiki, it would
also be thinkable that we accompany the source modules with some documentation
and generate this using the Maven Site plugin. My tests so far for generating a
multi-module site have not been very successful. But generating the site in a
module-by-module manner might be a good thing, at least to get the per-module
JavaDoc and some more code-oriented information like Surefire Reports, fixed
bugs, etc.</p>
<p>To prepare such Bundle Documentation I added a first shot at site
generation setup to the parent project. For now, this includes the module's
JavaDoc (of course), the Surefire reports and a report on the issues fixed (or
open) with respect to some version. This site generation setup can be
configured per module with two properties:</p>
<table>
@@ -174,7 +281,7 @@ $ svn update</p>
</tbody>
</table>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1341361 by fmeschbe on Tue, 22 May 2012 08:54:04 +0000
+ Rev. 1430446 by fmeschbe on Tue, 8 Jan 2013 19:05:49 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
