[jit] Update the docs

[Manuel López-Ibáñez]

> 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.