[llvm-dev] Combine TableGen documents?

[John Byrd via llvm-dev]

>
> > On Jul 31, 2020, at 1:49 PM, Paul C. Anagnostopoulos via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
> 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.
>

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

John Byrd
Gigantic Software
2321 E 4th Street
Suite C #429
Santa Ana, CA  92705-3862
http://www.giganticsoftware.com
T: (949) 892-3526 F: (206) 309-0850
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200804/081d2841/attachment.html>