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 665833 - gnobots2 / gnome-robots: Convert documentation to Mallard format
gnobots2 / gnome-robots: Convert documentation to Mallard format
Status: RESOLVED FIXED
Product: gnome-robots
Classification: Applications
Component: documentation
git master
Other Linux
: Normal normal
: ---
Assigned To: Maintainers of Gnome user documentation
gnome-robots-maint
Depends on:
Blocks:
 
 
Reported: 2011-12-09 02:26 UTC by Robert Ancell
Modified: 2014-03-19 16:23 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
screenshot (58.58 KB, image/png)
2014-01-26 16:51 UTC, Michael Catanzaro
  Details
Update documentor credits (799 bytes, patch)
2014-01-27 23:43 UTC, Michael Catanzaro
committed Details | Review
help: do not name the page "Robots logo Robots" (811 bytes, patch)
2014-01-27 23:43 UTC, Michael Catanzaro
committed Details | Review
help: install Robots logo (637 bytes, patch)
2014-01-27 23:43 UTC, Michael Catanzaro
committed Details | Review
Add icon next to title; fix typo; clarify possible moves (5.08 KB, patch)
2014-01-27 23:43 UTC, Michael Catanzaro
committed Details | Review
Bug 665833: Added Mallard help for GNOME-robots (92.73 KB, patch)
2014-01-27 23:43 UTC, Michael Catanzaro
committed Details | Review
help: New images for documentation (15.15 KB, patch)
2014-03-18 22:45 UTC, Rachel Dunstan
none Details | Review
help: Updated Makefile.am for new doc. images (1.45 KB, patch)
2014-03-18 22:46 UTC, Rachel Dunstan
none Details | Review
help: Updated appearance page with new themes (2.22 KB, patch)
2014-03-18 22:46 UTC, Rachel Dunstan
none Details | Review
help: Added starting new game from toolbar (1.66 KB, patch)
2014-03-18 22:46 UTC, Rachel Dunstan
needs-work Details | Review
help: All high&low risk robots & high score info (6.72 KB, patch)
2014-03-18 22:46 UTC, Rachel Dunstan
none Details | Review
help: Reordered & formatted table of game types (3.49 KB, patch)
2014-03-18 22:46 UTC, Rachel Dunstan
none Details | Review
help: Changed key info for staying & reformatted (2.22 KB, patch)
2014-03-18 22:46 UTC, Rachel Dunstan
none Details | Review
help: Fixed spacing of appearance patch (2.75 KB, patch)
2014-03-19 15:00 UTC, Rachel Dunstan
none Details | Review
help: Fixed spaces of basics patch & added alt-text (2.25 KB, patch)
2014-03-19 15:00 UTC, Rachel Dunstan
none Details | Review
help: Fixed spacing of controls-default & added alt-text (2.78 KB, patch)
2014-03-19 15:00 UTC, Rachel Dunstan
none Details | Review
help: Fixed spacing of game-types patch (3.49 KB, patch)
2014-03-19 15:00 UTC, Rachel Dunstan
none Details | Review
help: Fixed spacing of scores & added alt-text (10.07 KB, patch)
2014-03-19 15:00 UTC, Rachel Dunstan
none Details | Review

Description Robert Ancell 2011-12-09 02:26:07 UTC
Convert documentation to Mallard format
Comment 1 Aruna Sankaranarayanan 2013-05-21 16:42:20 UTC
Hi, a new branch mallard-help has been pushed to git.

The commit id of the mallard-help is 315dd03ad6a0215477fa8ae252426c0aced66c10

It would be great if someone reviewed the pages so it could be merged with master.
Comment 2 Aruna Sankaranarayanan 2013-05-24 12:31:32 UTC
Sorry, the commit id is 046104596308723c9f9f690e35318f9509a6f977
Comment 3 Michael Catanzaro 2014-01-15 00:46:45 UTC
Looks almost complete.  It'd be nice to get this in for 3.12 if we can.

A few comments, all minor:

* The 32x32 application icon should be displayed to the left of the title on the index page.
* On the basic instructions page, under enable sounds, there's a missing space between Select and Settings.
* On the different moves in Robots page, you say you can move in nine possible ways, or wait for the robots, or teleport. But one of the nine possible ways of moving listed below is waiting. Might be less confusing to say eight directions.
* On the game type page, you mention the use safe moves and use super safe moves preferences. It would be good to explain more fully how these work. These could arguably be split off to a separate page, since they're not really related to the game mode.
Comment 4 André Klapper 2014-01-26 02:18:05 UTC
(In reply to comment #3)
> Looks almost complete.  It'd be nice to get this in for 3.12 if we can.
> 
> * The 32x32 application icon should be displayed to the left of the title on
> the index page.
> * On the basic instructions page, under enable sounds, there's a missing space
> between Select and Settings.
> * On the different moves in Robots page, you say you can move in nine possible
> ways, or wait for the robots, or teleport. But one of the nine possible ways of
> moving listed below is waiting. Might be less confusing to say eight
> directions.

All three fixed in https://git.gnome.org/browse/gnome-robots/commit/?h=mallard-help&id=9ba4afc8147260d43adebf82fa4a1862eb9e8bdc

> * On the game type page, you mention the use safe moves and use super safe
> moves preferences. It would be good to explain more fully how these work. These
> could arguably be split off to a separate page, since they're not really
> related to the game mode.

Can this please become a separate enhancement request?

So regarding comment 3, I think we're done here, so you could merge Aruna's branch into git master for 3.12?
Comment 5 Michael Catanzaro 2014-01-26 03:24:59 UTC
(In reply to comment #4)
> All three fixed in
> https://git.gnome.org/browse/gnome-robots/commit/?h=mallard-help&id=9ba4afc8147260d43adebf82fa4a1862eb9e8bdc

Thanks! I made a couple of changes you might want to look over real quick.

> Can this please become a separate enhancement request?

OK: Bug #722998

> So regarding comment 3, I think we're done here, so you could merge Aruna's
> branch into git master for 3.12?

I sure can, but does anyone else need to approve this first, or are we good to go?
Comment 6 Aruna Sankaranarayanan 2014-01-26 06:15:59 UTC
Thanks for fixing my mistakes, Andre!
Comment 7 André Klapper 2014-01-26 10:12:23 UTC
(In reply to comment #5)
> Thanks! I made a couple of changes you might want to look over real quick.

https://git.gnome.org/browse/gnome-robots/commit/?h=mallard-help&id=edbb5942d3a324d9fcee4f40299d8209911a34f7 confuses me. The text should only be displayed as a fallback when the image is not loaded, IMO.
Wondering what's different with your setup. Yelp 3.10 here.

Thanks for fixing the build; was late yesterday and didn't test. :-/

> > So regarding comment 3, I think we're done here, so you could merge Aruna's
> > branch into git master for 3.12?
> 
> I sure can, but does anyone else need to approve this first, or are we good to
> go?

I'd let Kat have the last word here.
Comment 8 Michael Catanzaro 2014-01-26 16:51:08 UTC
Created attachment 267238 [details]
screenshot

Hm, do other modules use fallback text for these logos?  I don't think any of the other games do.

Here's what I'm seeing.  If I don't install the logo, it looks just like this except with a missing image placeholder instead of the logo: the text doesn't replace the image.  My Yelp is recently built from git master.
Comment 9 Kat 2014-01-27 10:13:28 UTC
Hi all, Michael is correct about the alt text for the logo: we don't use them because of the "Application logo Application" problem.

The rest of the help looks good for merging.
Comment 10 Michael Catanzaro 2014-01-27 23:43:44 UTC
Cool. Thanks everyone, especially Aruna of course!

The following fixes have been pushed:
9d52b91 Update documentor credits
74dbb93 help: do not name the page "Robots logo Robots"
1b8f4b4 help: install Robots logo
b2b364f Add icon next to title; fix typo; clarify possible moves
6e7a831 Bug 665833: Added Mallard help for GNOME-robots
Comment 11 Michael Catanzaro 2014-01-27 23:43:47 UTC
Created attachment 267361 [details] [review]
Update documentor credits
Comment 12 Michael Catanzaro 2014-01-27 23:43:50 UTC
Created attachment 267362 [details] [review]
help: do not name the page "Robots logo Robots"

This is displaying incorrectly in Yelp's window title and in the
dropdown menu.
Comment 13 Michael Catanzaro 2014-01-27 23:43:53 UTC
Created attachment 267363 [details] [review]
help: install Robots logo
Comment 14 Michael Catanzaro 2014-01-27 23:43:56 UTC
Created attachment 267364 [details] [review]
Add icon next to title; fix typo; clarify possible moves

See first three items of
https://bugzilla.gnome.org/show_bug.cgi?id=665833#c3
Comment 15 Michael Catanzaro 2014-01-27 23:43:59 UTC
Created attachment 267365 [details] [review]
Bug 665833: Added Mallard help for GNOME-robots

Added:
appearance.page, basics.page, controls-change,
controls-default.page, game-types.page, index.page,
moves.page, scores.page
Comment 16 Rachel Dunstan 2014-03-16 22:30:21 UTC
Could I try the review (mentioned here: https://wiki.gnome.org/DocumentationProject/Tasks/ApplicationHelp#Beginner_projects)?
Comment 17 Rachel Dunstan 2014-03-18 22:45:59 UTC
Created attachment 272329 [details] [review]
help: New images for documentation

New images of robots have been included for the themes not already
documented (anthills, cows, eggs. mice, spills, stormclouds,
toasters). "gnome-high-risk.png" and "gnome-low-risk.png" have been
renamed to "gnomes-high-risk.png" and "gnomes-low-risk" to conform
with theme name "gnomes" and names for the images of other themes.
One image for starting a new game added.
Comment 18 Rachel Dunstan 2014-03-18 22:46:03 UTC
Created attachment 272330 [details] [review]
help: Updated Makefile.am for new doc. images
Comment 19 Rachel Dunstan 2014-03-18 22:46:08 UTC
Created attachment 272331 [details] [review]
help: Updated appearance page with new themes

The themes not previously documented (anthills, cows, eggs, mice,
spills, stormclouds, toasters) have been added to the list of themes
available.
Comment 20 Rachel Dunstan 2014-03-18 22:46:12 UTC
Created attachment 272332 [details] [review]
help: Added starting new game from toolbar

An instruction for starting a new game from the toolbar with accompanying
image has been included.
Comment 21 Rachel Dunstan 2014-03-18 22:46:16 UTC
Created attachment 272333 [details] [review]
help: All high&low risk robots & high score info

The section on high and low risk robots now covers robots of all themes.
Anthills, cows, eggs, mice, spills, stormclouds were all previously
missing. The information is now in table form, to improve concision and
reduce repetition. Information on viewing high scores has been added.
Comment 22 Rachel Dunstan 2014-03-18 22:46:20 UTC
Created attachment 272334 [details] [review]
help: Reordered & formatted table of game types

The game types are now listed in the order in which they appear in the
preferences dialog; the previous order appeared to have no particular
pattern. The table has been reformatted to correspond better with the
formatting of other tables in GNOME Games.
Comment 23 Rachel Dunstan 2014-03-18 22:46:25 UTC
Created attachment 272335 [details] [review]
help: Changed key info for staying & reformatted

The key for staying in place has been edited to "Begin" (i.e. without
numlock activated) to match all other key descriptions e.g. "PgUp", with
a note that some keyboards only show "5" on this key. Table reformatted.
Comment 24 Kat 2014-03-19 12:53:17 UTC
Review of attachment 272332 [details] [review]:

::: help/C/basics.page
@@ +7,3 @@
 
+		<revision pkgversion="3.8" version="0.1" date="2013-04-03" status="draft"/>
+		<revision pkgversion="3.11.90" date="2014-03-18" status="review"/>

Check indentation

@@ +15,3 @@
       <email>safincrazy@gmail.com</email>
     </credit>
 

No blank line here please

@@ +19,3 @@
+			<name>Rachel Dunstan</name>
+			<email>dunstanrc@gmail.com</email>
+		</credit>

Check indentation

@@ +31,2 @@
   <p>Select <guiseq><gui style="menu">Game</gui>
+  <gui style="menuitem">New</gui></guiseq>,  click the <media type="image"

Don't break the <media> tag half way through, just move the whole tag to the next line

@@ +32,3 @@
+  <gui style="menuitem">New</gui></guiseq>,  click the <media type="image"
+	src="figures/new.png"/> button on the toolbar, or press <keyseq><key>Ctrl
+	</key><key>N</key></keyseq> to start a new

Check indentation; keep the <keyseq> on one line as what you're doing here will add a space into one of the keys
Comment 25 Rachel Dunstan 2014-03-19 15:00:00 UTC
Created attachment 272389 [details] [review]
help: Fixed spacing of appearance patch

Commit message of original patch:
The themes not previously documented (anthills, cows, eggs, mice,
spills, stormclouds, toasters) have been added to the list of themes
available.
Comment 26 Rachel Dunstan 2014-03-19 15:00:05 UTC
Created attachment 272390 [details] [review]
help: Fixed spaces of basics patch & added alt-text

Commit message of original patch:
An instruction for starting a new game from the toolbar with accompanying
image has been included.
Comment 27 Rachel Dunstan 2014-03-19 15:00:09 UTC
Created attachment 272391 [details] [review]
help: Fixed spacing of controls-default & added alt-text

Commit message of original patch:
The key for staying in place has been edited to "Begin" (i.e. without
numlock activated) to match all other key descriptions e.g. "PgUp", with
a note that some keyboards only show "5" on this key. Table reformatted
Comment 28 Rachel Dunstan 2014-03-19 15:00:14 UTC
Created attachment 272392 [details] [review]
help: Fixed spacing of game-types patch

Commit message of original patch:
The game types are now listed in the order in which they appear in the
preferences dialog; the previous order appeared to have no particular
pattern. The table has been reformatted to correspond better with the
formatting of other tables in GNOME Games.
Comment 29 Rachel Dunstan 2014-03-19 15:00:18 UTC
Created attachment 272393 [details] [review]
help: Fixed spacing of scores & added alt-text

Commit message of original patch:
The section on high and low risk robots now covers robots of all themes.
Anthills, cows, eggs, mice, spills, stormclouds were all previously
missing. The information is now in table form, to improve concision and
reduce repetition. Information on viewing high scores has been added.
Comment 30 André Klapper 2014-03-19 16:23:55 UTC
Rachel: This bug report was closed as RESOLVED FIXED on 2014-01-27 as converting the documentation to Mallard was successfully finished (and that's what the ticket is about). Further cleanup patches might not receive attention and should better go to separate followup bug reports, as they are unrelated to the original topic of this ticket (converting to Mallard).