<commit_before>= YAMLDoc

YAMLDoc helps software developers design clean, understandable configuration
files and generate tools for nontechnical users to edit them.

== 1. Philosophy
Users should never be *forced* to edit a text file to configure software, but 
should always be able to exercise that option in a clear and usable way.

Configuration File Design is a highly overlooked aspect of software 
engineering.

== 2. Purpose

YAMLDoc is a documentation specification that helps you document YAML* software
configuration files in a way that is nice to read in plain text, yet structured
enough to be automatically extracted and processed by a machine.

Documenting your configuration files in this way grants you the ability to
generate interactive editors and GUI forms to help nontechnical users get your
software up and running quickly, and helps eliminate guesswork which leads to
invalid directive values creating unexpected program state.

YAMLDoc borrows heavily from TomDoc*.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 
interpreted as described in RFC 2119*.

== 3. Components
* Specification
* Validation Tool
  * Validation will fail if any nodes are missing documentation, discouraging
    the Bloated Configuration File antipattern described by Chris Edwards*,
    wherein a file intended for user-editable configuration settings grows to
    include static application configuration that should never change.
  * This tool can be used to write unit tests for your configuration files
    capable of catching unexpected errors introduced through misconfiguration.
  * Capable of detecting version differences between the example and deployed
    YAML files, which MAY be used to raise a warning when the application
    is initialized, or cause a unit test to fail.<commit_msg>formatting<commit_after>= YAMLDoc

YAMLDoc helps software developers design clean, understandable configuration
files and generate tools for nontechnical users to edit them.

== 1. Philosophy
Users should never be *forced* to edit a text file to configure software, but 
should always be able to exercise that option in a clear and usable way.

Proper configuration file design is a highly overlooked aspect of software 
engineering.

== 2. Purpose

YAMLDoc is a documentation specification that helps you document YAML* software
configuration files in a way that is nice to read in plain text, yet structured
enough to be automatically extracted and processed by a machine.

Documenting your configuration files in this way grants you the ability to
generate interactive editors and GUI forms to help nontechnical users get your
software up and running quickly, and helps eliminate guesswork which leads to
invalid directive values creating unexpected program state.

YAMLDoc borrows heavily from TomDoc*.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 
interpreted as described in RFC 2119*.

=== 3. Components
* Specification
* Validation Tool
  * Validation will fail if any nodes are missing documentation, discouraging
    the Bloated Configuration File antipattern described by <NAME>*,
    wherein a file intended for user-editable configuration settings grows to
    include static application configuration that should never change.
  * This tool can be used to write unit tests for your configuration files
    capable of catching unexpected errors introduced through misconfiguration.
  * Capable of detecting version differences between the example and deployed
    YAML files, which MAY be used to raise a warning when the application
    is initialized, or cause a unit test to fail.
{'fraction_non_alphanumeric': 0.03848167539267016, 'fraction_numerical': 0.0036649214659685864, 'mean_word_length': 4.694485842026825, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3768249', 'n_tokens_mistral': 924, 'n_tokens_neox': 869, 'n_words': 541}