8,288
edits
Changes
Sugar on a Stick/Documentation SOP (view source)
Revision as of 15:34, 22 December 2010
, 15:34, 22 December 2010no edit summary
Starting with the upcoming SoaS version (release date: ''2010-05-11''), a good amount of the related documentation will be created through [https://fedorahosted.org/publican/ publican]. This [http://en.wikipedia.org/wiki/Standard_operating_procedure SOP] describes how to contribute changes to the documentation.
Starting with the upcoming SoaS version (release date: ''2010-05-11''), a good amount of the related documentation will be created through [https://fedorahosted.org/publican/ publican]. This [http://en.wikipedia.org/wiki/Standard_operating_procedure 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:
* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]
* [http://mirrors.rit.edu/sugarlabs/soas/docs/creation-kit/index.html Creation Kit]
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 ==
== Contributing Content to the Documentation ==
=== Checking out the latest Version ===
=== Checking out the latest Version ===
Clone the GIT repository with the Sugar on a Stick documentation from GIT by running:
Clone the [http://git.sugarlabs.org/soas-docs GIT repository] with the Sugar on a Stick documentation from GIT by running:
<pre>git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs</pre>
<pre>git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs</pre>
* Edit away! - Try to follow these conventions [https://fedorahosted.org/publican/browser/trunk/publican/datadir/Common_Content/common/en-US/Conventions.xml here].
* Edit away! - Try to follow these conventions [https://fedorahosted.org/publican/browser/trunk/publican/datadir/Common_Content/common/en-US/Conventions.xml here].
**For example, Move down to a directory you want to edit, and edit a file with gedit
<pre>cd soas-docs
ls
cd Creation\ Kit/
cd en-US
ls
gedit Book_Info.xml</pre>
* Bump the edition tag in ''Book_Info.xml'' after a major change.
* Bump the edition tag in ''Book_Info.xml'' after a major change.
* Make sure to explain your change in Revision_History.xml
* 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
or
publican build --format=pdf --lang=en-US
...depending on what output format you would like. You will see output that looks like this.
<pre>
[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
</pre>
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 Changes ===
=== Create a Patch from your Changes ===
* ''change'' should be a one or two word description of your proposed change
* ''change'' should be a one or two word description of your proposed change
=== Notify us 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 [http://lists.sugarlabs.org/listinfo/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.
Send an email (with a subject line like this ''[PATCH] name-of-your-patch'') to the SoaS [http://lists.sugarlabs.org/listinfo/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.
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
git push
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 gitorious@git.sugarlabs.org:soas-docs/mainline.git
git push origin master
You should be able to simply use <code>git push</code> thereafter.