Combine TableGen documents?

I've spent the last few days reading and rereading the TableGen documents. I thought I would try to improve the "Language Introduction" and the "Language Reference." But now I think it makes sense to combine the two documents. It isn't really possible for someone to use TableGen without reading both of them. Also, the factoring is unusual in some places. For example, the complete list of value expression facilities is in the Introduction rather than the Reference.

What do people think of this idea?

One reason not to do it is that it might be a waste of energy: Most of the uses of TableGen may already be in place.

+David Greene as someone who might have an opinion.

I don’t have a strong opinion, but if someone wants to try to make the docs better and more friendly to them I’m totally down :slight_smile:

-eric

Eric Christopher <echristo@gmail.com> writes:

+David Greene<mailto:dag@cray.com> as someone who might have an opinion.

I don't have a strong opinion, but if someone wants to try to make the
docs better and more friendly to them I'm totally down :slight_smile:

Thanks for the CC. I think combining them makes sense. I recall having
similar issues finding things in the past. If you go ahead and do this,
you can add me as a reviewer for approval.

            -David

+1 for combining. I tried learning TableGen in April. My experience
was also that I had to consult both documents to understand a concept.
There are some concepts for which LangIntro.rst provides more detailed
information while another set of concepts for which LangRef.rst
provides more detailed information.

Thanks, David. I have started a new document titled "TableGen Programmer's Guide." Getting it in reasonable shape will take a few days. Then I'll have to do some research on the code to find out how certain things really work, such as DEFVAR and !CAST. I may even understand some of the code when I'm done.

Thank you for driving this Paul, I agree that it is better to have one doc on TableGen. This has been a point of confusion for me as well - when I land in the wrong one and can’t find what I’m looking for :-).

-Chris

The idea has been well received, for which I am grateful.

What is the best way to have a new document reviewed? Submit it with Phabricator, or first send it around to a few people directly?

If either of you feel like responding to this suggestion, I'd appreciate it.

http://lists.llvm.org/pipermail/llvm-dev/2020-July/143912.html

~~ Paul

I’d submit a patch into Phabricator. Re the other thread, I think that the discussion should continue there to avoid mixing the topics.

Thank you again for pushing on this Paul!

-Chris

What is the best way to have a new document reviewed? Submit it with Phabricator, or first send it around to a few people directly?

Yes, Phabricator -- please do mention it here as well :slight_smile:

Cheers,
Nicolai

Similarly, I’ve just survived writing most of a new backend, and TableGen’s documentation was unfortunate.

Chris’s old original documentation was incomplete, but it was clear, and as such the original sketches were superior to the current state of TableGen documentation.

TableGen needs a proper programmer’s guide, which differs from a reference. I actually started such a rewrite here, but I never tried submitting it to Phabricator, because it wasn’t clear to me who was responsible for review:

https://github.com/johnwbyrd/llvm-mos/blob/master/llvm/docs/TableGen/index.rst
https://github.com/johnwbyrd/llvm-mos/blob/master/llvm/docs/TableGen/Deficiencies.rst

Most of the concepts behind TableGen are simple. They should be communicated simply, as per Chris’s original documentation. The things that are not simple, were developed as special-purpose solutions to practical problems.

The current documentation should be rewritten almost entirely from scratch, with a strong focus on organizing the document in a reasonable reading order, with a target audience of those who are working on LLVM backends. Patching the documentation has gotten it to its current state of confusion, and the process should be discontinued.

Likewise, I’ll mention that if anyone wants to finance authorship of proper TableGen and/or backend documentation, I’d be game to research it and write it.

I wasn't sure how to respond to John Byrd's post, since it wasn't addressed to me. So I've responded to Nicolai's. (Sorry about the spurious post in the TableGen trace facility thread.)

I'm reasonably far along in the process of writing a new Programmer's Guide for TableGen. I will continue working on it and submit it for review. I expect to do some rewriting as a result.

John: Would you like me to respect a copyright on your documents linked below? I wouldn't take any text verbatim, but some of the ways of describing TableGen give me ideas.