[TableGen] Update xxx-tblgen command document

[Paul-C-Anagnostopoulos]

Summary

This revision updates the xxx-tblgen command document that describes the tblgen commands. It now includes the options for all three xxx-tblgen commands.

I also took the opportunity to add some cross-references between documents.

And I eliminated Deficiencies.rst, since it contained no more information that Index.rst.

I will auto-LGTM this in 48 hours.

[Paul-C-Anagnostopoulos]

I'll push this revision now.

[aaronpuchert]

This generates a man page for xxx-tblgen, though arguably no such tool exists.

Couldn't we make this build a man page for llvm-tblgen and then create symlinks from clang-tblgen and mlir-tblgen? Probably not easy, at least I can't find anything right now about how to do this with Sphinx.

But perhaps we could at least go back to the original title tblgen, which matches the file name and doesn't require a user to infer that xxx is a placeholder?

[Paul-C-Anagnostopoulos]

How about the title "tblgen Family - Target Description to C++ Code" and then I list the three command names in the Synopsis?

[aaronpuchert]

In D90186#2656329, @Paul-C-Anagnostopoulos wrote:

How about the title "tblgen Family - Target Description to C++ Code" and then I list the three command names in the Synopsis?

Yes, this sounds good. A synopsis can indeed list different ways to invoke a command, or different commands.

[craig.topper]

Is there some way we can put the clang-tblgen and mlir-tblgen documentation into their respective projects. Seems like making someone update documentation in the llvm base project when they update tblgen in the clang/mlir project is a recipe for forgetting to do it.

[Paul-C-Anagnostopoulos]

The problem is all the common options. You know if we repeat those in three places they will quickly become inconsistent.

What if I add two short documents that simply refer to the primary one? Then at least a clang or mlir developer will find those documents in the appropriate docs/commandguide directory and know to update the primary document.

Should I call them clang-tblgen.rst and mlir-tblgen.rst?

[aaronpuchert]

In D90186#2657045, @Paul-C-Anagnostopoulos wrote:

The problem is all the common options. You know if we repeat those in three places they will quickly become inconsistent.

Agreed, we don't want to duplicate them.

What if I add two short documents that simply refer to the primary one? Then at least a clang or mlir developer will find those documents in the appropriate docs/commandguide directory and know to update the primary document.

Or even three? One for each variant ({llvm,clang,mlir}-tblgen), and one for the common options (let's say tblgen).

Should I call them clang-tblgen.rst and mlir-tblgen.rst?

Yes, having the same name as the commands should make them easy to find. On Linux at least this is installed as man page and it's a rule that man pages should be named like the command.

[Paul-C-Anagnostopoulos]

I wasn't thinking of taking out the common ones and then having four documents. Let's just have three. The main document has everything. The other two are just stubs that refer to the main document.

[craig.topper]

The are 4 tblgens. lldb has one too.

[Paul-C-Anagnostopoulos]

Which apparently isn't mentioned anywhere. I will add documentation for it to the main file and also include a stub that references the main file.

llvm/docs/CommandGuide/tblgen.rst

-tblgen - Target Description To C++ Code Generator
-=================================================
+xxx-tblgen: Target Description to C++ Code
+==========================================
 
 .. program:: tblgen
 
 SYNOPSIS
 --------
 
-:program:`tblgen` [*options*] [*filename*]
+:program:`xxx-tblgen` [*options*] [*filename*]
 
 DESCRIPTION
 -----------
 
-:program:`tblgen` translates from target description (``.td``) files into C++
-code that can be included in the definition of an LLVM target library.  Most
-users of LLVM will not need to use this program.  It is only for assisting with
-writing an LLVM target backend.
-
-The input and output of :program:`tblgen` is beyond the scope of this short
-introduction; please see the :doc:`introduction to TableGen
-<../TableGen/index>`.
+:program:`xxx-tblgen` is a family of programs that translates target
+description (``.td``) files into C++ code and other output formats. Most
+users of LLVM will not need to use this program. It is used only for
+writing parts of the compiler or LLVM target backends.
+
+The details of the input and output of :program:`xxx-tblgen` is beyond the
+scope of this short introduction; please see the :doc:`TableGen Overview
+<../TableGen/index>` for an introduction and for references to additional
+TableGen documents.
 
-The *filename* argument specifies the name of a Target Description (``.td``)
-file to read as input.
+The *filename* argument specifies the name of the Target Description (``.td``)
+file that TableGen processes.
 
 OPTIONS
 -------
 
-.. program:: tblgen
+General Options
+~~~~~~~~~~~~~~~
 
 .. option:: -help
 
  Print a summary of command line options.
 
-.. option:: -o filename
+.. option:: -D=macroname
 
- Specify the output file name.  If ``filename`` is ``-``, then
- :program:`tblgen` sends its output to standard output.
+  Specify the name of a macro to be defined. The name is defined, but it
+  has no particular value.
+
+.. option:: -d=filename
+
+  Specify the name of the dependency filename.
+
+.. option:: --debug
+
+  Enable debug output.
+
+.. option:: -dump-json
+
+ Print a JSON representation of all records, suitable for further
+ automated processing.
 
 .. option:: -I directory
 
  Specify where to find other target description files for inclusion.  The
  ``directory`` value should be a full or partial path to a directory that
  contains target description files.
 
-.. option:: -asmparsernum N
+.. option:: -o filename
 
- Make -gen-asm-parser emit assembly writer number ``N``.
+ Specify the output file name.  If ``filename`` is ``-``, then
+ :program:`xxx-tblgen` sends its output to standard output.
 
-.. option:: -asmwriternum N
+.. option:: -print-records
 
- Make -gen-asm-writer emit assembly writer number ``N``.
+ Print all classes and records to standard output (default option).
 
-.. option:: -class className
+.. option:: -print-detailed-records
 
- Print the enumeration list for this class.
+  Print a detailed report of all global variables, classes, and records
+  to standard output.
 
-.. option:: -print-records
+.. option:: --stats
 
- Print all records to standard output (default).
+  Enable statistics output.
 
-.. option:: -dump-json
+.. option:: -write-if-changed
 
- Print a JSON representation of all records, suitable for further
- automated processing.
+  Write the output file only if it is new or has changed. The default
+  is true.
 
-.. option:: -print-enums
+llvm-tblgen Options
+~~~~~~~~~~~~~~~~~~~
 
- Print enumeration values for a class.
-
-.. option:: -print-sets
+.. option:: -gen-asm-matcher
 
- Print expanded sets for testing DAG exprs.
+ Generate assembly instruction matcher.
 
-.. option:: -gen-emitter
+.. option:: -match-prefix=prefix
 
- Generate machine code emitter.
+  Make -gen-asm-matcher match only instructions with the given *prefix*.
 
-.. option:: -gen-register-info
+.. option:: -gen-asm-parser
 
- Generate registers and register classes info.
+ Generate assembly instruction parser.
 
-.. option:: -gen-instr-info
+.. option:: -asmparsernum=n
 
- Generate instruction descriptions.
+ Make -gen-asm-parser emit assembly parser number *n*.
 
 .. option:: -gen-asm-writer
 
- Generate the assembly writer.
+ Generate assembly writer.
 
-.. option:: -gen-disassembler
+.. option:: -asmwriternum=n
 
- Generate disassembler.
+ Make -gen-asm-writer emit assembly writer number *n*.
 
-.. option:: -gen-pseudo-lowering
+.. option:: -gen-attrs
 
- Generate pseudo instruction lowering.
+  Geneerate attributes.
+
+.. option:: -gen-automata
+
+  Generate generic automata.
+
+.. option:: -gen-callingconv
+
+  Generate calling convention descriptions.
+
+.. option:: -gen-compress-inst-emitter
+
+  Generate RISCV compressed instructions.
+
+.. option:: -gen-ctags
+
+  Generate ctags-compatible index.
 
 .. option:: -gen-dag-isel
 
- Generate a DAG (Directed Acyclic Graph) instruction selector.
+ Generate a DAG (directed acyclic graph) instruction selector.
 
-.. option:: -gen-asm-matcher
+.. option:: -instrument-coverage
 
- Generate assembly instruction matcher.
+  Make -gen-dag-isel generate tables to help identify the patterns matched.
+
+.. option:: -omit-comments
+
+  Make -gen-dag-isel omit comments. The default is false.
 
 .. option:: -gen-dfa-packetizer
 
  Generate DFA Packetizer for VLIW targets.
 
+.. option:: -gen-directive-decl
+
+  Generate directive related declaration code (header file).
+
+.. option:: -gen-directive-gen
+
+  Generate directive related implementation code part.
+
+.. option:: -gen-directive-impl
+
+  Generate directive related implementation code.
+
+.. option:: -gen-disassembler
+
+  Generate disassembler.
+
+.. option:: -gen-emitter
+
+ Generate machine code emitter.
+
+.. option:: -gen-exegesis
+
+  Generate llvm-exegesis tables.
+
 .. option:: -gen-fast-isel
 
   Generate a "fast" instruction selector.
 
-.. option:: -gen-subtarget
+.. option:: -gen-global-isel
 
- Generate subtarget enumerations.
+  Generate GlobalISel selector.
+
+.. option:: -gisel-coverage-file=filename
+
+  Specify the file from which to retrieve coverage information.
+
+.. option:: -instrument-gisel-coverage
+
+  Make -gen-global-isel generate coverage instrumentation.
+
+.. option:: -optimize-match-table
+
+  Make -gen-global-isel generate an optimized version of the match table.
+
+.. option:: -warn-on-skipped-patterns
+
+  Make -gen-global-isel explain why a pattern was skipped for inclusion.
+
+.. option:: -gen-global-isel-combiner
+
+  Generate GlobalISel combiner.
+
+.. option:: -combiners=list
+
+  Make -gen-global-isel-combiner emit the specified combiners.
+
+.. option:: -gicombiner-show-expansions
+
+  Make -gen-global-isel-combiner use C++ comments to indicate occurences
+  of code expansion.
+
+.. option:: -gicombiner-stop-after-build
+
+  Make -gen-global-isel-combiner stop processing after building the match tree.
+
+.. option:: -gicombiner-stop-after-parse
+
+  Make -gen-global-isel-combiner stop processing after parsing rules
+  and dump state.
+
+.. option:: -gen-instr-info
+
+ Generate instruction descriptions.
+
+.. option:: -gen-instr-docs
+
+ Generate instruction documentation.
 
 .. option:: -gen-intrinsic-enums
 
  Generate intrinsic enums.
 
+.. option:: -intrinsic-prefix=prefix
+
+  Make -gen-intrinsic-enums generate intrinsics with this target *prefix*.
+
 .. option:: -gen-intrinsic-impl
 
- Generate intrinsic implementation.
+ Generate intrinsic information.
 
-.. option:: -gen-tgt-intrinsic
+.. option:: -gen-opt-parser-defs
 
- Generate target intrinsic information.
+  Generate options definitions.
 
-.. option:: -gen-enhanced-disassembly-info
+.. option:: -gen-opt-rst
 
- Generate enhanced disassembly info.
+  Generate option RST.
 
-.. option:: -gen-exegesis
+.. option:: -gen-pseudo-lowering
 
- Generate llvm-exegesis tables.
+ Generate pseudo instruction lowering.
+
+.. option:: -gen-register-bank
+
+  Generate register bank descriptions.
+
+.. option:: -gen-register-info
+
+  Generate registers and register classes info.
+
+.. option:: -register-info-debug
+
+  Make -gen-register-info dump register information for debugging.
+
+.. option:: -gen-searchable-tables
+
+  Generate generic searchable tables. See :doc:`TableGen BackEnds <./BackEnds>`
+  for a detailed description.
+
+.. option:: -gen-subtarget
+
+ Generate subtarget enumerations.
+
+.. option:: -gen-x86-EVEX2VEX-tables
+
+  Generate X86 EVEX to VEX compress tables.
+
+.. option:: -gen-x86-fold-tables
+
+  Generate X86 fold tables.
+
+.. option:: -long-string-literals
+
+  When emitting large string tables, prefer string literals over
+  comma-separated char literals. This can be a readability and
+  compile-time performance win, but upsets some compilers.
+
+.. option:: -print-enums
+
+ Print enumeration values for a class.
+
+.. option:: -class=classname
+
+ Make -print-enums print the enumeration list for the specified class.
+
+.. option:: -print-sets
+
+ Print expanded sets for testing DAG exprs.
 
 .. option:: -version
 
- Show the version number of this program.
+ Show the version number of the program.
+
+
+clang-tblgen Options
+~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -gen-clang-attr-classes
+
+  Generate Clang attribute clases.
+
+.. option:: -gen-clang-attr-parser-string-switches
+
+  Generate all parser-related attribute string switches.
+
+.. option:: -gen-clang-attr-subject-match-rules-parser-string-switches
+
+  Generate all parser-related attribute subject match rule string switches.
+
+.. option:: -gen-clang-attr-impl
+
+  Generate Clang attribute implementations.
+
+.. option:: -gen-clang-attr-list"
+
+  Generate a Clang attribute list.
+
+.. option:: -gen-clang-attr-subject-match-rule-list
+
+  Generate a Clang attribute subject match rule list.
+
+.. option:: -gen-clang-attr-pch-read
+
+  Generate Clang PCH attribute reader.
+
+.. option:: -gen-clang-attr-pch-write
+
+  Generate Clang PCH attribute writer.
+
+.. option:: -gen-clang-attr-has-attribute-impl
+
+  Generate a Clang attribute spelling list.
+
+.. option:: -gen-clang-attr-spelling-index
+
+  Generate a Clang attribute spelling index.
+
+.. option:: -gen-clang-attr-ast-visitor
+
+  Generate a recursive AST visitor for Clang attributes.
+
+.. option:: -gen-clang-attr-template-instantiate
+
+  Generate a Clang template instantiate code.
+
+.. option:: -gen-clang-attr-parsed-attr-list
+
+  Generate a Clang parsed attribute list.
+
+.. option:: -gen-clang-attr-parsed-attr-impl
+
+  Generate the Clang parsed attribute helpers.
+
+.. option:: -gen-clang-attr-parsed-attr-kinds
+
+  Generate a Clang parsed attribute kinds.
+
+.. option:: -gen-clang-attr-text-node-dump
+
+  Generate Clang attribute text node dumper.
+
+.. option:: -gen-clang-attr-node-traverse
+
+  Generate Clang attribute traverser.
+
+.. option:: -gen-clang-diags-defs
+
+  Generate Clang diagnostics definitions.
+
+.. option:: -clang-component component
+
+  Only use warnings from specified component.
+
+.. option:: -gen-clang-diag-groups
+
+  Generate Clang diagnostic groups.
+
+.. option:: -gen-clang-diags-index-name
+
+  Generate Clang diagnostic name index.
+
+.. option:: -gen-clang-basic-reader
+
+  Generate Clang BasicReader classes.
+
+.. option:: -gen-clang-basic-writer
+
+  Generate Clang BasicWriter classes.
+
+.. option:: -gen-clang-comment-nodes
+
+  Generate Clang AST comment nodes.
+
+.. option:: -gen-clang-decl-nodes
+
+  Generate Clang AST declaration nodes.
+
+.. option:: -gen-clang-stmt-nodes
+
+  Generate Clang AST statement nodes.
+
+.. option:: -gen-clang-type-nodes
+
+  Generate Clang AST type nodes.
+
+.. option:: -gen-clang-type-reader
+
+  Generate Clang AbstractTypeReader class.
+
+.. option:: -gen-clang-type-writer
+
+  Generate Clang AbstractTypeWriter class.
+
+.. option:: -gen-clang-opcodes
+
+  Generate Clang constexpr interpreter opcodes.
+
+.. option:: -gen-clang-sa-checkers
+
+  Generate Clang static analyzer checkers.
+
+.. option:: -gen-clang-comment-html-tags
+
+  Generate efficient matchers for HTML tag names that are used in
+  documentation comments.
+
+.. option:: -gen-clang-comment-html-tags-properties
+
+  Generate efficient matchers for HTML tag properties.
+
+.. option:: -gen-clang-comment-html-named-character-references
+
+  Generate function to translate named character references to UTF-8 sequences.
+
+.. option:: -gen-clang-comment-command-info
+
+  Generate command properties for commands that are used in documentation comments.
+
+.. option:: -gen-clang-comment-command-list
+
+  Generate list of commands that are used in documentation comments.
+
+.. option:: -gen-clang-opencl-builtins
+
+  Generate OpenCL builtin declaration handlers.
+
+.. option:: -gen-arm-neon
+
+  Generate ``arm_neon.h`` for Clang.
+
+.. option:: -gen-arm-fp16
+
+  Generate ``arm_fp16.h`` for Clang.
+
+.. option:: -gen-arm-bf16
+
+  Generate ``arm_bf16.h`` for Clang.
+
+.. option:: -gen-arm-neon-sema
+
+  Generate ARM NEON sema support for Clang.
+
+.. option:: -gen-arm-neon-test
+
+  Generate ARM NEON tests for Clang.
+
+.. option:: -gen-arm-sve-header
+
+  Generate ``arm_sve.h`` for Clang.
+
+.. option:: -gen-arm-sve-builtins
+
+  Generate ``arm_sve_builtins.inc`` for Clang.
+
+.. option:: -gen-arm-sve-builtin-codegen
+
+  Generate ``arm_sve_builtin_cg_map.inc`` for Clang.
+
+.. option:: -gen-arm-sve-typeflags
+
+  Generate ``arm_sve_typeflags.inc`` for Clang.
+
+.. option:: -gen-arm-sve-sema-rangechecks
+
+  Generate ``arm_sve_sema_rangechecks.inc`` for Clang.
+
+.. option:: -gen-arm-mve-header
+
+  Generate ``arm_mve.h`` for Clang.
+
+.. option:: -gen-arm-mve-builtin-def
+
+  Generate ARM MVE builtin definitions for Clang.
+
+.. option:: -gen-arm-mve-builtin-sema
+
+  Generate ARM MVE builtin sema checks for Clang.
+
+.. option:: -gen-arm-mve-builtin-codegen
+
+  Generate ARM MVE builtin code-generator for Clang.
+
+.. option:: -gen-arm-mve-builtin-aliases
+
+  Generate list of valid ARM MVE builtin aliases for Clang.
+
+.. option:: -gen-arm-cde-header
+
+  Generate ``arm_cde.h`` for Clang.
+
+.. option:: -gen-arm-cde-builtin-def
+
+  Generate ARM CDE builtin definitions for Clang.
+
+.. option:: -gen-arm-cde-builtin-sema
+
+  Generate ARM CDE builtin sema checks for Clang.
+
+.. option:: -gen-arm-cde-builtin-codegen
+
+  Generate ARM CDE builtin code-generator for Clang.
+
+.. option:: -gen-arm-cde-builtin-aliases
+
+  Generate list of valid ARM CDE builtin aliases for Clang.
+
+.. option:: -gen-attr-docs
+
+  Generate attribute documentation.
+
+.. option:: -gen-diag-docs
+
+  Generate diagnostic documentation.
+
+.. option:: -gen-opt-docs
+
+  Generate option documentation.
+
+.. option:: -gen-clang-data-collectors
+
+  Generate data collectors for AST nodes.
+
+.. option:: -gen-clang-test-pragma-attribute-supported-attributes
+
+  Generate a list of attributes supported by ``#pragma`` Clang attribute for
+  testing purposes.
+
+
+
+mlir-tblgen Options
+~~~~~~~~~~~~~~~~~~~
+
+.. option:: -gen-avail-interface-decls
+
+  Generate availability interface declarations.
+
+.. option:: -gen-avail-interface-defs
+
+  Generate op interface definitions.
+
+.. option:: -gen-dialect-doc
+
+  Generate dialect documentation.
+
+.. option:: -dialect
+
+  The dialect to generate.
+
+.. option:: -gen-directive-decl
+
+  Generate declarations for directives (OpenMP, etc.).
+
+.. option:: -gen-enum-decls
+
+  Generate enum utility declarations.
+
+.. option:: -gen-enum-defs
+
+  Generate enum utility definitions.
+
+.. option:: -gen-enum-from-llvmir-conversions
+
+  Generate conversions of EnumAttrs from LLVM IR.
+
+.. option:: -gen-enum-to-llvmir-conversions
+
+  Generate conversions of EnumAttrs to LLVM IR.
+
+.. option:: -gen-llvmir-conversions
+
+  Generate LLVM IR conversions.
+
+.. option:: -gen-llvmir-intrinsics
+
+  Generate LLVM IR intrinsics.
+
+.. option:: -llvmir-intrinsics-filter
+
+  Only keep the intrinsics with the specified substring in their record name.
+
+.. option:: -dialect-opclass-base
+
+  The base class for the ops in the dialect we are to emit.
+
+.. option:: -gen-op-decls
+
+  Generate operation declarations.
+
+.. option:: -gen-op-defs
+
+  Generate operation definitions.
+
+.. option:: -asmformat-error-is-fatal
+
+  Emit a fatal error if format parsing fails.
+
+.. option:: -op-exclude-regex
+
+  Regular expression of name of ops to exclude (no filter if empty).
+
+.. option:: -op-include-regex
+
+  Regular expression of name of ops to include (no filter if empty).
+
+.. option:: -gen-op-doc
+
+  Generate operation documentation.
+
+.. option:: -gen-pass-decls
+
+  Generate operation documentation.
+
+.. option:: -name namestring
+
+  The name of this group of passes.
+
+.. option:: -gen-pass-doc
+
+  Generate pass documentation.
+
+.. option:: -gen-rewriters
+
+  Generate pattern rewriters.
+
+.. option:: -gen-spirv-avail-impls
+
+  Generate SPIR-V operation utility definitions.
+
+.. option:: -gen-spirv-capability-implication
+
+  Generate utility function to return implied capabilities for a given capability.
+
+.. option:: -gen-spirv-enum-avail-decls
+
+  Generate SPIR-V enum availability declarations.
+
+.. option:: -gen-spirv-enum-avail-defs
+
+  Generate SPIR-V enum availability definitions.
+
+.. option:: -gen-spirv-op-utils
+
+  Generate SPIR-V operation utility definitions.
+
+.. option:: -gen-spirv-serialization
+
+  Generate SPIR-V (de)serialization utilities and functions.
+
+.. option:: -gen-struct-attr-decls
+
+  Generate struct utility declarations.
+
+.. option:: -gen-struct-attr-defs
+
+  Generate struct utility definitions.
+
+.. option:: -gen-typedef-decls
+
+  Generate TypeDef declarations.
+
+.. option:: -gen-typedef-defs
+
+  Generate TypeDef definitions.
+
+.. option:: -typedefs-dialect name
+
+  Generate types for this dialect.
 
 EXIT STATUS
 -----------
 
-If :program:`tblgen` succeeds, it will exit with 0.  Otherwise, if an error
+If :program:`xxx-tblgen` succeeds, it will exit with 0.  Otherwise, if an error
 occurs, it will exit with a non-zero value.

llvm/docs/TableGen/Deficiencies.rst

-=====================
-TableGen Deficiencies
-=====================
-
-.. contents::
-   :local:
-
-Introduction
-============
-
-Despite being very generic, TableGen has some deficiencies that have been
-pointed out numerous times. The common theme is that, while TableGen allows
-you to build Domain-Specific-Languages, the final languages that you create
-lack the power of other DSLs, which in turn increase considerably the size
-and complexity of TableGen files.
-
-At the same time, TableGen allows you to create virtually any meaning of
-the basic concepts via custom-made back-ends, which can pervert the original
-design and make it very hard for newcomers to understand it.
-
-There are some in favour of extending the semantics even more, but making sure
-back-ends adhere to strict rules. Others suggesting we should move to more
-powerful DSLs designed with specific purposes, or even re-using existing
-DSLs.
-
-Known Problems
-==============
-
-TODO: Add here frequently asked questions about why TableGen doesn't do
-what you want, how it might, and how we could extend/restrict it to
-be more use friendly.

llvm/docs/TableGen/ProgRef.rst

 information is coded in a declarative style involving classes and records,
 which are then processed by TableGen. The internalized records are passed on
 to various backends, which extract information from a subset of the records
 and generate one or more output files. These output files are typically
 ``.inc`` files for C++, but may be any type of file that the backend
 developer needs.
 
 This document describes the LLVM TableGen facility in detail. It is intended
-for the programmer who is using TableGen to produce tables for a project. If
-you are looking for a simple overview, check out :doc:`TableGen Overview <./index>`.
+for the programmer who is using TableGen to produce code for a project. If
+you are looking for a simple overview, check out the :doc:`TableGen Overview
+<./index>`.  The various ``xxx-tblgen`` commands used to invoke TableGen are
+described in :doc:`xxx-tblgen: Target Description to C++ Code
+<../CommandGuide/tblgen>`.
 
 An example of a backend is ``RegisterInfo``, which generates the register
 file information for a particular target machine, for use by the LLVM
 target-independent code generator. See :doc:`TableGen Backends <./BackEnds>`
 for a description of the LLVM TableGen backends, and :doc:`TableGen
 Backend Developer's Guide <./BackGuide>` for a guide to writing a new
 backend.
 

 *str1*\ ``#``\ *str2*
     The paste operator (``#``) is a shorthand for
     ``!strconcat`` with two arguments.  It can be used to concatenate operands that
     are not strings, in which
     case an implicit ``!cast<string>`` is done on those operands.
 
 ``!subst(``\ *target*\ ``,`` *repl*\ ``,`` *value*\ ``)``
     This operator replaces all occurrences of the *target* in the *value* with
-    the *repl* and produces the resulting value. For strings, this is straightforward.
+    the *repl* and produces the resulting value. The *value* can
+    be a string, in which case substring substitution is performed.
 
-    If the arguments are record names, the function produces the *repl*
+    The *value* can be a record name, in which case the operator produces the *repl*
     record if the *target* record name equals the *value* record name; otherwise it
     produces the *value*.
 
 ``!tail(``\ *a*\ ``)``
     This operator produces a new list with all the elements
     of the list *a* except for the zeroth one. (See also ``!head``.)
 
 ``!xor(``\ *a*\ ``,`` *b*\ ``, ...)``

llvm/docs/TableGen/index.rst

 
 TableGen's purpose is to help a human develop and maintain records of
 domain-specific information.  Because there may be a large number of these
 records, it is specifically designed to allow writing flexible descriptions and
 for common features of these records to be factored out.  This reduces the
 amount of duplication in the description, reduces the chance of error, and makes
 it easier to structure domain specific information.
 
-The core part of TableGen parses a file, instantiates the declarations, and
-hands the result off to a domain-specific `backend`_ for processing.
-See the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth
-description of TableGen.
+The TableGen front end parses a file, instantiates the declarations, and
+hands the result off to a domain-specific `backend`_ for processing.  See
+the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth
+description of TableGen. See :doc:`xxx-tblgen: Target Description to C++
+Code <../CommandGuide/tblgen>` for details on the various
+``xxx-tblgen`` commands that invoke TableGen.
 
 The current major users of TableGen are :doc:`The LLVM Target-Independent
 Code Generator <../CodeGenerator>` and the `Clang diagnostics and attributes
 <https://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings>`_.
 
 Note that if you work on TableGen much, and use emacs or vim, that you can find
 an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
 ``llvm/utils/vim`` directories of your LLVM distribution, respectively.

 backends, and see the :doc:`TableGen Backend Developer's Guide <./BackGuide>`
 for information on how to write and debug a new backend.
 
 TableGen Deficiencies
 =====================
 
 Despite being very generic, TableGen has some deficiencies that have been
 pointed out numerous times. The common theme is that, while TableGen allows
-you to build Domain-Specific-Languages, the final languages that you create
+you to build domain specific languages, the final languages that you create
 lack the power of other DSLs, which in turn increase considerably the size
 and complexity of TableGen files.
 
 At the same time, TableGen allows you to create virtually any meaning of
 the basic concepts via custom-made backends, which can pervert the original
 design and make it very hard for newcomers to understand the evil TableGen
 file.
 
-There are some in favour of extending the semantics even more, but making sure
+There are some in favor of extending the semantics even more, but making sure
 backends adhere to strict rules. Others are suggesting we should move to less,
-more powerful DSLs designed with specific purposes, or even re-using existing
+more powerful DSLs designed with specific purposes, or even reusing existing
 DSLs.
-
-Either way, this is a discussion that will likely span across several years,
-if not decades. You can read more in :doc:`TableGen Deficiencies <./Deficiencies>`.