GNOME Bugzilla – Bug 664951
Swell Foop: Use Mallard for documentation
Last modified: 2018-05-22 11:37:20 UTC
Use Mallard for documentation
marking gnome-love. This will be released as a gci task on 12/16/11.
um.. i mean 2011/12/16.
Is any one woking on the bug use mallard for documentation.?
I'm not aware of anyone working on this.
Can i start to work on this bug?
Of course! I'd be happy to help with any questions you have about the game. If you have questions about Mallard, you'll want to get in touch with the documentation team: https://wiki.gnome.org/DocumentationProject/Contact
Thank you.
Please follow https://wiki.gnome.org/DocumentationProject/Guide/Convert and chose one project to work on at a time: it's not fair for other new contributors if you block all the available projects.
Created attachment 273707 [details] [review] mallard for documentation Please review.
Review of attachment 273707 [details] [review]: Thanks for the patch! You need to remove all pages and all media from the help/Makefile.am in the same patch. You should also delete help/C/topic.dat and help/C/legal.xml. Ask in #docs on IRC if you need help amending your previous patch :) Please update https://wiki.gnome.org/DocumentationProject/Tasks/ApplicationHelp to reflect that you're working on the documentation.
Created attachment 273877 [details] [review] mallard for documentation Please review. Thank you.
Comment on attachment 273877 [details] [review] mallard for documentation You also need to remove help/C/index.docbook in this patch, like you originally did, and update the help/Makefile.am
Created attachment 273891 [details] [review] mallard for documentation I removed index.docbook, Please review. Thank you.
Review of attachment 273891 [details] [review]: ::: help/Makefile.am @@ -2,3 @@ HELP_ID = swell-foop -HELP_MEDIA = \ You should probably leave "HELP_MEDIA =" in here @@ +5,3 @@ HELP_FILES = \ legal.xml \ + index.page You can only have legal.xml and index.page if you also add those files in this commit. The files that are listed in help/Makefile.am must exist in the repository or the build will be broken.
Created attachment 273906 [details] [review] mallard for documentation I removed legal.xml in help/Makeifile.am. Please review, thank you.
Review of attachment 273906 [details] [review]: ::: help/Makefile.am @@ +2,3 @@ HELP_ID = swell-foop HELP_MEDIA = \ Remove the trailing backslash as it will break the build. The last item in the list must not have a backslash, see https://wiki.gnome.org/DocumentationProject/Guide/Makefile for more details. @@ +6,2 @@ HELP_FILES = \ + index.page You haven't added legal.page in this patch…
Created attachment 273921 [details] [review] mallard for documentation Please review. Thank you.
Review of attachment 273921 [details] [review]: ::: help/Makefile.am @@ +4,1 @@ HELP_MEDIA = \ You still have a trailing backslash here, and please don't remove the blank line which was between the two items. @@ +6,3 @@ HELP_FILES = \ + index.page\ + legal.xml Sorry, I should have said "you haven't added index.page in this patch" at my last review. This list needs to reflect what is happening in this patch. If you remove any pages, they need to be removed form this list. If you add any pages, they need to be added to this list.
Created attachment 273975 [details] [review] mallard for documentation Please review. Thank you.
Review of attachment 273975 [details] [review]: ::: help/Makefile.am @@ +6,3 @@ HELP_FILES = \ + index.page\ + legal.xml Your help/Makefile.am is still not reflecting what you are doing in this patch. Please read my previous comment about these lines.
Created attachment 285215 [details] [review] mallard for doc Please review.
Comment on attachment 285215 [details] [review] mallard for doc (In reply to comment #21) > Created an attachment (id=285215) [details] [review] > mallard for doc > > Please review. You remove exactly one file: --- a/help/C/index.docbook +++ /dev/null and edit one more file (Makefile.am). In a/help/Makefile.am you add one file: + index.page\ There is a space missing and indentation is wrong, see the other ones around. You add that "index.page" file to Makefile.am so when compiling it will be looked for, but it is not there as you did not add a file called "index.page" in that patch. Furthermore, you remove all figures from Makefile.am but you do not remove the files from the repository. Changes to files themselves and the list of files in Makefile.am need to be consistent.
...also, there is a typo in the subject line.
Created attachment 285275 [details] [review] mallard for doc please review
Review of attachment 285275 [details] [review]: This patch deletes the Docbook help but doesn't add any new files. You need to 'git add' all the Mallard files. We also have a mallard-help branch now (which is probably more or less complete), so to the extent any changes are still necessary, make sure your changes are based on that branch, not on master. (You should have noticed this if you ran 'git pull' anytime in the last couple of months.) ::: help/Makefile.am @@ +6,2 @@ HELP_FILES = \ + index.page \ You need to list all your other Mallard files here, too. @@ +8,1 @@ legal.xml \ The backslash means that the list continues on the next line, so I don't think this could possibly work. Make sure the module actually builds by running 'jhbuild build swell-foop'.
Rashi, apologies for the unacceptable mega-delay on this. :( I've looked through your documentation today and it looks good. I'm not sure if Kat is OK with merging it now, or if she wants to wait until the start of the next cycle, though. I do see some things that could be improved: - On the index page: --- Say "to learn more" and "learn about" rather than "know more" and "know about." These words are similar, but "know" is a state of having knowledge, while "learn" is the state of gaining knowledge. --- The title is "Swell Foop" so never hyphenate it, as you did in the heading "Playing Swell-foop." --- Say "advanced settings" rather than "advance settings." - On the introduction page, you say "objects that are adjacent to each other get removed as a group." Which is almost true, but there is one more qualifier: they have to be the same color. I would say: "Objects of the same color that are adjacent to each other get removed as a group." Similarly, instead of "you cannot remove single objects," I would say "you cannot remove objects that are not adjacent to another object of the same color." - On the Play Swell Foop page, there is a broken image at the bottom of the page. - On the Scores page: --- Say "check out" (a verb phrase) rather than "checkout" (a noun, like a git checkout). --- Good job finding U+22EE vertical ellipsis; that was the perfect character to use here! - On the Start a new game dialog: --- We don't have New Game in the app menu anymore. --- "You can click on *the* Start a new game button." Besides the missing "the," we should probably give more detail here, since the button has a refresh icon and it's not at all clear that's the new game button. The icon on the button might change but the position of the button will probably stay the same, so you can say it's in the upper-left corner of the window. --- We probably don't need to mention the abandon game dialog. It's pretty clear how to get through this. Also, it won't appear at all if you haven't moved yet. - On the Game settings page: --- You have a comma splice: "The default number of colors is 3, you can increase or decrease it from Number of colors under Setup." Either change it to a semicolon or split it into two sentences. --- Zealous Animation is actually on by default, so you have this backwards. (Lastly: Kat didn't like it last time I squashed all your commits into one. Let it be known that this time it wasn't me. :) - On the Keyboard shortcuts page, I think we ought to mention how to play the game using the keyboard, using space and enter. That information is currently on the Play Swell Foop page, which is not where I would go to look for it. - On the Strategy page: --- Another comma splice here: "The most important rule when aiming for a high score is to think ahead, each group you remove will form and destroy other groups." --- The commas are off in the first sentence of the third bullet point. How about this: "If you have a choice between merging two groups of two into four or just adding one more to the group of six, then you should add the single object."
Hm, there is one more problem, which I forgot to check before. Most of the text is taken from the original documentation. Maybe we didn't mention this to you, but the original documentation uses the GNU Free Documentation License, which is not compatible with the CC-BY-SA license that you've used in your help. We think CC-BY-SA is a better license, but to do that license change we need to make sure to remove all the original GFDL writing, and redo it from scratch. :( It's also problematic that Callum and Andre, the original authors, aren't listed as authors in your revised version, since the work is largely a rearrangement of their writing. The best way forward is to make sure the Mallard help is completely CC-BY-SA, so we should remove their writing and start from scratch.
(In reply to Michael Catanzaro from comment #27) > Hm, there is one more problem, which I forgot to check before. Most of the > text is taken from the original documentation. Maybe we didn't mention this > to you, but the original documentation uses the GNU Free Documentation > License, which is not compatible with the CC-BY-SA license that you've used > in your help. We think CC-BY-SA is a better license, but to do that license > change we need to make sure to remove all the original GFDL writing, and > redo it from scratch. :( It's also problematic that Callum and Andre, the > original authors, aren't listed as authors in your revised version, since > the work is largely a rearrangement of their writing. The best way forward > is to make sure the Mallard help is completely CC-BY-SA, so we should remove > their writing and start from scratch. Hi Michael, Thanks for taking time out for this :) It's sad we have to do it all over again. But I think I can start working on it from next week or so.
Rashi, I talked with Kat and we decided to just use GFDL for your help, at least for now. So for Swell Foop and Chess, just change the license and restore the original authors to the credits, and we'll go from there. For Klotski and Tali, we need to follow the process at [1] to relicense it to GFDL. If you could post patches here in new bugs, Kat and I will --signoff on the Klotski patch; for Tali, only Kat needs to --signoff. It looks like Sindhu only left comments, which should hopefully all be gone by now, but if any of those are still remaining, please just remove or rewrite them so that we don't need to get --signoff from her. [1] https://wiki.gnome.org/DocumentationProject/Guide/Relicensing
As a temporary measure until we can complete the relicensing process, I've reverted the Klotski and Tali user help to the original Docbook help, so we can continue distributing those games.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/swell-foop/issues/2.