> IIRC, it took me several hours way back when to figure out how to just > run one specific testcase (as opposed to the whole suite), and I can > never remember the right incantation, so I wrote it up on the wiki page, > and now just go there when I find myself wondering the right incantation.
This is documented in several places: https://gcc.gnu.org/install/test.html https://gcc.gnu.org/wiki/Testing_GCC https://gcc.gnu.org/wiki/HowToPrepareATestcase?highlight=%28RUNTESTFLAGS%29 https://gcc.gnu.org/wiki/TestCaseWriting?highlight=%28RUNTESTFLAGS%29 I'm not saying that you should have found it, but that the information is not easy to find even if it is there. The question is why? > I can never find things in the .texi files or the HTML built from them. Or the ones that we do not build from them, since a lot of important information is not on the *.texi files but in other HTML pages... > Having vital documentation live on a *wiki* disturbs me. Well, it is better than having really outdated documentation or not having any documentation at all, which is often the case in GCC. I would like to think of the wiki as a prototyping/staging area. Unfortunately, right now it is more like a landfill. > I have a pet theory that any time that I have to use a wiki can be > seen as a symptom of dysfunction in a project - why am I editing a > wiki, rather that a file in a source tree? Some of the reasons might > be (not singling out gcc here): > * a project has chosen an overly cumbersome source representation for > its docs, and is using a wiki to avoid e.g. having to type DocBook > (I speak as a reformed former DocBook enthusiast). > * a project doesn't have a good place to put said documentation (e.g. we > have a user manual and an installation manual; do we have a contributor > manual? Though why make such distinctions? Maybe we can build a > smoother on-ramp for turning users into contributors?) > ...etc and I would add (singling out GCC here): * Documentation spread between webpages, html pages generated from *.texi and the wiki. * From all the above, the wiki is in fact the easiest to edit because... * texi requires review, reviews require someone to review, and if there are too few people reviewing patches, there are even fewer people reviewing doc patches. If I find something wrong or that should be better documented, I need: to write a patch, to write a changelog, submit it, wait from days to weeks (if ever reviewed), get feedback, write another patch, perhaps another changelog, submit it, wait from days to weeks (if ever reviewed)... * html pages: CVS. Do I need to say more? * Plus all this: https://gcc.gnu.org/wiki/DocumentationOverviewIssues Example: if someone says for the nth time "I know my code is undefined but...". I could fight with CVS, submit a patch for https://gcc.gnu.org/faq.html, wait wait wait wait wait, get it reviewed, then CVS, ups I did some html mistake, so it was not applied, fix it, then CVS, then send the link to the user. Or, I could directly edit https://gcc.gnu.org/wiki/FAQ#undefinedbut, then send the link to the user. And IMHO, the result in the wiki, despite all the shortcomings of MoinMoin (which are plenty), looks nicer than both the CVS html webpages and the HTML generated from texi. I'm not arguing that the reviewers are not doing their job. I fully understand that they are doing as much as they can and that GCC is lacking contributors and the situation is not getting better. My argument would go in the other direction: * Do not require any pre-commit review, except for major rewrites and additions. * Do not require changelogs for documentation patches: a commit message and 'svn log --verbose' should be enough. * Get rid of CVS. * Put all HTML pages in SVN under trunk/ and add a commit-hook to upload it, so there is the shortest delay possible between commit and showing up online. * Anything that looks remotely like documentation should come from the same sources as the real documentation (FAQs, Howtos, etc.), and hyperlink the hell out of it. * Add a Getting Started/Contributor manual. Add one per piece of GCC: Ada, libstdc++, etc... * Aggressively move things that are nice from the wiki to the documentation and hyperlink to it. * Aggressively cleanup the wiki from outdated and incoherent stuff. In summary, I totally agree with your rant. > "a wiki is where good documentation goes to die" Indeed: https://gcc.gnu.org/wiki/GettingStarted Indeed2: https://gcc.gnu.org/wiki/Visibility Indeed3: https://gcc.gnu.org/wiki/LinkTimeOptimizationFAQ Indeed4: https://gcc.gnu.org/wiki/Math_Optimization_Flags Cheers, Manuel. Bonus: Try to see how long can you go answering every question about using/developing GCC with a link to the documentation or the wiki. Bonusx2: Mentor someone to become a new contributor: Try to answer each of their questions with a link to the documentation or the wiki. See how long until they give up.
