Thanks! I quite enjoyed writing it. I will incorporate your comments and submit a new patch.

I did not yet attempt to find all the references to the existing two TableGen documents and change those references. I figure I would do that as a separate patch later. Does that make sense?

Could you comment on the '..' patch? https://reviews.llvm.org/D85585

Yep, as long as you're committed to doing it, I'm perfectly fine with doing that in a followup patch. You might want to land this at one of the old URLs to make that easier though.

Thank you again for driving this!

In D85838#2217330, @lattner wrote:

Yep, as long as you're committed to doing it, I'm perfectly fine with doing that in a followup patch. You might want to land this at one of the old URLs to make that easier though.

I think to do this, the file would have to be named the same as one of the old files. I gave the document a new title to avoid any conflicts with the old names. I don't mind hunting up all the existing references and changing them to point to the new document.

I will add a section on the dag type. However, I will do that as a future update, since it will take awhile to write the new section. In particular, I have to see how much is written elsewhere and include references as appropriate.

Hi Paul,

Please take a look at the LLVM Developer Policy and follow the instructions on commit access. :-)

In D85838#2219529, @lattner wrote:

Hi Paul,

Please take a look at the LLVM Developer Policy and follow the instructions on commit access. :-)

I appreciate the offer, but, as Paul Robinson will attest, I need more practice with Git. I'm reading a book on it for the third time, which I hope will do the trick.

I feel comfortable messing around with my own repository, but I'd appreciate someone else committing my next couple of patches.

I'm a little disappointed that this document does not describe the *intention* of TableGen, what exactly its output files are, their specific purposes, or where they are generally used in LLVM. It's possible that this information is ill suited for a reference manual, and belongs in a guide instead. Regardless, despite this draft's limitations, it's an improvement over the current state of things, and with a few improvements I'll happily sign off on it.

In D85838#2219986, @johnwbyrd wrote:

I'm a little disappointed that this document does not describe the *intention* of TableGen, what exactly its output files are, their specific purposes, or where they are generally used in LLVM. It's possible that this information is ill suited for a reference manual, and belongs in a guide instead. Regardless, despite this draft's limitations, it's an improvement over the current state of things, and with a few improvements I'll happily sign off on it.

I will attempt to be more specific about the purpose of TableGen. I don't think I can list "all" the uses of it, however, since it is a general-purpose tool.

I will address your other points and resubmit in the next few days. Thanks for the critique.

I will attempt to be more specific about the purpose of TableGen. I don't think I can list "all" the uses of it, however, since it is a general-purpose tool.

The uses of TableGen are finite and enumerable. An effort has been made to list all the uses of TableGen -- see llvm/docs/TableGen/BackEnds.rst . I am not convinced these descriptions are canonical.

In D85838#2220067, @johnwbyrd wrote:

I will attempt to be more specific about the purpose of TableGen. I don't think I can list "all" the uses of it, however, since it is a general-purpose tool.

The uses of TableGen are finite and enumerable. An effort has been made to list all the uses of TableGen -- see llvm/docs/TableGen/BackEnds.rst . I am not convinced these descriptions are canonical.

The uses are finite within the LLVM and Clang projects. But nothing stops someone outside these projects from using it.

https://www.embecosm.com/2015/04/14/utilizing-tablegen-for-non-compiling-processes/

The uses are finite within the LLVM and Clang projects. But nothing stops someone outside these projects from using it.
https://www.embecosm.com/2015/04/14/utilizing-tablegen-for-non-compiling-processes/

That project does not seem to be part of LLVM, so it's not clear to me why the reference guide should document it. Anyway, as you prefer.

In D85838#2220106, @johnwbyrd wrote:

The uses are finite within the LLVM and Clang projects. But nothing stops someone outside these projects from using it.
https://www.embecosm.com/2015/04/14/utilizing-tablegen-for-non-compiling-processes/

That project does not seem to be part of LLVM, so it's not clear to me why the reference guide should document it. Anyway, as you prefer.

Oh, I don't think that the reference should document it. I was just pointing that an exhaustive list of TableGen uses is not possible.

In D85838#2219986, @johnwbyrd wrote:

This concept is good, but it doesn't follow the parallel structure of headings in the rest of the document. The heading is the keyword. Use text to define the concept.

John: that is what you said about the heading for the let statement. I'm not sure I understand your objection. Can you elaborate?

John: that is what you said about the heading for the let statement. I'm not sure I understand your objection. Can you elaborate?

After reviewing the other headings, I see that my comment is in error. Please mark the comment as done.

First of all, thank you for doing this. I haven't gone through it fully yet. The main thing that is missing in my opinion is to remove stuff from the existing files. You include here a listing of TableGen syntax -- that's fine, but it's now redundant with what's in TableGen/LangRef.rst, and this redundancy is a very bad place for us to be in.

In D85838#2222000, @nhaehnle wrote:

First of all, thank you for doing this. I haven't gone through it fully yet. The main thing that is missing in my opinion is to remove stuff from the existing files. You include here a listing of TableGen syntax -- that's fine, but it's now redundant with what's in TableGen/LangRef.rst, and this redundancy is a very bad place for us to be in.

You are most welcome. My plan was to get this committed first. Note that this includes an update to the TableGen Overview to refer to this document rather than the two old ones. A search turns up no other references to the two old documents in the Clang or LLVM documentation. Then once this is committed, we can delete the two old files. (Is that what we do, delete them?)

Shall I wait for additional review comments from you?

In D85838#2222073, @Paul-C-Anagnostopoulos wrote:

In D85838#2222000, @nhaehnle wrote:

First of all, thank you for doing this. I haven't gone through it fully yet. The main thing that is missing in my opinion is to remove stuff from the existing files. You include here a listing of TableGen syntax -- that's fine, but it's now redundant with what's in TableGen/LangRef.rst, and this redundancy is a very bad place for us to be in.

You are most welcome. My plan was to get this committed first. Note that this includes an update to the TableGen Overview to refer to this document rather than the two old ones. A search turns up no other references to the two old documents in the Clang or LLVM documentation. Then once this is committed, we can delete the two old files. (Is that what we do, delete them?)

Why not just delete them at the same time? (them = LangIntro.rst and LangRef.rst, I assume) Making the change atomically like that feels more "right" to me. And after actually scanning those two docs again, yes, I agree that we can just delete them.

Shall I wait for additional review comments from you?

I've sent a few more a few minutes ago, but that should cover it as far as I'm concerned.

In D85838#2222091, @nhaehnle wrote:

In D85838#2222073, @Paul-C-Anagnostopoulos wrote:

In D85838#2222000, @nhaehnle wrote:

First of all, thank you for doing this. I haven't gone through it fully yet. The main thing that is missing in my opinion is to remove stuff from the existing files. You include here a listing of TableGen syntax -- that's fine, but it's now redundant with what's in TableGen/LangRef.rst, and this redundancy is a very bad place for us to be in.

You are most welcome. My plan was to get this committed first. Note that this includes an update to the TableGen Overview to refer to this document rather than the two old ones. A search turns up no other references to the two old documents in the Clang or LLVM documentation. Then once this is committed, we can delete the two old files. (Is that what we do, delete them?)

Why not just delete them at the same time? (them = LangIntro.rst and LangRef.rst, I assume) Making the change atomically like that feels more "right" to me. And after actually scanning those two docs again, yes, I agree that we can just delete them.

Shall I wait for additional review comments from you?

I've sent a few more a few minutes ago, but that should cover it as far as I'm concerned.

I will address your comments and submit a final patch.

@nhaehnle, but please tell me how to delete the two old files. Do I simply do a 'git rm' and then commit that along with the final ProfRef.rst?