How-to write english documentation for Yanel using Yulup

(Last updated March 4, 2008. Tutorial written using Yanel revision 32725 and Yulup 0.3.1-r27430)

The purpose of this tutorial is to demonstrate a way to to create, edit and contribute documentation. Please keep in mind that Yanel and Yulup are both functional but not polished.

This tutorial assumes that you've:

This tutorial was created using the methods described in this tutorial.

Create the new resource

  1. At http://127.0.0.1:8080/yanel/ click on 'Turn on toolbar'. You should now see a Yanel menu at the top of the page.
  2. Click on the 'Yanel Website' link in the Registered Realms section.
  3. Click on 'Learn more about Yanel'.
  4. Click on 'Documentation'.
  5. Take a moment to consider how what you are intending to add fits into the existing documentation structure.
    You need to decide what 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
  6. On the Yanel menu, select 'File-New-Standard page (XHTML)' which will redirect you to a login page for the Yanel Website realm.
  7. You may login with 'alice', 'levi'. After successfully logging in you will be redirected to Step 1 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 subversion's revert command 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.
  8. Now that you've created the new resource, you may view it by clicking on the link on the confirmation/summary page.

Edit the content

  1. To start the Yulup editor, click on the Yulup icon on the upper right hand corner of the Firefix window and select 'Login'.
    You many login using 'alice', 'levi'.
  2. Once again click on the Yulup icon and select 'Checkout and Edit "index.html"' This will load the document into the Yulup editor interface.
  3. Edit the document by exploring what Yulup can do. The global.css for the yanel-website realm has a div class called 'instructions' 
    <div class="instructions">
    that you may add via the 'Source' view in Yulup after the <body> tag (or elsewhere) which will then style <li> and <pre>.

    When you are done click on the diskette icon on the Yulup toolbar and select 'Check back in to CMS and exit' to save and commit your changes.
  4. Congratulations! You've created and edited some new content in Yanel using Yulup.

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 subversion 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' *
This will allow you to find what you created within the file system - remember to grep for a string that is likely unique to what you've created.

When writing this tutorial, egrep returned: 
content/9e6fb7cd-8e79-431c-8d81-0cad8bb5eeed:Adding some content
Adding some content
content/9e6fb7cd-8e79-431c-8d81-0cad8bb5eeed.yarep/revisions/1204347225811/content:Adding some content
Adding some content
You will notice that Yulup makes use of Yarep as a data abstraction layer which introduces version control for the resource (content) you created.

To add this content to the Yanel subversion repository at Wyona, you need to add the current version of the content: 
svn add content/9e6fb7cd-8e79-431c-8d81-0cad8bb5eeed
the repository for the content: 
svn add content/9e6fb7cd-8e79-431c-8d81-0cad8bb5eeed.yarep
and the representation within the file system: 
svn add paths/en/documentation/tutorials/add-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 
svn del --force content/9e6fb7cd-8e79-431c-8d81-0cad8bb5eeed
svn del --force content/9e6fb7cd-8e79-431c-8d81-0cad8bb5eeed.yarep/
svn del --force paths/en/documentation/tutorials/add-some-content

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.