After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 618345 - quadrapassel: Convert documentation to Mallard format
quadrapassel: Convert documentation to Mallard format
Status: RESOLVED FIXED
Product: gnome-games-superseded
Classification: Deprecated
Component: docs
trunk
Other Linux
: Normal enhancement
: ---
Assigned To: Maintainers of Gnome user documentation
Maintainers of Gnome user documentation
Depends on:
Blocks:
 
 
Reported: 2010-05-11 07:53 UTC by Robert Ancell
Modified: 2012-08-11 22:47 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
first draft patch for changing the old format to Mallard (23.91 KB, patch)
2012-03-28 15:23 UTC, Elena
needs-work Details | Review
This is the patch with corrections made. I do apologize for the first one though. (4.19 KB, patch)
2012-03-28 19:03 UTC, Elena
committed Details | Review
Improving the design of the previous documentation. (268.41 KB, patch)
2012-04-04 19:02 UTC, Elena
committed Details | Review
One more change - GNOME image :) (326.43 KB, patch)
2012-04-05 13:14 UTC, Elena
committed Details | Review
After the comments from my mentor (Tiffany Apostolski) (449.55 KB, patch)
2012-04-13 00:12 UTC, Elena
committed Details | Review

Description Robert Ancell 2010-05-11 07:53:24 UTC
Convert documentation to Mallard format
Comment 1 Tiffany Antopolski 2012-03-25 21:02:12 UTC
For anyone interested in working on this, you will first of course need to be familiar with the game,  so be sure to install 'quadrapassel', and play around for a bit.

To begin documenting:

1. You will need to first get the git version of the gnome-games.  To do so, in a terminal, type:  

git clone git://git.gnome.org/gnome-games

This will create a directory called gnome-games in your current directory.  (You may first need to install 'git' using your distributions package manager)

2. To view the current documentation:

cd gnome-games/quadrapassel/help/C/
yelp quadrapassel.xml

This documentation is out of date.  First, we would like to convert it to Mallard, and second, updates to the game have been made, so some features may have been removed, others may have been added.  

To view an example of Mallard docs for a gnome game, you could look at Iagno, or gnome-sudoku or gnomine.  These games (and their documentation) are also in the gnome-games directory.  

So to view the Iagno docs, you would cd into the Iagno/help/C directory.  There you will see many files with the .page extension.  To view the docs in yelp documentation viewer, type:

yelp index.page  

The index.page is the entry page into the docs (similar to html).  You can use the yelp command to open any of the pages (yelp <page name>)

You can view the mallard source by opening the page using your preferred text editor (like Gedit or vim).

It is a good idea to look at the Iagno, gnome-sudoku, or gnomine docs as an example of the topics and layouts.




To begin writing Mallard help for Quadrapassel, you will create .page files in the quadrapassel/help/C directory using a text editor.  Use the yelp command to view your creation, changes, and progress.

Some references:

http://projectmallard.org/about/learn/tenminutes.html
http://blogs.gnome.org/shaunm/files/2012/01/mallardcheatsheet.png

For a GWOP application, an index page with stub pages would be a good start.  By stub pages I mean incomplete topics, just to show an outline of the project. Perhaps one completed topic page (like introduction.page, or play.page).

----

Once you have some pages you would like reviewed, you will need to set up your git (if you haven't done so already)  --> http://book.git-scm.com/2_setup_and_initialization.html

Then for each new .page you have created type:

git add <new page name>

then type:

git commit -a -m "quadrapasse docs: start of Mallard docs"


Now you will want to create a .patch file:

git format-patch HEAD^

This will create a .patch file in your current directory.  This is the file you should attach to this bug.  Once it is attached, someone will review it and give you feedback.

Feel free to talk to members of the documentation team on #docs during your progress.  :-)
Comment 2 Elena 2012-03-25 23:11:38 UTC
Hello, 
I have already started working on the bug, and I will send it too You as soon as I finish.
Sincerely, 
Elena Petrevska


(In reply to comment #1)
> For anyone interested in working on this, you will first of course need to be
> familiar with the game,  so be sure to install 'quadrapassel', and play around
> for a bit.
> 
> To begin documenting:
> 
> 1. You will need to first get the git version of the gnome-games.  To do so, in
> a terminal, type:  
> 
> git clone git://git.gnome.org/gnome-games
> 
> This will create a directory called gnome-games in your current directory. 
> (You may first need to install 'git' using your distributions package manager)
> 
> 2. To view the current documentation:
> 
> cd gnome-games/quadrapassel/help/C/
> yelp quadrapassel.xml
> 
> This documentation is out of date.  First, we would like to convert it to
> Mallard, and second, updates to the game have been made, so some features may
> have been removed, others may have been added.  
> 
> To view an example of Mallard docs for a gnome game, you could look at Iagno,
> or gnome-sudoku or gnomine.  These games (and their documentation) are also in
> the gnome-games directory.  
> 
> So to view the Iagno docs, you would cd into the Iagno/help/C directory.  There
> you will see many files with the .page extension.  To view the docs in yelp
> documentation viewer, type:
> 
> yelp index.page  
> 
> The index.page is the entry page into the docs (similar to html).  You can use
> the yelp command to open any of the pages (yelp <page name>)
> 
> You can view the mallard source by opening the page using your preferred text
> editor (like Gedit or vim).
> 
> It is a good idea to look at the Iagno, gnome-sudoku, or gnomine docs as an
> example of the topics and layouts.
> 
> 
> 
> 
> To begin writing Mallard help for Quadrapassel, you will create .page files in
> the quadrapassel/help/C directory using a text editor.  Use the yelp command to
> view your creation, changes, and progress.
> 
> Some references:
> 
> http://projectmallard.org/about/learn/tenminutes.html
> http://blogs.gnome.org/shaunm/files/2012/01/mallardcheatsheet.png
> 
> For a GWOP application, an index page with stub pages would be a good start. 
> By stub pages I mean incomplete topics, just to show an outline of the project.
> Perhaps one completed topic page (like introduction.page, or play.page).
> 
> ----
> 
> Once you have some pages you would like reviewed, you will need to set up your
> git (if you haven't done so already)  -->
> http://book.git-scm.com/2_setup_and_initialization.html
> 
> Then for each new .page you have created type:
> 
> git add <new page name>
> 
> then type:
> 
> git commit -a -m "quadrapasse docs: start of Mallard docs"
> 
> 
> Now you will want to create a .patch file:
> 
> git format-patch HEAD^
> 
> This will create a .patch file in your current directory.  This is the file you
> should attach to this bug.  Once it is attached, someone will review it and
> give you feedback.
> 
> Feel free to talk to members of the documentation team on #docs during your
> progress.  :-)
Comment 3 Tiffany Antopolski 2012-03-25 23:20:38 UTC
Thanks Elena!
Comment 4 Elena 2012-03-28 15:23:34 UTC
Created attachment 210791 [details] [review]
first draft patch for changing the old format to Mallard

I am sending you the first draft. I have included some additional information in the documentation.
Comment 5 Tiffany Antopolski 2012-03-28 18:02:20 UTC
Review of attachment 210791 [details] [review]:

Hi Elena,
  
  This patch deletes the content and completely alters the contents of gnome-sudoku/help/C/commandline.page.  I don't think you meant to do that :-)

  There are a couple errors on quit.page:

       Unmatched inline element: i

  For each page which you added, you could type "yelp <page name>" and look at the terminal to check for errors.
  
The icon is not showing up on each of the pages, just on the index.page.  Looking at how the other docs do this should help you.

Can you fix these issues and upload the changes in a second patch?
Comment 6 Elena 2012-03-28 18:12:42 UTC
Hi Tiffany, 

Certainly I will fix the issues and upload it in the second patch. By following the example, I thought that we should use the other versions that are already finished in order all manuals to be similar to each other and easier for the users to adapt to them. 
It will not be a problem at all changing it; and I will send it to You as soon as possible. 

Thank You, 
Elena
Comment 7 Elena 2012-03-28 18:18:58 UTC
Maybe that is the reason why I somehow got in touch with the other document, because I was analyzing the way you have done it, and tried to imply the knowledge from the Mallard manual together with your way of working.
Comment 8 Elena 2012-03-28 19:03:00 UTC
Created attachment 210804 [details] [review]
This is the patch with corrections made. I do apologize for the first one though.
Comment 9 Elena 2012-04-04 19:02:32 UTC
Created attachment 211320 [details] [review]
Improving the design of the previous documentation.
Comment 10 Elena 2012-04-05 13:14:57 UTC
Created attachment 211380 [details] [review]
One more change - GNOME image :)
Comment 11 Elena 2012-04-13 00:12:44 UTC
Created attachment 211964 [details] [review]
After the comments from my mentor (Tiffany Apostolski)
Comment 12 Elena 2012-04-13 00:14:51 UTC
(In reply to comment #11)
> Created an attachment (id=211964) [details] [review]
> After the comments from my mentor (Tiffany Antopolski*)

* I am sorry for the mispronunciation. :)
Comment 13 Tiffany Antopolski 2012-04-23 03:00:35 UTC
Review of attachment 210804 [details] [review]:

See further notes below.
Comment 14 Tiffany Antopolski 2012-04-23 03:01:03 UTC
Review of attachment 211380 [details] [review]:

ok
Comment 15 Tiffany Antopolski 2012-04-23 03:01:26 UTC
Review of attachment 211964 [details] [review]:

ok.
Comment 16 Tiffany Antopolski 2012-04-23 03:01:43 UTC
Review of attachment 211320 [details] [review]:

okay
Comment 17 Tiffany Antopolski 2012-04-23 03:14:25 UTC
Hi Elena,
 
Sorry about the long wait :-(  Okay, I took all your patches and merged them into one and pushed them to the master branch... You can see your commit here:

http://git.gnome.org/browse/gnome-games/commit/?id=f679c7c9a7430b88e2b3365d976d01fc66e168c4

Additionally, I made some small changes (For example, use of the guiseq element, the keyseq element, removed screenshots (wrong theme and English strings) which remained, and used html codes to refer to the arrow keys).  

There was a validation issue too, (which took even me a while to figure out).  The section element strictly requires an id and a title (which became apparent when using the yelp-check validate tool).  This is actually not mentioned on the Mallard tutorial, and was far from obvious.  

You can see my changes here: 
http://git.gnome.org/browse/gnome-games/commit/?id=ee1c7a16162f23823b203bff0f03b7f390d1c341

Now, as you found out and mentioned on irc, the docs should definitely be updated to the 3.4 version you saw on your Ubuntu 12.04 install.  These docs are complete, just need the update, and then the gnome-games team will include them in the next point release.

So at this point, you should just do a fresh clone of the repository, and all your pages will there, with my changes included.  

Thanks for your work!
Comment 18 Elena 2012-04-23 06:05:18 UTC
Hi Tiffany, 

Thank you for the response, and for the changes. 
For the section element, I didn't know it, but it's always good to find out something new !!! :) 
It's great that the help section will be included in the new update! 

Thank you for your help while making the documentation for quadrapassel ! 
Elena
Comment 19 Tiffany Antopolski 2012-08-11 22:47:12 UTC
Final updates matching 3.5.5 pushed to master.  

commit: http://git.gnome.org/browse/gnome-games/commit/?id=d70ba5d50218fb23112fd9a265c3a635fbab8bbe

Closing this bug.