Author: buildbot
Date: Sun Feb  4 13:20:53 2018
New Revision: 1024817

Log:
Production update by buildbot for tapestry

Modified:
    websites/production/tapestry/content/cache/main.pageCache
    websites/production/tapestry/content/confluence-site-setup.html

Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/tapestry/content/confluence-site-setup.html
==============================================================================
--- websites/production/tapestry/content/confluence-site-setup.html (original)
+++ websites/production/tapestry/content/confluence-site-setup.html Sun Feb  4 
13:20:53 2018
@@ -136,7 +136,7 @@
 </div>
 
 
-<h1 id="ConfluenceSiteSetup-Overview">Overview</h1><p>Most of the web site and 
documentation (with the notable exception of the Javadoc API pages) are kept in 
Confluence.</p><p>Since the Confluence instance at <a  class="external-link" 
href="https://cwiki.apache.org/confluence/";>https://cwiki.apache.org/confluence/</a>
 isn't capable of handling a lot of incoming requests, all wiki spaces are 
statically exported. The SiteExporter program is responsible for that. Once a 
page in Confluence changes, that page gets re-exported automatically.</p><h2 
id="ConfluenceSiteSetup-HowSiteExporterworks">How SiteExporter 
works</h2><p><em>For more details see the <a  class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/README";>SiteExporter
 README</a>.</em></p><p>SiteExporter is a command-line Java program that is run 
hourly (currently at 19 minutes after the hour) from Apache's BuildBot. It 
makes a web service call to Confluence (to its RSS feed, actually) to get
  a list of pages that have changed since the last run, and the HTML-formatted 
export of those pages. For each, it post-processes the file (described below). 
Finally, SiteExporter commits all changed HTML files into Tapestry's part of 
the Apache Subversion repository, which (nearly instantly) makes it available 
to the public at <a  class="external-link" 
href="http://tapestry.apache.org";>http://tapestry.apache.org</a>, and commit 
emails are sent to Tapestry's "commits" mailing list.</p><p>Attachments (to 
Confluence pages) are exported in roughly the same way.</p><p>The time between 
saving a change in Confluence and seeing the result on the public site is at 
most 1 hour, depending on when you do it. If you save a change at 18 minutes 
after the hour you'll see the change in about a minute. If you publish it at 20 
minutes after the hour then you'll have to wait almost an hour.</p><div 
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" 
rowspan="1" class="confluen
 ceTd"><p>HTML files in SVN</p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><a  class="external-link" 
href="https://svn.apache.org/repos/infra/websites/production/tapestry";>https://svn.apache.org/repos/infra/websites/production/tapestry</a></td></tr><tr><td
 colspan="1" rowspan="1" class="confluenceTd"><p>Cache File</p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><a  class="external-link" 
href="https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache";>https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache</a></td></tr><tr><td
 colspan="1" rowspan="1" class="confluenceTd"><p>SiteExporter 
source</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a  
class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk";>https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk</a></td></tr><tr><td
 colspan="1" rowspan="1" class="confluenceTd"><p>Velocity template</p></t
 d><td colspan="1" rowspan="1" class="confluenceTd"><a  class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm";>https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm</a></td></tr></tbody></table></div><h3
 id="ConfluenceSiteSetup-Post-processingHTMLPages">Post-processing HTML 
Pages</h3><p>HTML pages exported from Confluence are post-processed in several 
ways before being committed to SVN. Here are just a few of the things going 
on:</p><ul><li>Tagsoup is used to clean up the HTML.</li><li>The breadcrumb 
links are updated.</li><li>Empty paragraph (&lt;p&gt;) tags are removed from 
the top of the page.</li><li>{code} macro output (code examples) are detected, 
and SyntaxHighlighter JavaScript links are added to the page when 
needed.</li><li>{include} tags (when one Confluence page includes another) are 
detected, causing the <em>including</em> page to be regenerated 
autoamtically.</li><li>{children} tags ar
 e also detected and handled</li></ul><h2 
id="ConfluenceSiteSetup-ManualIntervention">Manual Intervention</h2><p>You can 
cause the <em>whole site</em> to be republished by deleting the main.pageCache 
file (above) in the subversion repo. This is usually only needed after changing 
the template.</p><h2 
id="ConfluenceSiteSetup-ChangingSiteExporteritself">Changing SiteExporter 
itself</h2><p>Currently the SiteExporter source code is an unmodified copy of a 
program of the same name written by Dan Kulp for the Apache CXF project and 
also used by Camel, Geronimo, and Struts (and possibly others). It can be 
customized, but proceed with caution, because any customizations will make it 
harder to pull in future changes from the original CXF SiteExporter code. The 
CXF SiteExporter is likely to change as Confluence versions change.</p><p>To 
pick up changes to the original CXF SiteExporter code, just compare <a  
class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trun
 k/src/main/java/org/apache/cxf/cwiki">the Tapestry source code</a> with <a  
class="external-link" 
href="http://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/";>the
 CXF source code</a>.</p><hr><h1 
id="ConfluenceSiteSetup-WikiFormattingGuidelines">Wiki Formatting 
Guidelines</h1><ul><li>Precede annotation names with '@'. If the annotation 
name is hyperlinked, put the '@' character <em>outside</em> of the link: 
@[AnnotationType|http://...AnnotationType.html]</li><li>The first reference to 
a type on a page should be a link to <a  class="external-link" 
href="http://tapestry.apache.org/current/apidocs/";>http://tapestry.apache.org/current/apidocs/</a>...
 (or the component reference)</li><li>Treat the page title as if it were an h0. 
element, and put top level sections within the page as h1.</li><li>Page names 
as headings should have All Words Captialized.</li><li>For other headings, only 
the first word of multi-word headings should be capitalized, e.g. "h2. Naming 
conven
 tions" (following Wikipedia)</li><li>Use <code>code</code> font for method and 
property names: <code>myProperty</code>, <code>someMethod()</code>.</li><li>Use 
the default font for Class names (qualified or not).</li><li>Use the default 
font for path names.</li><li>Use {code} for listings, not 
{noformat}.</li><li>Use {noformat} for console output.</li><li>Images and 
diagrams should be small-sized thumbnails, centered, with no 
border.</li><li>Use the <a  href="confluence-site-setup.html">Since and 
Deprecated</a> macros to mark new or deprecated features.</li><li><em>Proposed: 
Each page should include explicit links to its child pages. Don't rely on the 
"Child Pages" links at the bottom, which don't carry over to the exported 
site.</em></li><li><em>Proposed: In pages other than the User Guide pages, 
subsections that briefly discuss topics that are more fully covered in the User 
Guide should lead with a "Main Article: [Foo]" line, where Foo is the name of 
the page in the User Guide. Exa
 mple: the "Template Localization" section of <a  
href="confluence-site-setup.html">Confluence Site 
Setup</a></em></li><li><em>Proposed: User Guide pages should generally start 
with a right-floated "Related Articles" box that provides links to related 
content in the FAQ, Cookbook, Cheat Sheets, etc. <a  
href="confluence-site-setup.html">Example</a></em></li><li><em>Proposed: The 
lead paragraph should generally lead with the title word or phrase in bold 
(following Wikipedia)</em></li></ul><h1 
id="ConfluenceSiteSetup-Websitestructure">Website structure</h1><p>The <a  
href="confluence-site-setup.html">Confluence Site Setup</a> page includes the 
<a  href="confluence-site-setup.html">Confluence Site Setup</a> and <a  
href="confluence-site-setup.html">Confluence Site Setup</a> pages as well as 
the blog posts. Most other pages are just plain pages and may or may not 
include other parts. In addition the <a  
href="confluence-site-setup.html">Confluence Site Setup</a>, <a  
href="confluence-sit
 e-setup.html">Confluence Site Setup</a> and <a  
href="confluence-site-setup.html">Confluence Site Setup</a> pages 
exist.</p><p>Our SiteExporter template (described above) glues everything 
together. It adds the contents of the <a  
href="confluence-site-setup.html">Confluence Site Setup</a> and <a  
href="confluence-site-setup.html">Confluence Site Setup</a> pages in the 
appropriate places and on all pages except the <a  
href="confluence-site-setup.html">Confluence Site Setup</a> page. It also adds 
the contents of the <a  href="confluence-site-setup.html">Confluence Site 
Setup</a> page as well as the breadcrumbs navigation.</p><div 
class="confluence-information-macro confluence-information-macro-warning"><span 
class="aui-icon aui-icon-small aui-iconfont-error 
confluence-information-macro-icon"></span><div 
class="confluence-information-macro-body"><p>HLS: I've noticed that pages with 
footnotes that are combined with the {include} macro do not render correctly 
... the footnote numbers an
 d anchors reset back to 1 for each included page. Perhaps there's a way to fix 
that with the template?</p></div></div><h1 
id="ConfluenceSiteSetup-Updatingthetemplate">Updating the template</h1><p>You 
must be a Tapestry committer or otherwise have write access to the subversion 
repository (see link above).</p><p>To edit the template:</p><ol><li>check out 
the SiteExporter source project (see link above)</li><li>find and edit the 
template.vm file</li><li>commit your changes</li></ol></div>
+<h1 id="ConfluenceSiteSetup-Overview">Overview</h1><p>Most of the web site and 
documentation (with the notable exception of the Javadoc API pages) are kept in 
Confluence.</p><p>Since the Confluence instance at <a  class="external-link" 
href="https://cwiki.apache.org/confluence/";>https://cwiki.apache.org/confluence/</a>
 isn't capable of handling a lot of incoming requests, all wiki spaces are 
statically exported. The SiteExporter program is responsible for that. Once a 
page in Confluence changes, that page gets re-exported automatically.</p><h2 
id="ConfluenceSiteSetup-HowSiteExporterworks">How SiteExporter 
works</h2><p><em>For more details see the <a  class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/README";>SiteExporter
 README</a>.</em></p><p>SiteExporter is a command-line Java program that is run 
hourly (currently at 19 minutes after the hour) from Apache's BuildBot. It 
makes a web service call to Confluence (to its RSS feed, actually) to get
  a list of pages that have changed since the last run, and the HTML-formatted 
export of those pages. For each, it post-processes the file (described below). 
Finally, SiteExporter commits all changed HTML files into Tapestry's part of 
the Apache Subversion repository, which (nearly instantly) makes it available 
to the public at <a  class="external-link" 
href="http://tapestry.apache.org";>http://tapestry.apache.org</a>, and commit 
emails are sent to Tapestry's "commits" mailing list.</p><p>Attachments (to 
Confluence pages) are exported in roughly the same way.</p><p>Unfortunately, 
wiki pages with embedded images will export with &lt;img&gt; tags pointing to 
the origial cwiki.apache.org URLs, unless you manually change the image in the 
Confluence page to be linked to the exported static image file. This has been 
done for the banner image, but not every embedded image.</p><p>The time between 
saving a change in Confluence and seeing the result on the public site is at 
most 1 hour, dependi
 ng on when you do it. If you save a change at 18 minutes after the hour you'll 
see the change in about a minute. If you publish it at 20 minutes after the 
hour then you'll have to wait almost an hour.</p><div class="table-wrap"><table 
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p>HTML files in SVN</p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><a  class="external-link" 
href="https://svn.apache.org/repos/infra/websites/production/tapestry";>https://svn.apache.org/repos/infra/websites/production/tapestry</a></td></tr><tr><td
 colspan="1" rowspan="1" class="confluenceTd"><p>Cache File</p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><a  class="external-link" 
href="https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache";>https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache</a></td></tr><tr><td
 colspan="1" rowspan="1" class="confluenceTd"><p>SiteExporter s
 ource</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a  
class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk";>https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk</a></td></tr><tr><td
 colspan="1" rowspan="1" class="confluenceTd"><p>Velocity template</p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><a  class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm";>https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm</a></td></tr></tbody></table></div><h3
 id="ConfluenceSiteSetup-Post-processingHTMLPages">Post-processing HTML 
Pages</h3><p>HTML pages exported from Confluence are post-processed in several 
ways before being committed to SVN. Here are just a few of the things going 
on:</p><ul><li>Tagsoup is used to clean up the HTML.</li><li>The breadcrumb 
links are updated.</li><li>Empty paragraph (&lt;p&gt;) tags are removed from 
the top of the p
 age.</li><li>{code} macro output (code examples) are detected, and 
SyntaxHighlighter JavaScript links are added to the page when 
needed.</li><li>{include} tags (when one Confluence page includes another) are 
detected, causing the <em>including</em> page to be regenerated 
autoamtically.</li><li>{children} tags are also detected and 
handled</li></ul><h2 id="ConfluenceSiteSetup-ManualIntervention">Manual 
Intervention</h2><p>You can cause the <em>whole site</em> to be republished by 
deleting the main.pageCache file (above) in the subversion repo. This is 
usually only needed after changing the template.</p><h2 
id="ConfluenceSiteSetup-ChangingSiteExporteritself">Changing SiteExporter 
itself</h2><p>Currently the SiteExporter source code is an unmodified copy of a 
program of the same name written by Dan Kulp for the Apache CXF project and 
also used by Camel, Geronimo, and Struts (and possibly others). It can be 
customized, but proceed with caution, because any customizations will make it ha
 rder to pull in future changes from the original CXF SiteExporter code. The 
CXF SiteExporter is likely to change as Confluence versions change.</p><p>To 
pick up changes to the original CXF SiteExporter code, just compare <a  
class="external-link" 
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/src/main/java/org/apache/cxf/cwiki";>the
 Tapestry source code</a> with <a  class="external-link" 
href="http://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/";>the
 CXF source code</a>.</p><hr><h1 
id="ConfluenceSiteSetup-WikiFormattingGuidelines">Wiki Formatting 
Guidelines</h1><ul><li>Precede annotation names with '@'. If the annotation 
name is hyperlinked, put the '@' character <em>outside</em> of the link: 
@[AnnotationType|http://...AnnotationType.html]</li><li>The first reference to 
a type on a page should be a link to <a  class="external-link" 
href="http://tapestry.apache.org/current/apidocs/";>http://tapestry.apache.org/current/apidocs/</a>...
 (or the 
 component reference)</li><li>Treat the page title as if it were an h0. 
element, and put top level sections within the page as h1.</li><li>Page names 
as headings should have All Words Captialized.</li><li>For other headings, only 
the first word of multi-word headings should be capitalized, e.g. "h2. Naming 
conventions" (following Wikipedia)</li><li>Use <code>code</code> font for 
method and property names: <code>myProperty</code>, 
<code>someMethod()</code>.</li><li>Use the default font for Class names 
(qualified or not).</li><li>Use the default font for path names.</li><li>Use 
{code} for listings, not {noformat}.</li><li>Use {noformat} for console 
output.</li><li>Images and diagrams should be small-sized thumbnails, centered, 
with no border.</li><li>Use the <a  href="confluence-site-setup.html">Since and 
Deprecated</a> macros to mark new or deprecated features.</li><li><em>Proposed: 
Each page should include explicit links to its child pages. Don't rely on the 
"Child Pages" links at th
 e bottom, which don't carry over to the exported 
site.</em></li><li><em>Proposed: In pages other than the User Guide pages, 
subsections that briefly discuss topics that are more fully covered in the User 
Guide should lead with a "Main Article: [Foo]" line, where Foo is the name of 
the page in the User Guide. Example: the "Template Localization" section of <a  
href="confluence-site-setup.html">Confluence Site 
Setup</a></em></li><li><em>Proposed: User Guide pages should generally start 
with a right-floated "Related Articles" box that provides links to related 
content in the FAQ, Cookbook, Cheat Sheets, etc. <a  
href="confluence-site-setup.html">Example</a></em></li><li><em>Proposed: The 
lead paragraph should generally lead with the title word or phrase in bold 
(following Wikipedia)</em></li></ul><h1 
id="ConfluenceSiteSetup-Websitestructure">Website structure</h1><p>The <a  
href="confluence-site-setup.html">Confluence Site Setup</a> page includes the 
<a  href="confluence-site-setup.htm
 l">Confluence Site Setup</a> and <a  
href="confluence-site-setup.html">Confluence Site Setup</a> pages as well as 
the blog posts. Most other pages are just plain pages and may or may not 
include other parts. In addition the <a  
href="confluence-site-setup.html">Confluence Site Setup</a>, <a  
href="confluence-site-setup.html">Confluence Site Setup</a> and <a  
href="confluence-site-setup.html">Confluence Site Setup</a> pages 
exist.</p><p>Our SiteExporter template (described above) glues everything 
together. It adds the contents of the <a  
href="confluence-site-setup.html">Confluence Site Setup</a> and <a  
href="confluence-site-setup.html">Confluence Site Setup</a> pages in the 
appropriate places and on all pages except the <a  
href="confluence-site-setup.html">Confluence Site Setup</a> page. It also adds 
the contents of the <a  href="confluence-site-setup.html">Confluence Site 
Setup</a> page as well as the breadcrumbs navigation.</p><div 
class="confluence-information-macro confluence-
 information-macro-warning"><span class="aui-icon aui-icon-small 
aui-iconfont-error confluence-information-macro-icon"></span><div 
class="confluence-information-macro-body"><p>HLS: I've noticed that pages with 
footnotes that are combined with the {include} macro do not render correctly 
... the footnote numbers and anchors reset back to 1 for each included page. 
Perhaps there's a way to fix that with the template?</p></div></div><h1 
id="ConfluenceSiteSetup-Updatingthetemplate">Updating the template</h1><p>You 
must be a Tapestry committer or otherwise have write access to the subversion 
repository (see link above).</p><p>To edit the template:</p><ol><li>check out 
the SiteExporter source project (see link above)</li><li>find and edit the 
template.vm file</li><li>commit your changes</li></ol></div>
       </div>
 
       <div class="clearer"></div>


Reply via email to