#############################################################################
#    Copyright 2011 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.
#############################################################################

HOWTO for Apache OpenNLP Web Site
=================================

This HOWTO describes how the Apache OpenNLP website
can be changed, tested and deployed.


Working on the Website
======================
The website is written in Markdown with inline HTML
and uses CSS for styling.

The website has a menu on the left side, this
menu is defined in the templates/sidenav.mdtext file,
to change the item in the menu edit this file.

All the content pages, css files, images, etc. is located in the
content/ folder.

There are a few things which should taken into account
to change the website:
- Make sure you understand Markdown, the following link
  gives an introduction to it:
  http://daringfireball.net/projects/markdown/basics

- The Markdown can be mixed with HTML, do this if the
  Markdown syntax limits you, here and there you can find
  samples of that in our pages.

- Ensure that the files are encoded as UTF-8, depending
  on your platform your editor might not use UTF-8 to open the files.

- Images are located in content/images, when you create
  new images ask on the mailing list where to put original design
  resources, which might be needed in the future to work on the image

- Do all styling with the help of the opennlp.css stylesheet

- To render the Markdown into html without checking in the modifcations:
  * http://www.apache.org/dev/cmsref.html#local-build 

Deploying
=========
The website must be manually deployed via the publish
link inside the cms.apache.org page.

Always follow these steps to to publish the site:
- Test the modifications on the staging site:
  opennlp.staging.apache.org/
- Ensure the produced HTML and CSS is valid with
  the W3C validation tools:
  http://validator.w3.org/
  http://jigsaw.w3.org/css-validator/
- If there are issues please correct them and
  repeat from beginning
- Login to cms.apache.org with your committer login
- Search for "opennlp" in the list and click on
  "Publish opennlp site".
- Fill in a short description about the changed content
  into the "Log Message" text area. The Log Message will
  used as subversion commit message and should contain all
  involved jira issue ids. The jira issues are important,
  they the make change to the website traceable.
- After the website is deployed please test again that it
  appears as expected.