<div dir="ltr"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">> On Jul 31, 2020, at 1:49 PM, Paul C. Anagnostopoulos via llvm-dev <<a href="mailto:llvm-dev@lists.llvm.org" target="_blank">llvm-dev@lists.llvm.org</a>> wrote:<br>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.<br></blockquote></div><div><br></div>Similarly, I've just survived writing most of a new backend, and TableGen's documentation was unfortunate.<div><br></div><div>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.<div><br></div><div>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:</div><div><br></div><div><a href="https://github.com/johnwbyrd/llvm-mos/blob/master/llvm/docs/TableGen/index.rst">https://github.com/johnwbyrd/llvm-mos/blob/master/llvm/docs/TableGen/index.rst</a>  </div><div><a href="https://github.com/johnwbyrd/llvm-mos/blob/master/llvm/docs/TableGen/Deficiencies.rst">https://github.com/johnwbyrd/llvm-mos/blob/master/llvm/docs/TableGen/Deficiencies.rst</a>  <br></div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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.<br><div><div dir="ltr" class="gmail_signature">---<br><br>John Byrd<br>Gigantic Software<br>2321 E 4th Street<br>Suite C #429<br>Santa Ana, CA  92705-3862<br><a href="http://www.giganticsoftware.com" target="_blank">http://www.giganticsoftware.com</a><br>T: (949) 892-3526 F: (206) 309-0850</div></div></div></div></div>