How-to write english documentation for Yanel

The purpose of this tutorial is to get started on Yanel by demonstrating a way to to create, edit and contribute documentation. Please keep in mind that Yanel is functional but not polished.

This tutorial assumes that you've installed the source distibution of Yanel with support for SSL in /usr/local/wyona and are able to view content in your Browser. (If you are using IE9 you might not be able to edit with one of the provided editors.)

Create the new page/resource

1. Start Yanel.
2. Visit http://127.0.0.1:8080/yanel/ or http://localhost:8080/yanel/.
3. Click on the 'Yanel Website' link in the Registered Realms section.
4. Click on 'Learn more about Yanel'.
5. Click on 'Documentation'.
6. Click on the link 'Toolbar' at the bottom of the page. You will be redirected a login page for the Yanel Website realm.
7. Enter 'alice' as your Username and 'levi' as your password.
8. After successfully logging in you will be redirected to the Documentation site with the additional Yanel 'Toolbar' on the top.
9. Take a moment to consider how your contribution fits into the existing documentation structure.
   You need to decide what page/resource type you want to create, where it will be placed and how to link to it.
   For this tutorial, we will create a new tutorial called 'Adding Some Content' which will be placed at
   http://127.0.0.1:8080/yanel/yanel-website/en/documentation/tutorials/add-some-content/index.html
10. Select in the Yanel 'menu': file - new - Standard Page (XHTML)
11. You are redirected to the first step of creating a new page.
    
    In the 'title:' property text box enter the title that you would like to have for the page Adding some content.
    
    In 'Save as:' use the directory tree to navigate to where the new content is to be placed. For this tutorial this means, /en/documentation/
    
    Be very careful as there are currently no warnings about overwriting. If you do overwrite something, you may want to make
    use of git's revert commands to restore what was overwritten.
    
    In the 'New name:' text box enter tutorials/add-some-content/index.html
    
    Review your work and the click on the 'Save new resource' button. This will create the resource and move you to a confirmation and summary page.
12. Now that you've created the new page/resource, you may view it by clicking on the link on the confirmation/summary page.

Edit the content

There are two possibilities two edit your page. Either you alter the page in your browser or you alter the source file directly. First we will have a look at how to use the editors.

1. Using the editors

• Choose one of the editors provided in the Yanel 'menu'.
1. Select in the Yanel 'menu': edit - open with - WYSIWYG editor - edit page with XXX
2. Now you need to decide if you prefer to edit your page with Xinha or tinyMCE.
3. According to your previous decision your document will be loaded into the editor interface.
4. Edit the document by exploring the facilities provided by the editor.

2. Altering the source file

1. Open the "conf" folder in your YANEL_HOME directory. (cd .../YANEL_HOME/conf)
2. There you should have a look at the "realms.xml" file. This file helps you to locate the repository you are looking for. Follow the path enclosed by the <config ... />-tag.
   (Of course consider the <config>-tag embedded by the realm-tag having the right "id".)
3. In this directory you will find another "realm.xml" file. It tells you (embedded by the <data>-tag) where the data is saved.
4. To find the source file, follow the directories, which are equal to the tree structure of the navigation.
5. Open the source file. It contains html. Create/Edit the content as you see fit.

Congratulations! You've created and edited some new content in Yanel.

 

Contribute to the Yanel documentation

If you are really working on documentation for Yanel and you have commit privileges for the project you will need to use git to add the content you just created. One way of doing this is to open a shell and use the following sequence of commands:

cd /usr/local/wyona/yanel-trunk/src/realms/yanel-website  
egrep -rio 'Adding some content' *

As you don't really want to commit the results of this tutorial to the Yanel repository at Wyona, you should remove your local modifications

asdfafdasfasfasf

If you are not a commiter but have created some documentation, please create a patch.

If you are really adding documentation to Yanel, you will need to either commit a change that links to your work or submit a patch that offers a change that will link to your work.