docs(man): add a page for Terraform parser

Signed-off-by: Masatake YAMATO <[email protected]>
universal-ctags · Apr 1, 2023 · 9a23f87 · 9a23f87
1 parent 9a37a64
commit 9a23f87
Show file tree

Hide file tree

Showing 4 changed files with 96 additions and 0 deletions.
diff --git a/docs/man-pages.rst b/docs/man-pages.rst
@@ -31,6 +31,7 @@ Man pages
 	ctags-lang-sql(7) <man/ctags-lang-sql.7.rst>
 	ctags-lang-systemtap(7) <man/ctags-lang-systemtap.7.rst>
 	ctags-lang-tcl(7) <man/ctags-lang-tcl.7.rst>
+	ctags-lang-terraform(7) <man/ctags-lang-terraform.7.rst>
 	ctags-lang-verilog(7) <man/ctags-lang-verilog.7.rst>
 
 	readtags(1) <man/readtags.1.rst>
diff --git a/docs/man/ctags-lang-terraform.7.rst b/docs/man/ctags-lang-terraform.7.rst
@@ -0,0 +1,47 @@
+.. _ctags-lang-terraform(7):
+
+==============================================================
+ctags-lang-terraform
+==============================================================
+
+Random notes about tagging Terraform files with Universal Ctags
+
+:Version: 6.0.0
+:Manual group: Universal Ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|	**ctags** ... --languages=+Terraform ...
+|	**ctags** ... --language-force=Terraform ...
+|	**ctags** ... --map-Terraform=+.tf ...
+|
+|	**ctags** ... --extras=+{reference} --languages=+TerraformVariables ...
+|	**ctags** ... --extras=+{reference} --language-force=TerraformVariables ...
+|	**ctags** ... --extras=+{reference} --map-Terraform=+.tfvars ...
+
+DESCRIPTION
+-----------
+This man page gathers random notes about tagging Terraform files.
+
+TIPS
+-----------
+
+Extracting variables assigned in Variable definitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Specify ``--extras=+{reference}`` and ``--languages=+TerraformVariables``
+to extract variables assigned in variables definitions (`*.tfvars`).
+The TerraformVariables parser extracts variables in `*.tfvars` files
+with ``variable`` kind with ``assigned`` role of ``Terraform`` language.
+
+KNOWN BUGS
+----------
+* The parser doesn't ignore strings inside a block comment (``/* ... */``).
+
+* The parser doesn't extract variables defined with ``locals`` keyword.
+
+SEE ALSO
+--------
+:ref:`ctags(1) <ctags(1)>`,
+`Configuration Syntax <https://developer.hashicorp.com/terraform/language/syntax/configuration>`_ (https://developer.hashicorp.com/terraform/language/syntax/configuration),
+`Variable Definitions (.tfvars) Files <https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files>`_ (https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files)
diff --git a/man/GNUmakefile.am b/man/GNUmakefile.am
@@ -42,6 +42,7 @@ GEN_IN_MAN_FILES = \
 	ctags-lang-sql.7 \
 	ctags-lang-systemtap.7 \
 	ctags-lang-tcl.7 \
+	ctags-lang-terraform.7 \
 	ctags-lang-verilog.7 \
 	\
 	readtags.1 \

diff --git a/man/ctags-lang-terraform.7.rst.in b/man/ctags-lang-terraform.7.rst.in
@@ -0,0 +1,47 @@
+.. _ctags-lang-terraform(7):
+
+==============================================================
+ctags-lang-terraform
+==============================================================
+---------------------------------------------------------------------
+Random notes about tagging Terraform files with Universal Ctags
+---------------------------------------------------------------------
+:Version: @VERSION@
+:Manual group: Universal Ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|	**@CTAGS_NAME_EXECUTABLE@** ... --languages=+Terraform ...
+|	**@CTAGS_NAME_EXECUTABLE@** ... --language-force=Terraform ...
+|	**@CTAGS_NAME_EXECUTABLE@** ... --map-Terraform=+.tf ...
+|
+|	**@CTAGS_NAME_EXECUTABLE@** ... --extras=+{reference} --languages=+TerraformVariables ...
+|	**@CTAGS_NAME_EXECUTABLE@** ... --extras=+{reference} --language-force=TerraformVariables ...
+|	**@CTAGS_NAME_EXECUTABLE@** ... --extras=+{reference} --map-Terraform=+.tfvars ...
+
+DESCRIPTION
+-----------
+This man page gathers random notes about tagging Terraform files.
+
+TIPS
+-----------
+
+Extracting variables assigned in Variable definitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Specify ``--extras=+{reference}`` and ``--languages=+TerraformVariables``
+to extract variables assigned in variables definitions (`*.tfvars`).
+The TerraformVariables parser extracts variables in `*.tfvars` files
+with ``variable`` kind with ``assigned`` role of ``Terraform`` language.
+
+KNOWN BUGS
+----------
+* The parser doesn't ignore strings inside a block comment (``/* ... */``).
+
+* The parser doesn't extract variables defined with ``locals`` keyword.
+
+SEE ALSO
+--------
+ctags(1),
+`Configuration Syntax <https://developer.hashicorp.com/terraform/language/syntax/configuration>`_ (https://developer.hashicorp.com/terraform/language/syntax/configuration),
+`Variable Definitions (.tfvars) Files <https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files>`_ (https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files)