Title:     Website editing
Notice:    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.

This HowTo documentation will show the needed steps to edit the Apache Rave
website. This includes creation of new pages, modification, and deletion - for files
and sub-directories.

## How it works in general

The website is hosted in a Content Management System (CMS). You will not edit the
HTML pages directly. The actual edit is split into two steps:

 1. First you edit the content which is provided as [Markdown text][1] (mdtext).
    This will be committed into the staging section (see the SVN commit mail with
    your log message) and automatically build HTML files out of the the mdtext files
    (see the commit mail with "Staging update by buildbot" as log messge).

 2. Second you need to publish the staging part to the production section (see the
    commit mail with "Publishing merge to Apache Rave site by <your Apache ID>"
    as log message).

## What do you prefer: Working via command line or in the browser?

### Via command line

It is assumed that you have already checked out the code from the SVN repository
(http://svn.apache.org/repos/asf/rave/).

Edit the file via your favorite editor like vi and finally commit via SVN:

     vi myfile.mdtext
     svn ci -m"My log message" myfile.mdtext

Now wait a few seconds so that the entire website can be rebuilt. Then:

    curl -sL http://s.apache.org/cms-cli | perl

If this does not work on your local machine just do it on "people.apache.org" by
executing this:

    ssh -t <user>@people.apache.org publish.pl rave <your Apache ID>

### Editing in the browser

#### Prerequisites

##### Browser bookmark

Normally you see the webpage in your browser. To update this page with an
inline-editor and little preview you need to add a link as bookmark to your browser
(more information see [here][2]).

Drag this [Apache CMS] [3] bookmarklet to your browser's toolbar.

##### Apache ID

Furthermore, you need an Apache ID to authenticate to the system.

#### Starting

Browse to the respective webpage or directory you would like to edit and click on
the bookmark. Now click on the [Edit this directory] link on the top. The following
is displayed as content from the CMS.

#### Edit an existing webpage

Click on the actions link [Edit] in the appropriate table cell for editing the
favorite file. If the file is not in this directory but in a subdir, just click on
the directory name (e.g., "docs/") to enter this directory.

Now you should see a new webpage with a 4 fields:

 1. Upper left is the inline editor for text in markdown syntax.
 2. Upper right shows the written text as a permanent preview or as HTML source code.
 3. Below the editor you can enter a log message.
 4. Enter a general header text, e.g., the license of the entered text.

When you have finished writing your text, check the "Log message" box, enter a
commit message and click on [Submit].

#### Create a new webpage

When in the correct directory, at the top enter a name for the new text file (e.g.,
"my-file.mdtext"). Now you enter your text (see topic above).

#### Create new subdirectory

When in the correct directory, at the top enter a name for the new directory (e.g.,
"my-dir/"). Make sure you entered a trailing "/"!

#### Delete a webpage or subdirectory

When in the correct directory, click on the actions link [Delete] in the appropriate
table cell and enter a commit message. Finally click on [Submit].

#### How to put into production?

After you have edited your files and/or directories, you need now to pubish your
modifications into production. For this please click on the link
[Publish site] on the top of the webpage. Enter a commit message on click on [Submit].

### Links

[CMS Documentation Reference][4]

  [1]:  http://daringfireball.net/projects/markdown/syntax
  [2]:  https://cms.apache.org/#bookmark
  [3]:  javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))
  [4]:  http://www.apache.org/dev/cmsref.html