This was based off of the wiki. It is the first draft. It can be found at the included url. Reproducible: Always Steps to Reproduce: 1. 2. 3.
As discussed on IRC, alexander is about to made some updates and attach the result to this bug.
Created attachment 37248 [details] fixed xml guide I have added fixes to the xml. please add it as soon as possible. Thanks.
I'm editing it atm. xml code is a bit of a mess ;-) I'll use the provided link to the wiki to setup the French translation as well. From IRC: <alexander> http://www.wonderwarp.com/alex/tipiwiki/index.php?wiki=GentooForMacOSFr <alexander> there it is <alexander> hmm <alexander> i just noticed that the edit page section for the wiki says GFDL but the actual wiki says creative commons SA license <alexander> i hope that isn't a problem. <alexander> i can contact all the people who have edited the wiki <neysx> Thanks, I'll use it and fix the spelling mistakes before it goes into doc/fr <neysx> Please confirm cc-by-sa is the license it is under <alexander> neysx, Well I wrote most of it, and people edited the wiki <neysx> it's OK then
Please do _not_ make this draft official until further notice. alexander took the liberty of requesting that the doc be official without having requested revision from the rest of the team.
I'll edit it slightly (some typos and such) and apply coding style to make the xml readable. As I don't know anything about the Mac world unfortunately, feedback from the PPC guys will be required and appreciated ;-) Just do not bother posting patches against the attached doc, it's already been half reshaped. Thanks.
Hasan, please don't point fingers at me like that. 2 days ago, I posted a message to the mailing list stating that I would be submitting a first revision to become official. I collaborated already with three or 4 of the gentoo macos guys in the irc channel. I already submitted the guide xml to bugzilla before you started working on yours. _Please_ do not do any further work on your version or the currently submitted version until Xavier submits the fixed up one that he is reformatting. I think we should build off of that. I realize that you spent a lot of time on your version and you are frustrated that we both duplicated efforts, but please don't express that frustration by pointing fingers at me. I am frustrated as well since I spent a lot of time working on mine. Again, stop doing work until Xavier submits the version that he is working on. We can incorporate what you added into that version which has a different structure.
1) I did not at all mean to make any accusations or make any derogatory comments. I apologize if it came off that way. 2) I said that you didn't run this by the team because you didn't e-mail the rest of the team on any of the associated mailing lists. 3) I have just sent an e-mail out to the gentoo-osx@gentoo.org mailing list (sorry, sent before i saw that this bug had another message on it, otherwise I wouldn't have). It details what I have done and what I think needs to be done. For those of you not on the mailing list, it can be found at http://marc.theaimsgroup.com/?l=gentoo-osx&m=109226815427527&w=2 4) There is no need to spend time fixing broken xml; my xml already works and has been parsed into html (as confirmation of this). I don't mean to cause any frustration (I'm not frustrated at all, honestly). Let me know if I've done something wrong.
Adding osx@gentoo.org to the cc. In the future, I think this should be done for all bugs in concern with gentoo-osx development, regardless of the division (documentation, portage, ebuilds, gui, etc.).
I did notify the team. See http://marc.theaimsgroup.com/?l=gentoo-osx&m=109211051719645&w=2 Also, please note the comment I added to the bugzilla page warning you not to do any work until we clear this up. I posted this before you updated this, although you tell me that you did not see my message. Regardless, even though you say you merged my changes, I notice that your revision does not have most of the fixes that I made. Xavier is currently working on the revision I sent, and I don't want his efforts to go in vein. Also, please note that he specifically stated that he was working on this and said not to do anything until he finished. Because of this, I think it is only fair that we work on Xavier's revision. I do not mean to undermine your work, but Xavier has been more than helpful and I would not want to undermine his efforts. Please, don't do ANY work until Xavier has finished fixing the original xml. We will work from there. I will merge the changes into his version once this is done,. Hasan, I wonder why you have helped us with the xml because you are not on the Documentation team for the project. Regardless, thanks for you work, I appreciate it greatly. I too hope that I do not sound accusatory or combative. Because I am the lead of the documentation group, I feel that it is my duty to take care of the rest of the logistics in merging the two revisions. I realize how frustrating it is when this sort of thing happens, but I really don't want to cause this problem to infect other people who are not even members of the gentoo for macos project, which is why I would like to start with Xavier's version. I think he has already fixed the broken xml. Regardless, the xml can be easily fixed, as I already did so. I will merge the versions once Xavier has finished, as your revision still does not have many of my fixes (they were mainly grammatical so I'd have to basically rewrite what you have right now to incorporate all of them.
Actually, after comparing the two revisions, I realized that it would be better for me to continue with your revision. Sorry, I was just upset, and I now see that you have more content in yours. I will just edit your revision. After I have done this, I will submit it. Again, I am sorry I posted this out of frustration that we duplicated work.
Actually, since i can't find the xml source of yours, I'm going to have to integrate the content from yours into my already existing xml. I'm going to do this now. I will post the updated xml when I finish.
XML source for my page located at http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml
Created attachment 37256 [details] merged two versions Ok, thanks. I have added some stuff to the xml. i attached a new xml. I was the one who wrote most of the guide, and I've changed the wording of your sections to reflect my writing style because it makes up most of the document and I am picky about that sort of thing. I hope that's ok. I also tried to take out redundant info.
Alexander and I just sat down and went over the revised version of the xml. We have prepared a second revision, available for public criticism. It's available at the same url: http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.html (change extension to xml for the xml source) comments, questions, criticisms, changes, and donations *wink* are all welcome.
Created attachment 37270 [details] Initial doc as it should have looked Thanks for sorting this out. I look forward to reading the final doc. We do have a GuideXML doc and it includes a chapter about coding style (http://www.gentoo.org/doc/en/xml-guide.xml#doc_chap3) I'm not fixing another messed up doc. This the original posted document as it should have looked, please follow our standards, thanks.
I made some changes which can be found at http://wonderwarp.com/alex/macos-guide.xml
Alexander: All of the changes you've made on that last revision were great! Thanks! I made one more change (on the section about the uninstall script -- took out 'perl' and re-organized so as to use proper linking style). I have updated the xml (and the html). The URLs remain the same for both. http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.html I skimmed both the howto and the tips/tricks for doc generation, but I will re-read and make sure that I haven't missed anything (in terms of style, etc).
Xavier: I apologize for your having to clean up xml. You should never have had to do that in the first place. Hopefully you will never have to again. I have cleaned up the xml on http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml (and I have also updated the html to reflect these changes). Alexander: I also added a warning about the volume name for CVS disk images; I just realized that it should be mentioned and wasn't. I did see something I didn't understand in attachmend 37270 ('Initial doc as it should have looked'): <!-- $Header$ --> Is this something that needs to be included in the xml? What does it mean? I didn't see any reference to it anywhere in the docs (although I'm known to be blind at times). Thanks for everything you've done so far, and in advance for everything else. :)
just one thing : could you change my mail (iznogoud_) to clement@varaldi.org. Additionnaly, you could also change the nickname to my realname : Clement VARALDI Thanks
The "<!-- $Header$ -->" thingie is for CVS to insert the revision information and such. It makes it easy for translators to see if the version they are translating is still the latest version, and if not between what versions they should compare to see the differences.
both xml source and html have been updated to reflect changes from the previous two comments on this bug. (name change, email change, and $Header$).
Created attachment 37354 [details] /doc/en/macos-guide.xml This has been a lively thread ;-) Thanks for everyone's contribution. Done minor edits, fixed typos & spelling mistakes, made doc DTD-compliant (<warn>, not <warning>). If I don't hear anything from you guys, this version will be published within 24 hours.
Updated the xml and html for yet another small content change. Only content removal this time, so there should be no need to go back and check it again. I have made the changes against the latest attachment, 37354. They are located in the normal places. :) Otherwise, everything should be fine to make it stable. We've had no traffic on our mailing list, but no news is sometimes good news (no protests yet).
Committed and linked from our index. Thanks a lot for your work, guys. PS: from now on, please post patches made with diff -Nut instead of a link to an updated version. Thanks.
Created attachment 37538 [details] italian translation of the xml guide I wrote this italian translation, if you like it...
I created a new bug (#60579) to take care of your Italian translation, as you already know ;-). Thanks a lot.
I'll work on the French translation as soon as the English one is validated.
