<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
  "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
  <header>
    <title>How to Publish Forrest Documentation</title>
    <abstract>
      This documents the steps to update the Forrest Website.
    </abstract>
  </header>
  <body>
    <section id="About">
      <title>Introduction</title>
      <p>
        All documentation about Apache Forrest is managed as a Forrest-built
        project located in the site-author directory of forrest/trunk SVN. The
        Apache Forrest website is updated by generating static pages from the
        site-author-project and committing them to the forrest/site SVN, which
        is then 'svn checkout' on the forrest.apache.org webserver to create the
        website.
      </p>
      <p>
        See other notes for the Documentation Coordination
        <a href="site:tasks">tasks</a>.
      </p>
    </section>
    <section id="forrestbot-local">
      <title>Updating the site with a local forrestbot</title>
      <p>
        Generating and publishing the main docs is very easy using a local
        forrestbot:
      </p>
      <source>cd site-author
forrest -f publish.xml build
forrest -f publish.xml deploy</source>
      <p>
        Note: if your system username is not the same as your "svn username"
        then provide a "deploy.svn.settings" file as explained at
        <code>$FORREST_HOME/etc/publishing_our_site.txt</code>
      </p>
      <p>
        This builds the documentation locally then deploys it by committing it
        to the
        <a href="http://svn.apache.org/repos/asf/forrest/site">forrest/site
        SVN</a>.
        The svnpubsub system automatically kicks in to do the final publish step.
      </p>
      <p>
        See more detailed <a href="site:forrestbot-svn">explanation</a> of this
        procedure.
      </p>
      <p>
        Publishing documentation for a particular plugin is done by:
      </p>
      <source>cd plugins/myPluginName
$FORREST_HOME/tools/ant/bin/ant deploy-docs</source>
      <p>
        See further information in the
        <a href="site:buildPlugin">buildPlugin</a> doc.
      </p>
      <p>
        See some general notes about managing
        <a href="http://www.apache.org/dev/project-site.html">project
        websites</a>.
      </p>
    </section>
    <fixme author="open">
      This is work in progress.
    </fixme>
    <section id="OrgDoc">
      <title>Other docs</title>
      <p>
        There have been a few explantions of our docs processing on the
        forrest-dev mail list. Need to glean the info from them. Here is the
        content of some:
      </p>
      <source>
<![CDATA[
                To publish from trunk/site-author/
                
                # Make changes to sources, and then test, then commit.

                # Please, please, ensure valid xml docs. Errors will be
                # reported during the 'build' phase if you don't.
                # Also it prevents other people from working with the docs,
                # which goes against the collaborative development process.

                # You can do 'forrest validate-xdocs" beforehand or use
                # a validating editor (link: catalog.html) or for a single doc use
                # xmllint (link: catalog.html) from the command-line, e.g.
                # xmllint --noout --valid --catalogs faq.xml

                # Use the forrestbot to build and then deploy to svn.apache.org ...
                
                cd site-author
                forrest -f publish.xml build
                # ... verify files in build/forrest-docs
                forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"
                
                Now the files are in SVN at forrest/site
                Periodically the real website files are updated from there.
                You do not have to do anything else.
                
                ----------------------
                Note: The first time that you deploy, it will need to do
                a long svn checkout first.
                 ]]>
      </source>
      <p>
        Some more notes that need to be integrated above ...
      </p>
      <p>
        Note that forrestbot does not remove docs from the forrest/site SVN
        (FOR-392). So need to manually delete:
        '<code>svn delete https://svn.apache.org/repos/asf/forrest/site/.../oldDoc</code>'
        and then remove it from the forrestbot work directories: 'cd
        $FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm
        work/svn-deploy/forrest-docs/oldDoc'.
      </p>
      <p>
        The generated docs are in build/forrest-docs which is the name given to
        it in the forrestbot descriptor (site-author/publish.xml). Here is a
        trick for reviewing changes that forrestbot is ready to deploy ...
      </p>
      <source>
forrest -f publish.xml build
svn update work/svn-deploy/forrest-docs
diff -rq work/svn-deploy/forrest-docs build/forrest-docs | grep -v "\.svn" | grep differ</source>
      <p>
        If you change something that affects all pages (e.g. layout changes; navigation
        menu additions or MOTD changes that affect old "versioned docs")
        then see the note in conf/cli.xconf about temporarily not excluding
        old "docs_*" patterns.
      </p>
      <p>
        If there have been changes to tools/forrestbar then need to follow the
        instructions there to build it. Then copy its build/forrestbar.xpi to
        site-author/content/xdocs/tools/forrestbar.xpi and commit that. Then run
        forrestbot to build and deploy the site, or alternatively for a quick
        fix, just commit it to forest/site/tools (which is what forrestbot would do).
      </p>
    </section>
  </body>
</document>