Sugar on a Stick/Documentation SOP: Difference between revisions

(8 intermediate revisions by 2 users not shown)

Line 5:

You can view a reasonably up-to-date version of the files here:

* [http://~~people~~.sugarlabs~~.org~~/~~sdz~~/customization-guide/ Customization Guide]

* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]

* [http://~~people~~.sugarlabs~~.org~~/~~sdz~~/creation-kit/ Creation Kit]

* [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.

Line 14:

=== 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>

Line 20:

* 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.

* Make sure to explain your change in Revision_History.xml

Line 25:

Line 34:

=== Generating HTML or PDF output ===

Install publican if you haven't already. ~~On most Linux distributions~~, this ~~will be~~:

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.

Line 76:

Line 89:

==== 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.

@@ Line 5: / Line 5: @@
 You can view a reasonably up-to-date version of the files here:
-* [http://people.sugarlabs.org/sdz/customization-guide/ Customization Guide]
+* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]
-* [http://people.sugarlabs.org/sdz/creation-kit/ Creation Kit]
+* [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.
@@ Line 14: / Line 14: @@
 === 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>
@@ Line 20: / Line 20: @@
 * 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.
 * Make sure to explain your change in Revision_History.xml
@@ Line 25: / Line 34: @@
 === Generating HTML or PDF output ===
-Install publican if you haven't already. On most Linux distributions, this will be:
+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.
@@ Line 76: / Line 89: @@
 ==== 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.