From 7d443a246a52d89baa44c0395524398be75688a9 Mon Sep 17 00:00:00 2001 From: R0b0t1 Date: Sun, 13 Jun 2010 06:11:24 -0500 Subject: [PATCH] Proofreading docs. --- Doc/sphinx/docdoc.rst | 20 ++++++++--------- Doc/sphinx/features.rst | 2 +- Doc/sphinx/features/autoupdate.rst | 7 +++--- Doc/sphinx/features/scriptmanager.rst | 3 ++- Doc/sphinx/gettingstarted.rst | 29 ++++++++++++------------- Doc/sphinx/index.rst | 2 +- Doc/sphinx/pymml/color.rst | 2 +- Doc/sphinx/pymml/mouse.rst | 2 +- Doc/sphinx/simbaref/extensions.rst | 31 +++++++++++---------------- Doc/sphinx/troubleshooting.rst | 2 +- Doc/sphinx/whatsnew.rst | 2 +- 11 files changed, 47 insertions(+), 55 deletions(-) diff --git a/Doc/sphinx/docdoc.rst b/Doc/sphinx/docdoc.rst index 9fe93ad..ae578e6 100644 --- a/Doc/sphinx/docdoc.rst +++ b/Doc/sphinx/docdoc.rst @@ -9,22 +9,21 @@ for Simba. Documentation system -------------------- The documentation system we use is sphinx. The link to sphinx can -be found at the bottom of the page at all times. +be found at the bottom of the page. .. note:: It is important to note that there is also a database SQL fulltext engine called Sphinx, but this is not the project we use. We use the Sphinx - ``documentation system`` ( http://sphinx.pocoo.org/ ) + "documentation system" ( http://sphinx.pocoo.org/ ) Building the documentation -------------------------- -In the future, the online documentation will be refreshed every hour. +In the future, the online documentation will be refreshed every hour. However, +if you want to build the documentation yourself, you should install +``python-sphinx``. -If you want to build the documentation yourself, you should install -sphinx-python. - -Move to the ``Simba/doc/sphinx`` directory and call ``make all``. -This will place the doc in html format in ``_build/html``. +Move to the ``Simba/doc/sphinx`` directory and run ``make all``. +This will place an HTML version of the documentation in ``_build/html``. .. note:: The build instructions are for Linux only. If you want to build the doc on @@ -40,8 +39,7 @@ http://docutils.sourceforge.net/docs/user/rst/quickstart.html As stated above, the markup language is not the hard part about writing documentation; the hard part is simply coming up with good content suited for -the documentation. This process is rather self explanatory, so we will not cover -this further. +the documentation. Directory structure ~~~~~~~~~~~~~~~~~~~ @@ -53,7 +51,7 @@ then there should be no worries as to where to place your new text. However if you are writing a new chapter, then placing the file in the correct directory is something we'd like you to consider. -If you wrote a chapter for the ``Simba Reference`` or ``Scripting Reference`` +If you write a chapter for the ``Simba Reference`` or ``Scripting Reference`` or ``Features`` part of the documentation, place it in the ``simbaref``, ``scriptref`` or ``features`` folder repectively. diff --git a/Doc/sphinx/features.rst b/Doc/sphinx/features.rst index e8ee6cd..955df80 100644 --- a/Doc/sphinx/features.rst +++ b/Doc/sphinx/features.rst @@ -1,4 +1,4 @@ -Feature overview +Feature Overview ================ .. toctree:: diff --git a/Doc/sphinx/features/autoupdate.rst b/Doc/sphinx/features/autoupdate.rst index 45a84d7..c3fa80a 100644 --- a/Doc/sphinx/features/autoupdate.rst +++ b/Doc/sphinx/features/autoupdate.rst @@ -1,9 +1,8 @@ Updater in Simba ================ -A button appear, and a text message. blabla +A notice should appear in the Simba GUI, or you can alternatively +use Tools -> Update. - - -Don't forget to restart Simba when it has been updated, blabla +Don't forget to restart Simba when it has been updated! diff --git a/Doc/sphinx/features/scriptmanager.rst b/Doc/sphinx/features/scriptmanager.rst index 6d4047f..7668534 100644 --- a/Doc/sphinx/features/scriptmanager.rst +++ b/Doc/sphinx/features/scriptmanager.rst @@ -1,4 +1,5 @@ Simba Script Manager ==================== -Non technical script manager doc. +Community-created scripts will be available for download from the +Script Manager. diff --git a/Doc/sphinx/gettingstarted.rst b/Doc/sphinx/gettingstarted.rst index 4d89705..fe8e038 100644 --- a/Doc/sphinx/gettingstarted.rst +++ b/Doc/sphinx/gettingstarted.rst @@ -1,7 +1,7 @@ Getting started with Simba ========================== -This page will help you install Simba and point you at some basic Simba +This page will help you install Simba and highlight some basic Simba features. Installing Simba @@ -19,33 +19,32 @@ Simba installer Everyone can download Simba at http://wizzup.org/simba/ Go to download, and download the Simba installer. -Once it is done downloading, simple run the installer and follow the steps. +Once it is done downloading, simply run the installer and follow the steps. .. note:: Simba will install to C:/ by default; if you want to install it - somewhere else, make sure you select a different location in the installer. + somewhere else, make sure you select a different location! -Once you have installed Simba, make sure you update it at least once, -to get a more recent version of Simba. - -Simba will tell you there is an update and an update button will appear. -Alternatively you can update Simba using Tools -> Update. +Simba will probably tell you there is an update available. In this case, an +update button will appear. Alternatively you can update Simba using +Tools -> Update. .. note:: Updating Simba regularly is recommended. -Simba binary +Simba Binary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is harder and not recommended. Steps on how to do this will follow later. - -For now, simply stick to the installer and update -Simba after the install has completed. +This is not the recommended method due to some computers having problems +with FreePascal and Lazarus. However, all you must do is install FreePascal +and Lazarus (from repos or non) and open the Simba project file located +in the repository (retrieve the project with git). +You should then see a prominent "compile" button. Yay! Setting up SRL 4 with Simba --------------------------- -If you were using the :ref:`simba-installer` then you can simple enable the +If you were using the :ref:`simba-installer` then you can simply enable the ``SRL Updater`` extension. (Go to View -> Extensions and enable srl.sex) This is the only supported way. You can simply do a svn checkout on the srl @@ -63,5 +62,5 @@ Scripts can be downloaded with the Script Manager, in Tools -> Script Manager. Troubleshooting --------------- -If you run into problems that are not mentioned here, make sure you check out +If you run into problems that are not mentioned here, make sure you look at the :ref:`Troubleshooting` page. diff --git a/Doc/sphinx/index.rst b/Doc/sphinx/index.rst index cf49dda..826b217 100644 --- a/Doc/sphinx/index.rst +++ b/Doc/sphinx/index.rst @@ -6,7 +6,7 @@ Welcome to the Simba documentation! =================================== -Welcome to the Documentation of the Simba project. +Welcome to the Documentation for the Simba project. Contents: diff --git a/Doc/sphinx/pymml/color.rst b/Doc/sphinx/pymml/color.rst index af2efaf..e9eee22 100644 --- a/Doc/sphinx/pymml/color.rst +++ b/Doc/sphinx/pymml/color.rst @@ -1,7 +1,7 @@ PyMML Color =========== -This is the PyMML color class. +This is the PyMML Color class. .. automodule:: mmlcolor :members: diff --git a/Doc/sphinx/pymml/mouse.rst b/Doc/sphinx/pymml/mouse.rst index d5e42e8..b96f494 100644 --- a/Doc/sphinx/pymml/mouse.rst +++ b/Doc/sphinx/pymml/mouse.rst @@ -1,7 +1,7 @@ PyMML Mouse =========== -This is the PyMML mouse class. +This is the PyMML Mouse class. .. automodule:: mmlmouse :members: diff --git a/Doc/sphinx/simbaref/extensions.rst b/Doc/sphinx/simbaref/extensions.rst index fddb22f..9479b06 100644 --- a/Doc/sphinx/simbaref/extensions.rst +++ b/Doc/sphinx/simbaref/extensions.rst @@ -1,17 +1,15 @@ Writing Simba Extensions ======================== -Simba extensions are scripts written in PascalScript that can be embedded into -Simba. Purposes vary from updaters to full blown dtm and bitmap editors. +Simba extensions are scripts written for the interpreter that can be embedded into +Simba. Purposes vary from updaters to editors. .. FIXME link to dtm and bitmap How they work ------------- -Extensions are event based. This means you don't have some ``loop`` in your -program that never ends and does all the logic for you. When a system is event -based, you implement some functions and those are called on a certain event. +Extensions are event based. Functions from the extension are called based on external events. Extension core hooks -------------------- @@ -29,7 +27,7 @@ Called when the Extension is initialized. procedure init; begin; - Writeln('Init your extension here.'); + Writeln('Initialize your extension here.'); end; If you want to add a button to the menu, do it now. @@ -79,7 +77,7 @@ Called upon freeing the extension. Usually this means that Simba is closed. procedure free; begin if started then - writeln('Init was called'); + writeln('Free() was called'); end; From the SRL updater extension: @@ -91,7 +89,7 @@ From the SRL updater extension: if (started) then Timer.Enabled := False; { Freeing the components is not needed, as they will be freed - upon the freeing of Simba. } + upon the closure of Simba. } end; attach @@ -187,8 +185,8 @@ onColourPick onScriptStart ~~~~~~~~~~~~~ -Special cases -------------- +Special Cases +~~~~~~~~~~~~~ Multiple extensions hooking onto the same event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -196,23 +194,20 @@ Multiple extensions hooking onto the same event So what happens when multiple extensions hook onto the same event/hook? The behaviour is currently defined, but prone to change in the near future. -Currently simply all extensions are called. The order is simple the order they -were loaded. +Currently all extensions are called in the order they were loaded. The behaviour will probably change to something like the following: - In loading order, extensions are called with the proper hook. As soon as one - extension returns something that is not equal to zero, it will bail and stop - calling other events. Apart from not calling other events, the hook will not - allow the action it is bound to. + In the order they were loaded, call any available extensions. The first + extension to return non-zero terminates the calling loop. Pitfalls -------- Extensions can be very dangerous in the sense that they run on the main thread -of Simba, it is very simple to crash Simba or make it infinitely loop. There is +of Simba, it is very easy to crash Simba or make it hang. There is no way to prevent this, so make sure to check what you're doing before you try -your own (or someone else's extension) +your own (or someone else's) extension. diff --git a/Doc/sphinx/troubleshooting.rst b/Doc/sphinx/troubleshooting.rst index 3423de7..939bdea 100644 --- a/Doc/sphinx/troubleshooting.rst +++ b/Doc/sphinx/troubleshooting.rst @@ -4,7 +4,7 @@ Troubleshooting =============== This is a general troubleshooting page and will hopefully cover all potential -problem you may run into. +problems you may encounter. Problems when installing or starting Simba ------------------------------------------ diff --git a/Doc/sphinx/whatsnew.rst b/Doc/sphinx/whatsnew.rst index 38033ba..6e1bcc4 100644 --- a/Doc/sphinx/whatsnew.rst +++ b/Doc/sphinx/whatsnew.rst @@ -2,7 +2,7 @@ What's new in Simba? ==================== Currently Simba is still in its beta stages; this includes the documentation. -You will probably notice some parts of the documentation aren't finished or just +You will probably notice some parts of the documentation aren't finished or are just plain missing. So what's new in Simba? This documentation system.