GNOME Bugzilla – Bug 665836
lightsoff: Convert documentation to Mallard format
Last modified: 2012-05-01 03:02:42 UTC
Convert documentation to Mallard format
To start writing documentation for this game, make sure you are running version 3.4.0. (You can check this by clicking Help-->About, or Application-->About, depending on which version you have). 1. You will need to install and setup git (http://wiki.freegeek.org/index.php/Git_for_dummies#Setup) <-- do the stuff under Setup only :-) 2. Open a terminal and type: git clone git://git.gnome.org/gnome-games 3. Then to go into the help directory: cd gnome-games/lightsoff/help/C The outdated help files are in this directory. If you want to view them you can type: yelp lightsoff.xml *** We can not use the content from this document. It is just an example. *** A good example of Mallard game docs to look at would be the iagno documentation, which is in gnome-games/iagno/help/C. There you will see a list of .page files. To view the document in yelp type: yelp index.page (The online version is here: http://library.gnome.org/users/iagno/stable/). You can view the Mallard source pages of the .page files using any text editor like Gedit or vi. You can use a similar type outline for Lightsoff. Create new .page files in the lightsoff/help/C directory and write them up. To view the resulting page type: yelp <pagename> A good Mallard resource can be found here: http://projectmallard.org/about/learn/tenminutes.html Once you have something you would like us to review (like maybe an outline to start with), type: git add <pagename> Add EVERY new page you created to git. Then type: git commit -m "lightsoff docs: New Mallard docs" Then type: git format-patch HEAD^ This will create a .patch file (starting with 0001-). This is the file you should upload to the bug.
NOTE: As of today here has been a change to the old xml doc filename. The above should read: The outdated help files are in this directory. If you want to view them you can type: yelp index.docbook
Hi, I am interested in doing the mallard documentation for the lightsoff game. I have had a good look at the bug report given above. I will start the mallard documentation for lightsoff, If there are any other suggestions that i need to follow regarding the documentation, Please let me know, It will be really helpful. Thanks and Regards Perumal
Created attachment 212511 [details] [review] Lightsoff new mallard docs. Hi Tiffany, I have made the new mallard documentation for the Lightsoff game and have attached the patch. Please have a look at the patch and let me know if it needs any changes to be made. I have tried to apply the patch; it seems to be working fine. I have not included the keyboard shortcuts in the help docs, as it only works when we click the application menu. Cheers!!!! Thanks, Perumal
Review of attachment 212511 [details] [review]: Quick review from looking at the patch; I did not compile it and check in Yelp. ::: lightsoff/help/C/basic.page @@ +16,3 @@ + +<title>Basics</title> +<p> Lightsoff can be played using the keyboard or the mouse. </p> Please avoid whitespaces at the beginning and at the end. @@ +21,3 @@ +<title>Using the keyboard</title> +<list> + <item><p>To select a tile, use the arrow keys to move the spotlight on to that tile and press <key> Enter </key> key.</p></item> Two whitespaces before "key". @@ +38,3 @@ +<list> + <item><p>The progress through the levels is either by turning of all the lights in that level or using the arrow shaped buttons in the bottom of the game.</p></item> + <item><p> The arrow shaped buttons at the bottom of the game allow you to skip the levels or return to the previous levels. The current level is shown at the bottom of the game. Whitespace at the beginning of the sentence. @@ +42,3 @@ +</list> +<figure> + <desc>This shows the lights off pattern for level 3, with the arrow shaped buttons at the bottom.</desc> "lights off" spelling is inconsistent with other places. Should be checked globally. :) ::: lightsoff/help/C/bug-filing.page @@ +26,3 @@ +<title>Report a bug or suggest an improvement</title> +<p> + <app>Lightsoff</app> is maintained by a volunteer community. You are welcome to participate. If you notice a problem you can file a <em>bug report</em>. To file a bug, go to <link href = "https://bugzilla.gnome.org/"/>. link href = " - Does that really work with whitespaces around the = ? @@ +36,3 @@ + <p> + Once you have an account, log in, click on <guiseq><gui>File a Bug</gui><gui>Applications</gui><gui>gnome-games</gui></guiseq>. + Before reporting a bug, please read the <link href = "https://bugzilla.gnome.org/page.cgi?id=bug-writing.html">bug writing guidelines</link>, and please <link href="https://bugzilla.gnome.org/browse.cgi?product=gnome-games">browse</link> for the bug to see if it already exists. Same issue as in the other place: "</link>, and": Two whitespaces. ::: lightsoff/help/C/documentation.page @@ +24,3 @@ + The <app>GNOME Games</app> documentation is maintained by a volunteer community. You are welcome to participate.</p> + +<p>To contribute to the Documentation Project, feel free to get in touch with us using <link href="https://cbe003.chat.mibbit.com/?url=irc%3A%2F%2Firc.gnome.org%2Fdocs">irc</link>, or via our <link href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list">mailing list</link>. In the glines user docs there is a similar sentence: "To contribute to the Documentation Project, feel free to get in touch with us using ..." You have two whitespaces in front of "feel free to" so if a translator used a translation tool with translation memory this would not be a perfect match but marked as "fuzzy" because of that. ::: lightsoff/help/C/index.page @@ +20,3 @@ +<title><media type="image" src="figures/lightsoff.jpg">Iagno logo</media>Lightsoff</title> + + <p><app>Lightsoff</app>is a puzzle played on an 5X5 grid with the aim to turn off all the lights. Each click on a tile toggles the state of the clicked tile and its non-diagonal neighbours. </app>is misses a whitespace. neighbour is British spelling, but documentation and strings in general in GNOME should be American English. ::: lightsoff/help/C/rules.page @@ +16,3 @@ + <title>Rules</title> + + <p>In order to complete the lightsoff puzzle, you must turn off all the lights in the board. This will get you to advance to the next level.</p> I think the User Interface (UI) calls it "Lights Off". You could put this into <app> markup. Same applies to other places. @@ +21,3 @@ + The game begins with a pattern of lights on the 5x5 grid. + </p></item> + <item><p>Select a tile to toggle its state and its non-diaogonal neighbours state</p></item> Typo: diaogonal. British spelling: neighbours. ::: lightsoff/help/C/strategy.page @@ +50,3 @@ + <item><p>Now again chase the lights starting from the first row. After chasing the lights this time your puzzle will be solved.</p></item> + </steps> + <note><p>This strategy doesn't always produce the optimal solution, it may take more number of moves to complete the game. But you will be able to successfully complete the game using this strategy.</p></note> "it may take more number of moves" => "it may take more moves"? And "But you will be able to successfully complete the game using this strategy." is not a full sentence. :) ::: lightsoff/help/C/translate.page @@ +29,3 @@ +</p> +<p> +To start translating you will need to <link href="http:l10n.gnome.org">create an account</link> and join the <link href="http://l10n.gnome.org/teams/">translation team</link> for your language. This will give you the ability to upload new translations. Broken URL: http:l10n.gnome.org
Created attachment 212591 [details] [review] Lightsoff new mallard docs. Here is the updated patch. cheers, Perumal
Review of attachment 212591 [details] [review]: Overall, these docs look good! I have mentioned some further changes which should be made before I can push these docs to the master branch. Thanks for your work! ::: lightsoff/help/C/basic.page @@ +3,3 @@ + id="play"> + <info> + <revision pkgversion="3.4" version="0.1" date="2012-03-08" status="final"/> status="review". The documentation team sets the status to "candidate" or "final" @@ +21,3 @@ +<title>Using the keyboard</title> +<list> + <item><p>To select a tile, use the arrow keys to move the spotlight on to that tile and press <key>Enter</key> key.</p></item> press the <key>Enter</key> @@ +37,3 @@ +<title>Progress through the levels</title> +<list> + <item><p>The progress through the levels is either by turning of all the lights in that level or using the arrow shaped buttons in the bottom of the game.</p></item> turning off all the lights @@ +44,3 @@ + <desc>This shows the <app>Lights Off</app> pattern for level 3, with the arrow shaped buttons at the bottom.</desc> + <media type="image" mime="image/jpg" src="figures/lo1.jpg" width="300" ></media> +</figure> The image should use the GNOME 3 theme in general (This image has a Ubuntu theme). However, I also generally prefer there to not be any English strings in the images inless absolutely necessary (makes life easier for translators). Here, if you crop this image to exclude the title bar, everything will be okay, since this will remove the Ubuntu themed title bar along with the English name of the game. @@ +48,3 @@ + +<section id="usage-video"> + <title>Video Demonstration</title> The video is well done, but should also not include the titlebar (same reasoning as the image). ::: lightsoff/help/C/index.page @@ +7,3 @@ + <title type='link'>Lights Off</title> + <title type='text'>Lights Off</title> + <revision pkgversion="3.4" version="0.1" date="2012-03-08" status="final"/> status="review" ::: lightsoff/help/C/strategy.page @@ +19,3 @@ + <section> + <steps> + <item><p>Chase the lights starting from the first row. To chase the lights in the first row, click the tile on the second row corresponding to the light in the first row. This will turn of that light in the first row.</p> This will turn off that light in the first row. @@ +24,3 @@ + <item><p>In the same way continue to chase the lights in the second, third and fourth row. At the end of this you will be only left with the lights in the fifth row.</p></item> + + <item><p>Now depending on the lights left in the fifth row, click the tiles in the first row using the table given below. </p> depending on which lights are remaining in the fifth row, ...
Review of attachment 212591 [details] [review]: A couple of more things I noticed. ::: lightsoff/help/C/strategy.page @@ +16,3 @@ + + <title>Strategy</title> + <p>This is a simple strategy to solve the <app>Lights Off</app> puzzle by using the method called "Chase The Lights".</p> "Chase the Lights" . The word "the" is never capitalised in title case. @@ +17,3 @@ + <title>Strategy</title> + <p>This is a simple strategy to solve the <app>Lights Off</app> puzzle by using the method called "Chase The Lights".</p> + <section> After checking in yelp with yelp-check tool, this section element is causing the this page not to validate. This is because every section element needs an id attribute and a title. For example: <section id="chase"><title>Chase the light steps:</title>. The other option is to remove the <section> element (and it's closing tag altogether). I will leave the decision up to you.
(In reply to comment #7) > @@ +21,3 @@ > +<title>Using the keyboard</title> > +<list> > + <item><p>To select a tile, use the arrow keys to move the spotlight on to > that tile and press <key>Enter</key> key.</p></item> > > press the <key>Enter</key> Tiffany: Sure about that? "Press the Enter." sounds rather ugly to me.
... and press the <key>Enter</key> key. (versus "press <key>Enter</key> key").
I think i will make it 'press the <key>Enter</key>'. It is like that in Sudoku also.
Either "press the <key>Enter</key> key." or "press <key>Enter</key>." I prefer the latter. Regarding comment #5, spaces around the equals sign in an attribute are actually well-formed XML. But you should just live your life as if it isn't. ;-)
It should be either: 1. ... press the <key>Enter</key> key. OR 2. ... press <key>Enter</key>. I'll have a look at the Sudoku help. Thanks.
Tiffany, I meant 'press the <key>Enter</key> key'. But i think the second one is better. Shaun, I will choose the second one then. And about the spaces around the equal sign it did work well, but i removed the spaces in the updated patch to make it more uniform.
Created attachment 213118 [details] [review] Updated Patch I have made all the changes mentioned. This patch also removes the old index.docbook file. In the 'basic.page', I have used 'press the <key>Enter</key> key', as it would be same as the other docs(Sudoku) and it looks better.:-) Thanks, Perumal
Review of attachment 213118 [details] [review]: Great! I have pushed the docs to master: http://git.gnome.org/browse/gnome-games/commit/?id=c7c1fb5548d3cc05ac996ec5a67fedcd1f8acb8c
I made one minor change. The index page had the title as "Lightsoff", so I updated it to "Lights Off" to match the rest (http://git.gnome.org/browse/gnome-games/commit/?id=d7fd5f2f05df3de4434cd0c2083e0e061a8ee6c0). The new license.xml has now been also added (http://git.gnome.org/browse/gnome-games/commit/?id=6ddeb27f86675c201049e6d4741273a7883191de), and the Makefile.am has been updated to build the new Mallard help (http://git.gnome.org/browse/gnome-games/commit/?id=f70d80a66a21c1e1aa6eaeefed9f6ce0d65800eb) Thanks for your work!
Thanks for your care and help ! I am looking forward to make future contributions to GNOME :-)