Hi doc team With Markus Dittrich, we did a full new draft of the BLAS/LAPACK documentation. The document describes a user and developer guide for what we are currently making the transition, and should be available soon in the portage main tree (we are still doing some tests in the science overlay). Unfortunately neither of us has taken the time to be proficient in GuideXML. If one of you could take a look, that would be great. The txt files are: http://dev.gentoo.org/~bicatali/blas-lapack.txt and a better revision and wording in http://dev.gentoo.org/~markusle/blas-lapack-r1.txt Sébastien (sci team) Reproducible: Always
Not the GDP's responsibility, but I'll see about updates. Watch the commit logs to the existing URL to see how I do it -- it might help you understand GuideXML a lil' bit more.
(In reply to comment #0) Now, just to be clear, you and Markus are the authors of this new doc, correct? Just so you know, the link in Markus' devspace is an error 404 -- can you post it somewhere? All I have to go on is http://dev.gentoo.org/~bicatali/blas-lapack.txt, so I will assume you want this doc to completely replace the existing doc at the URL provided in the bug header.
Hi Josh Thanks for the help, it is very welcomed! > Now, just to be clear, you and Markus are the authors of this new doc, correct? Yes. > Just so you know, the link in Markus' devspace is an error 404 -- can you post > it somewhere? All I have to go on is Ooops, sorry, the correct URL is http://dev.gentoo.org/~markusle/blas-lapack.txt-r1 I will check the commit on doc then. Sébastien
Hi Josh, Thanks a lot for your help! If you could do the initial change over that would be great. I can pick up maintaining the guide after that if that's all right with the docs team. Do we have any docs on how to use GuideXML on our pages? Thanks, Markus
(In reply to comment #4) > Do we have any docs on how to use GuideXML on our pages? http://gdp.gentoo.org Scroll down to the resources section.
Created attachment 133839 [details] blas-lapack.xml Okay, guys, sorry it took so long. I've been on devaway for a few months, and it's a Herculean task to GuideXMLify such a long, complex document from scratch. Anyway, here's the document given to me, with proper GuideXML and some spelling/grammar fixes where necessary. You can view a SHINY, PRETTY rendered version at my devspace: http://dev.gentoo.org/~nightmorph/blas-lapack.xml
Created attachment 133873 [details] blas-lapack.xml Hi Josh, Many thanks! It looks a lot more professional. Here is a revised version, where I only changed small stuff. I also removed the warning since the Intel compilers are now in portage. Sébastien
(In reply to comment #6) > You can view a SHINY, PRETTY rendered version at my devspace: > http://dev.gentoo.org/~nightmorph/blas-lapack.xml > Josh, That's fantastic! Thank you so much for your help! cheers, Markus
(In reply to comment #7) > Created an attachment (id=133873) [edit] > blas-lapack.xml > > Hi Josh, > > Many thanks! It looks a lot more professional. Here is a revised version, where > I only changed small stuff. I also removed the warning since the Intel > compilers are now in portage. > > Sébastien > I'll have a careful look at it later when I have some time. Should I commit it once I am done? Thanks, Markus
> Should I commit it once I am done? Fine with me.
Created attachment 133910 [details, diff] blas-lapack.xml.patch This is a patch for the version you guys put up. It fixes line-wrapping (80 columns is the limit), an English grammar fix, and it takes out the unnecessary ® symbol. Really, you don't have to include that symbol; should be consistent with other company names without it in the doc, like AMD. lso, *none* of the other documentation or projects bother to use Intel® or similar trademark symbols. ;) Otherwise, the new version looks great; there are no changes to make besides these.
Comment on attachment 133873 [details] blas-lapack.xml Didn't mean to obsolete this. Use the patch I provided together with this doc, and you're all set. :)
> ® symbol. Really, you don't have to include that symbol; should be consistent > with other company names without it in the doc, like AMD. lso, *none* of the > other documentation or projects bother to use Intel® or similar trademark > symbols. ;) I wish we could remove all the trademarking stuff, really. I am not sure we could do it though. I may be overly cautious: AMD is an acronym and Intel is a name, and they like their registered trademark. If we don't bother, I'm fine with it (I don't live in the US, so I hope they can't sue me). Otherwise, I think we are good to go. Markus?
(In reply to comment #13) > > Otherwise, I think we are good to go. Markus? > Yes, I think so, too. I can commit it tonight. I meant to do it over the weekend, but updating and committing all the octave-forge packages + eclass to the overlay took me much longer than anticipated so I didn't get to it. I have no problem keeping the ®, better safe than sorry (since I live in the US ;) unless there is an explicit Gentoo policy to not have them. Thanks. Markus
After some wrestling with our beloved Gentoo XML-QA-checker (which was correct, btw) I've finally committed the new guide. I've revised a few things and will probably go over it once more sometime soon. I think it sounds nice and is definitely a big improvement over what we had before. Thanks again to Josh for his hard work. cheers, Markus
BTW: I talked to our main web content person here at work and she recommended to always use the ® for official web documentation. Apparently there have been instances of particular vendors being pretty "pushy" about this.
