Sugar on a Stick/Documentation SOP
Starting with the upcoming SoaS version (release date: 2010-05-11), a good amount of the related documentation will be created through publican. This SOP describes how to contribute changes to the documentation.
Viewing the Documentation
You can view a reasonably up-to-date version of the files here:
This is not a permanent location (the URLs above will likely be moving between now and May 2010), and these files may not be completely up-to-date; we are currently obtaining a more permanent infrastructure solution, but the links should suffice at present.
Contributing Content to the Documentation
Checking out the latest Version
Clone the GIT repository with the Sugar on a Stick documentation from GIT by running:
git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs
Apply your Changes
- Edit away! - Try to follow these conventions here.
- For example, Move down to a directory you want to edit, and edit a file with gedit
cd soas-docs ls cd Creation\ Kit/ cd en-US ls gedit Book_Info.xml
- Bump the edition tag in Book_Info.xml after a major change.
- Make sure to explain your change in Revision_History.xml
Generating HTML or PDF output
Install publican if you haven't already. If you are running a yum-based system (Fedora, SuSE, etc), this is:
sudo yum install publican
If you are running an apt-based system (Debian, Ubuntu, etc), this is:
sudo apt-get install publican
In the same directory as the file publican.cfg (this will almost certainly be /path/to/soas-docs/Customization Guide or /path/to/soas-docs/Creation Kit), run the following command.
publican build --format=html --lang=en-US
publican build --format=pdf --lang=en-US
...depending on what output format you would like. You will see output that looks like this.
[you@machine]$ publican build --format=html --lang=en-US Setting up en-US Processing file tmp/en-US/xml/Common_Content/Conventions.xml Processing file tmp/en-US/xml/Common_Content/Feedback.xml Processing file tmp/en-US/xml/Common_Content/Legal_Notice.xml <snip more similar stuff> Beginning work on en-US Starting html Using XML::LibXSLT on /usr/share/publican/xsl/html.xsl Writing pref-Customization_Guide-Preface.html for preface(pref-Customization_Guide-Preface) Writing sect-Creation_Kit-Preparation-Getting_Started.html for section(sect-Creation_Kit-Preparation-Getting_Started) Writing chap-Customization_Guide-Preparation.html for chapter(chap-Customization_Guide-Preparation) <snip more similar stuff> Writing index.html for book Finished html
When the publican build is finished, you will find your generated docs in a folder called tmp/en-US in your current directory.
Create a Patch from your ChangesCreate a patch using the following command:
git diff > product-name-change.patch
- product reflects the folder you made your change in, so either creation-kit or customization-guide
- name references to your personal name to track contributions
- change should be a one or two word description of your proposed change
Push your changes
If you don't have commit access
Send an email (with a subject line like this [PATCH] name-of-your-patch) to the SoaS mailing list together with your patch and an explanation of what you changed and why you think the change is necessary. Discussion will happen on list.
After that, your patch will be committed and pushed. At some point, you might also be granted access to the GIT repository so that you can commit changes directly without submitting the patches to the list.
If you have commit access
If you need to apply someone else's patch to the file before committing it, do that first.
patch -p0 < path/file.patch
Once you have applied the patch and otherwise edited the files you want to commit, make the commit.
git commit -a
Leave a commit message describing the change. Finally, push changes back to gitorious with
If you are doing a push for the first time, you may need to specify the origin (this is due to a weird thing in gitorious). In order to do this:
git remote rm origin git remote add origin email@example.com:soas-docs/mainline.git git push origin master
You should be able to simply use
git push thereafter.