For REVIEW: How to edit Help and contribute

Signed-off-by: Iain Brown Douglas <iain@browndouglas.plus.com>

4 files changed, 379 insertions, 0 deletions

diff --git a/images/BrowseComposite2.png b/images/BrowseComposite2.png
new file mode 100644
index 0000000..a739023
--- /dev/null
+++ b/images/BrowseComposite2.png
diff --git a/images/BrowseComposite3.png b/images/BrowseComposite3.png
new file mode 100644
index 0000000..d52ee6f
--- /dev/null
+++ b/images/BrowseComposite3.png
diff --git a/images/Browse_filesystem.png b/images/Browse_filesystem.png
new file mode 100644
index 0000000..d3b85b5
--- /dev/null
+++ b/images/Browse_filesystem.png
diff --git a/source/how_to_help.rst b/source/how_to_help.rst
new file mode 100644
index 0000000..7d06d2c
--- /dev/null
+++ b/source/how_to_help.rst
@@ -0,0 +1,379 @@
+===============================
+How to edit Help and contribute
+===============================
+
+.. Note::
+
+   *24 November 2013. Draft version for review.*
+
+   *TO DO: I propose a dedicated "landing page" for contributors. http://wiki.laptop.org/go/Help_Activity_refresh/0.98 will be out of date by the time this is published. Possibility of developing collaborative working model. Paragraph Contribute refers. Possibility that a page on sugarlabs wiki can be used to flag up ideas for new pages.*
+
+   *I have checked the tutorials, but would appreciate if they were independently tested.*
+
+   *Corrections, omissions, and feedback most welcome, iain at browndouglas dot plus dot com.*
+
+
+Help displays documentation for Sugar and the XO laptop. Help contains a :ref:`View source` button.
+
+This version of Help contains all the source files and images. These files can be edited within Help, and displayed. Help is now capable of producing new pages for Help, or making completely fresh documentation.
+
+Help allows internationalization of the content, by {reference required} {To what extent can this page encourage users to get involved with that?}
+
+This page aims to show how to write attractive documentation, which, if users share their work, could be used to improve Help. To contribute you only need to:
+
+* Create a development environment
+* Make changes
+* Contribute the changes
+
+Create a development environment
+--------------------------------
+
+XO Help.xo 17 already includes the source files ready to use.
+
+Alternatively, you can use git to get Help Activity with the most recent sources included. If you have the Activity Help already installed, uninstall it first. Generally an Activity is uninstalled from the F3, Home View, List, by selecting the Activity, and press Erase. Where Erase is not available, you need to delete ``Help.activity`` from the folder ``~/Activities``.
+
+The following guide assumes you ``git clone`` from your home directory. This command will collect all the required resources.
+
+::
+
+ git clone gitorious@git.sugarlabs.org:help/mainline.git
+
+You can install it in your development environment doing: :: 
+
+ cd mainline
+ ./setup.py dev
+
+You can modify any .rst file in ~/mainline/source/ directory or the images in the ~/mainline/source/images/ directory.
+
+To create the HTML files. You only need do: ::
+
+ cd mainline
+ make html
+
+If you see an error indicating that HTML cannot be built, the most likely cause is that ``python-sphinx`` is missing.
+
+To fix this, in Terminal Activity (or any terminal emulator) as root, ::
+
+ yum install python-sphinx
+
+or in Debian or Ubuntu derivatives, ::
+
+ apt-get install python-sphinx
+
+In **Sugar** you don't need restart Help to see the changes after running ``make html``, you just click with the secondary mouse button, and select reload.
+
+In any other Linux environment the output of ``make html`` is in ``~/mainline/html``, and is displayed by opening ``~/mainline/html/index.html`` in a browser.
+
+What if I break Help?
+:::::::::::::::::::::
+
+In Sugar you cannot break Help. If you start to follow these instructions and get lost or make a mistake, and Help will not display correctly, you should not worry.
+
+You should simply visit  `ASLO <http://activities.sugarlabs.org>`_ with Browse. Search for Help, and download and install a new copy of XO Help.
+
+Alternatively, experienced users might make a backup .xo before starting to work by doing: ::
+
+ ./setup.py dist_xo
+
+This will create a directory dist and inside, an .xo file.
+
+.. _Orientation:
+
+Orientation
+:::::::::::
+
+**Source**
+
+The two source folders we look at are filled initially by the download of Help.
+
+The directory ``~/mainline/source/`` contains the text files we will be altering in this guide.
+
+The directory ``~/mainline/images/`` contains all the images that are used on the various pages of Help. You can add image files to this folder, and if they are linked into documents, they will display in the *output* of the command ``make html``. 
+
+In Sugar you have the ability to inspect the source files safely, using the *View source* button on the Help icon in the Frame. See Help, :ref:`View source`
+
+**Output**
+
+The pages displayed in Activity Help are the *output* of the command ``make html``. The files are all in the folder ``~/mainline/html/``.
+
+Depending on the setup of your installation there may be a number of other folders present in the ``~/mainline/html/`` folder (for instance ``_sources``, ``_static``, and ``_images``). These are also *output files*, they could be regarded as hidden folders, and should not be edited.
+
+The key page in navigating Help is the Index or contents page. In the ``~/mainline/source/`` folder, `index.rst` is the text document which automatically provides links to all other pages in the source folder.
+
+Browse your file system
+:::::::::::::::::::::::
+
+This set of images shows how to use Browse (or any other browser) to navigate the file system.
+
+.. image :: ../images/Browse_filesystem.png
+
+Above we see Browse opened from Start new. The Browse home page is shown, and the address bar highlighted. Put the cursor in the address bar, use the right arrow key to move the cursor to the far right end of the address, or URL, and use the backspace delete key to delete "index.html". Now hit **Enter**, and the containing folder is displayed. In the same way we can backspace delete till we reach the root of the file system, and then select the "home " directory.
+
+Browse mainline
+:::::::::::::::
+
+.. image :: ../images/BrowseComposite2.png
+
+Having opened ``/home``, we navigate to ``/home/user`` then to ``/home/user/mainline``, then ``/home/user/mainline/source``, and select ``browse.rst``
+
+Browse HTML
+:::::::::::
+
+.. image :: ../images/BrowseComposite3.png
+
+In the first of these images we view the text file browse.rst by pointing the browser at the source file: ::
+
+ file:///home/your-username/mainline/source/browse.rst
+
+We can back off again and reach ``/home/user/mainline/html`, and open ``browse.html``. Now we display the *output* HTML file by pointing the browser at the html file: ::
+
+ file:///home/your-username/mainline/html/browse.html
+
+Make changes
+------------
+
+You can just write a page in simple text, perhaps with some explanatory pictures or screen-shots. Screen-shots are made in Sugar from the keyboard, by pressing the "Alt" key and 1.
+The page :doc:`/restructuredtext` gives some guidance on the features of the markup language we use. Do not be concerned with complex features, plain, simply written text will be of most use to new learners.
+
+You will have your own ideas about what you would like to change and contribute. Explaining anything, which you have struggled to learn, is likely to be of use to others, and seeing your work published gives quite a buzz!
+
+Here are a few exercises, which demonstrate making changes, and making pages.
+
+Tutorial 1 - Make a page
+::::::::::::::::::::::::
+
+We are going to make a fresh page in reStructuredText. It will not at first be connected to the index, or contents page, of Help.
+
+1. Open a new file in any text editor.
+
+2. Save the file with the name ``my_first.rst`` in ~/mainline/source . (Here we have called ``/home/your-username/mainline/source`` by the shorter, ``~/mainline/source``). Type some text onto the page. In order to give the page a title we put a line of "=" "equal" signs above and below the title like this. Leave a line of white space, then type some text. This is an example:
+
+::
+
+ =============
+ My first page
+ =============
+
+ I am going to learn to write a Help page.
+
+3. Now we want to convert our little page of text into an attractive page of Help. Open Terminal Activity (or any terminal emulator) and type,
+
+::
+
+ cd mainline
+ make html
+
+4. There will be about ten lines of output, there will be mention of errors. Read the error trace, expect to see an error line like the one below, but the final two lines here report a success.
+
+::
+
+ ~/mainline/source/my_first.rst:: WARNING: document isn't included in any toctree
+ ...
+ build succeeded, 3 warnings.
+ Build finished. The HTML pages are in ./html.
+
+The warning, "WARNING: document isn't included in any toctree" is telling us the document is not linked into the Help index yet.
+
+Tutorial 2 will fix this. It does exist and you could see what it looks like if you can find it as described above with a browser in ``~/mainline/html``.
+
+Tutorial 2 - Link page to index
+:::::::::::::::::::::::::::::::
+
+1. Backup your index file. Open Terminal Activity (or any terminal emulator) and type,
+
+::
+
+ cd mainline
+ cd source
+ cp index.rst index.rst.ori
+
+Above, we have changed directory into mainline, changed directory into source, and copied ``index.rst`` to a new file named ``index.rst.ori``
+
+2. Before proceeding make sure you are familiar with how to restore your index from the backup, in case you damage your Help index.
+
+3. Open ``~/mainline/source/index.rst`` with a text editor. Notice the line spacing (lines of white space especially) and indents. They are very important to maintain.
+
+4. Scroll down ``index.rst`` right to the bottom of the page. Put the cursor at the front of the last line. Using the arrow keys you will see that the indent is 4 "spaces", it is not "Tab".
+
+5. Put the cursor at the end of the last line. Press *Enter*, press space bar 4 times, and enter the file name you used above ``my_page.rst``. Use "Enter" and the space bar so that  you exactly copy the indentation, and line spacing as used in the other entries.
+
+6. Double check your changes to ``index.rst`` and save your changes. 
+
+7. Now we want to convert our index into HTML. Open Terminal Activity (or any terminal emulator) and type,
+
+::
+
+ cd mainline
+ make html
+
+8. The newly changed index page will now display in Help, or in your browser, once you reload the page. In Sugar you click with the secondary button, and select reload, or in a browser pointing to ``~/mainline/html/index.html`` press the reload button. In the index, or contents page, the link to your new page can be clicked to open your page "my_page.html"
+
+Tutorial 3 - Adding an image
+::::::::::::::::::::::::::::
+
+1. Open your existing page in any text editor, or create and "Title" a new page, and add it to the index.
+
+2. An image which is already in ``~/mainline/images/`` can be included by typing this on to your page.
+
+::
+
+ .. image :: ../images/Help.png
+
+The "reference line" above needs a line of white space, above and below it.
+
+3. You can add an image file in .jpg or .png format to ``~/mainline/images/``. It is best if the image does not exceed 800 pixels in width. It can be difficult to read around tall images. For this reason screen-shots 600 pixels in width may be a good compromise if the content is simple.
+
+4. If you add an image file ``my_image.png``, made in, say, Paint to ``~/mainline/images/``, then you link it into your page with:
+
+::
+
+ .. image :: ../images/my_image.png
+
+5. Now we want to convert our page with an image into HTML. Open Terminal Activity (or any terminal emulator) and type,
+
+::
+
+ cd mainline
+ make html
+
+6. The newly changed page will now display in Help, or in your browser, once you reload the page.
+
+Tutorial 4 - Write or improve a Help page
+:::::::::::::::::::::::::::::::::::::::::
+
+Decide whether you want to make a page from a fresh start, you could just start writing on a subject you know about. Alternatively experiment with improving an existing page. You could work from the text of an existing page (it might be this page) or a more simple page.
+
+1. Open ``~/mainline/source/index.rst``.
+
+2. Put the cursor at the end of the last line. Press *Enter*, press space bar 4 times, and enter a new file name, perhaps, ``my_second.rst``. Use "Enter" and the space bar so that you exactly copy the indentation, and line spacing as used in the other entries.
+
+3. Double check your changes to ``index.rst`` and save your changes.
+
+4. Open a new file in any text editor.
+
+5. Save the page as the new file name chosen above, perhaps, ``my_second.rst``.
+
+6. Type in a title like this:
+
+::
+
+ ==================
+ How I changed Help
+ ==================
+
+7. Enter your text, and save your changes.
+
+
+8. Now we want to convert our page into HTML. Open Terminal Activity (or any terminal emulator) and type,
+
+::
+
+ cd mainline
+ make html
+
+9. The newly generated page will now display in Help, or in your browser, once you reload the page.
+
+10. You can now go back to your page, and improve it.
+
+11. Again, write the changes to HTML version, with:
+
+::
+
+ cd mainline
+ make html
+
+12. You have now written your first improved page for the Activity Help. We would love it if you could share it with the Sugar community!
+
+.. _Contribute:
+
+Contribute
+----------
+
+Once you are familiar with editing, adding a page, and making or improving a Help page, you could make a page with the intention of having it published in the next version of Help.
+
+You might write a tutorial on a subject you know about.
+
+In the next version of Activity Help, better "New to Sugar" pages might be included at the beginning of Help, as a quick introduction for new Sugar learners. Contributions to be considered would be welcome.
+
+Some Activities have no easy to find instructions. If you can write even a very short introduction, it could be very useful for other Sugar learners.
+
+The  wiki page linked might have some ideas on pages, which have been requested, or which others are working on and might appreciate collaboration.
+
+What to do with your finished work
+::::::::::::::::::::::::::::::::::
+
+First of all you might briefly contact gonzalo at laptop dot org by e-mail to tell him what you would like to contribute. If you write a new page , you can send him the page (as my_page.rst) as an attachment to an e-mail explaining briefly what is attached. If new images are linked into the page, send them too.
+
+If you have improved a page, the preferred method is to submit it is as a "patch".
+
+Tutorial 5 - generate a patch
+:::::::::::::::::::::::::::::
+
+1. Let's say you decide to work on the Help page, "Switching Activities". You might back up that page before you start. Open Terminal Activity (or any terminal emulator) and type,
+
+::
+
+ cd mainline
+ cd source
+ cp switching_activities.rst switching_activities.rst.ori
+
+Above, we have changed directory into mainline, changed directory into source, and copied ``switching_activities.rst`` to a new file named ``switching_activities.rst.ori``
+
+2. Make your changes to ``switching_activities.rst``. Save your changes regularly, and check by running the ``make html`` command that the page displays nicely. Once you are happy with your work, you can generate a patch like this:
+
+::
+
+ cd mainline
+ cd source
+ diff -u switching_activities.rst.ori switching_activities.rst > switching_activities.patch
+
+3. The patch can now be sent as an e-mail attachment.
+
+4. For more information, in Terminal Activity (or any terminal emulator) type,
+
+::
+
+ man diff
+
+and
+
+::
+
+ man patch
+
+
+Reconfigure Help to show View source
+------------------------------------
+
+In Sugar as we already have a :ref:`View source` button in the frame.
+
+If you are working with this software in a browser, you can add a *View source* button, which will appear in the navigation panel on the left. You need to alter three lines in ``mainline/source/conf.py``. Each of the entries listed below comprise a comment line, starting with a"#" followed by the code line. Find each pair of lines in ``conf.py`` and change the value in the code line like this. ::
+
+
+ # Custom sidebar templates, maps document names to template names. ## Edit: Sugar default is without 'sourcelink.html'
+ html_sidebars = {'**':['localtoc.html', 'sourcelink.html']}
+
+ # If true, links to the reST sources are added to the pages. ##Edit: Sugar default is False
+ html_show_sourcelink = True
+
+ # Do not copy .rst files ##Edit: Sugar default is False
+ html_copy_source = True
+
+A disadvantage of doing this is that extra folders are created, that might be confusing at first. The command ``make html`` also takes longer to run. It is recommend not to make these changes before you are confident navigating the source and HTML folders.
+
+Further reading
+---------------
+
+|more| For more complete help on reStructuredText:
+
+.. |more| image:: ../images/more.png
+
+Quick reStructuredText, http://docutils.sourceforge.net/docs/user/rst/quickref.html, is a cheat-sheet for reStructuredText.
+
+"reStructuredText Directives" http://docutils.sourceforge.net/docs/ref/rst/directives.html by David Goodger, March 2013.
+
+Sphinx reStructuredText Primer, http://sphinx-doc.org/rest.html, a brief introduction to reStructuredText concepts and syntax.
+
+Sphinx home page, http://sphinx-doc.org/index.html.
+
+Another tutorial, http://matplotlib.org/sampledoc/.