Start discussing language directory structure

docs/Voice Coding/language-specific.md

@@ -4,9 +4,11 @@ sidebar_position: 5
 
 # Miscellaneous Language Specific Commands
 
-The community [lang directory](https://github.com/talonhub/community/tree/main/lang) contains folders implementing support for specific programming languages. In the .talon file named after the programming language, you will see several tags activated. These tags activate programming commands whose behavior depends on the active programming language. Descriptions of the commands activated by these tags are available below.
+The community [lang directory](https://github.com/talonhub/community/tree/main/lang) contains folders implementing support for specific programming languages and programming language features.
 
-This page leaves out functionality that is now better done with [snippets](snippets.md) than the tag based grammar. For many languages, you will find additional language specific functionality in the language .talon and .py files.
+`<language>/<language>.talon` files activate one or more tags. These tags enable commands shared across languages with similar features, meaning you have fewer commands to memorize if you code in multiple languages. The behavior of these commands depends on the active programming language. Descriptions of the commands activated by these tags are below.
+
+This page leaves out functionality that is now better done with [snippets](snippets.md) than tag-based commands. For many languages, you will find additional language specific functionality in the `<language>/<language>.talon` and `<language>/<language>.py` files.
 
 ## user.code_data_bool
 
@@ -31,3 +33,31 @@ This activates commands related to types and functions. `type <user.code_type>`
 ## user.code_keywords
 
 This activates support for dictating language keywords. `put <user.code_keyword>+` inserts the specified keywords. Keywords in the `user.code_keyword_unprefixed` list can be dictated without the put prefix. You can see the contents of the prefixed and unprefixed keyword lists for the active language with the commands `help keywords` and `help keywords unprefixed` respectively.
+
+# Navigating the Language Directory Structure
+
+While not strictly necessary for voice coding with community, understanding the directory structure is useful to discover functionality and when expanding language support. Each subdirectory of the `lang` directory corresponds to a programming language, except for `tags`, which includes voice commands intended to be used across multiple languages. To understand the Talon concepts discussed in this section, please read the [Talon framework](/Customization/Talon%20Framework/talon-framework-overview) documentation.
+
+## The `tags` Subdirectory
+
+The .talon files in this directory define commands that become available when the tag at the top of the file is activated. Languages can activate these tags in their .talon file to make these commands available. The .py files in this directory define the action signatures that need to be implemented in Python on a per-language basis to make these commands actually useful. The .py files additionally define things like lists that can also be implemented on a per-language basis.
+
+This structure allows defining generic commands, actions, and lists that can be relied on as long as the active programming language provides implementations. For instance, a user could use the following talon file to allow dictating a type name followed by a space:
+
+```talon
+tag: user.code_functions
+-
+strut <user.code_type>: '{code_type} '
+```
+
+If you look at the tags activated by a language's .talon file, you can find the corresponding commands activated by looking for that tag in the `tags` directory. You can find the corresponding action signatures there and see how they are implemented in the language's .py file.
+
+## understanding language specific .py files
+
+Languages differ in how much support they have implemented. The following describes things you may find there.
+
+There is usually an Operators object defining the operators that can be inserted.
+
+There might be language specific actions, lists, and captures defined on a Module object.
+
+Language specific implementations of generic functionality will be defined on a Context object.