update recommended file extensions

.gitattributes

@@ -0,0 +1 @@
+*.dclg linguist-language=XML

CONTRIBUTING.md

@@ -89,3 +89,20 @@ For maintainers preparing a release:
    (syncs version across artifacts, regenerates Appendix A, writes DOCX exports, and prepends a section to `CHANGELOG.md`; optional `--reference-input reference/input`)
    - Make any manual changes needed (e.g. ToC regeneration on DOCX file, export to PDF etc.)
 3. **Commit & tag** — once committed to `main`, create and push the tag.
+
+## Working with DocLang files
+
+To streamline working with the recommended file extensions, custom mappings can be provided to both the operating system and the IDE.
+
+For example, in IDEs based on VS Code, you can add the following to your `settings.json` (or accordingly extend the `"files.associations"` key if already present):
+
+```json
+{
+  "files.associations": {
+    "*.dclg": "xml"
+  }
+}
+```
+
+On the OS level, e.g. on Mac, you can choose which app opens a certain file type (e.g. `.dclg` files) as described
+[here](https://support.apple.com/guide/mac-help/choose-an-app-to-open-a-file-on-mac-mh35597/mac).

README.md

@@ -35,7 +35,7 @@ pip install doclang
 You can then validate a DocLang document as follows:
 
 ```bash
-doclang validate -n my_document.dclg.xml
+doclang validate -n my_document.dclg
 ```
 
 For more details, see the [doclang/README.md](https://github.com/doclang-project/doclang/blob/main/doclang/README.md).

doclang/README.md

@@ -13,26 +13,26 @@ pip install doclang
 ### Basic CLI Usage
 
 ```bash
-doclang validate my_document.dclg.xml
+doclang validate my_document.dclg
 ```
 
 ### More CLI Usage Scenarios
 
 ```bash
 ## Inject DocLang namespace if document doesn't declare it:
-doclang validate my_document.dclg.xml --allow-empty-namespace
+doclang validate my_document.dclg --allow-empty-namespace
 
 # XSD validation only
-doclang validate my_document.dclg.xml --xsd-only
+doclang validate my_document.dclg --xsd-only
 
 # Schematron validation only
-doclang validate my_document.dclg.xml --schematron-only
+doclang validate my_document.dclg --schematron-only
 
 # JSON output
-doclang validate my_document.dclg.xml --format json
+doclang validate my_document.dclg --format json
 
 # Quiet mode (exit code only)
-doclang validate my_document.dclg.xml --quiet
+doclang validate my_document.dclg --quiet
 
 # Show help
 doclang --help
@@ -44,7 +44,7 @@ doclang --help
 from doclang import validate, ValidationError
 
 try:
-    validate("my_document.dclg.xml")
+    validate("my_document.dclg")
     print("Validation OK (no exception)")
 except ValidationError as exc:
     print(exc)  # human-readable summary
@@ -83,7 +83,7 @@ In VS Code you can use [Red Hat's XML extension](https://open-vsx.org/vscode/ite
 ```xml
     "xml.fileAssociations": [
         {
-            "pattern": "**/*.dclg.xml",
+            "pattern": "**/*.dclg",
             "systemId": "file:///absolute/path/to/doclang.xsd",
         }
     ],

spec.md

@@ -246,6 +246,8 @@ The XSD schema itself may additionally capture a patch version and internally de
 
 ## Language Specification
 
+DocLang markup is encoded as XML. Recommended file extension: **`.dclg`**.
+
 The individual DocLang elements and attributes, as well as DocLang's contextual rules are specified in [Reference](#reference).
 
 The DocLang archive format is defined in [DocLang Archive Format](#doclang-archive-format).
@@ -3047,7 +3049,7 @@ None (empty element).
 
 ### DocLang Archive Format
 
-A **DocLang archive** is a [ZIP](https://pkware.cachefly.net/webdocs/APPNOTE/APPNOTE-6.3.10.TXT) file using the [Open Packaging Conventions (OPC)](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) container model. Recommended extension: **`.dclg`**.
+A **DocLang archive** is a [ZIP](https://pkware.cachefly.net/webdocs/APPNOTE/APPNOTE-6.3.10.TXT) file using the [Open Packaging Conventions (OPC)](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) container model. Recommended extension: **`.dclx`**.
 
 An archive is a **package** of **parts** (files in the ZIP). Each part has a path (e.g. `/document.xml`) and a content type declared in `[Content_Types].xml`. The package root relationship file `_rels/.rels` identifies the main DocLang document part.
 

tests/test_cli.py

@@ -32,13 +32,13 @@ def test_cli_version_matches_installed_metadata():
 
 def test_validate_valid_document():
     """Test validating a valid document."""
-    xml_file = Path("tests/data/valid/ok_comprehensive.dclg.xml")
+    xml_file = Path("tests/data/valid/ok_comprehensive.dclg")
     result = runner.invoke(app, ["validate", str(xml_file)])
     assert result.exit_code == 0
 
 
 def test_validate_invalid_document():
     """Test validating an invalid document."""
-    xml_file = Path("tests/data/invalid/nok_href_in_body.dclg.xml")
+    xml_file = Path("tests/data/invalid/nok_href_in_body.dclg")
     result = runner.invoke(app, ["validate", str(xml_file)])
     assert result.exit_code == 1

tests/test_validation.py

@@ -19,13 +19,12 @@
 
 
 # Collect test files
-valid_files = list(VALID_DIR.glob("*.dclg.xml")) if VALID_DIR.exists() else []
-invalid_files = list(INVALID_DIR.glob("*.dclg.xml")) if INVALID_DIR.exists() else []
+valid_files = list(VALID_DIR.glob("*.dclg")) if VALID_DIR.exists() else []
+invalid_files = list(INVALID_DIR.glob("*.dclg")) if INVALID_DIR.exists() else []
 
 
 def _allow_empty_namespace(xml_file: Path) -> bool:
-    base_name = xml_file.name.replace(".dclg.xml", "")
-    return base_name in ["ok_no_namespace", "doclang_example"]
+    return xml_file.stem in ["ok_no_namespace", "doclang_example"]
 
 
 @pytest.mark.parametrize("xml_file", valid_files, ids=lambda f: f.stem)
@@ -51,7 +50,7 @@ def test_invalid(xml_file):
 
 def test_invalid_reports_both_xsd_and_schematron_errors():
     """A document may fail both XSD and Schematron validation in a single run."""
-    xml_file = INVALID_DIR / "nok_xsd_and_schematron.dclg.xml"
+    xml_file = INVALID_DIR / "nok_xsd_and_schematron.dclg"
     with pytest.raises(ValidationError) as exc_info:
         validate(xml_file, allow_empty_namespace=False)
 

utils/generate_reference.py

@@ -13,7 +13,7 @@
 
     Arguments:
     - input_directory: Directory containing the Excel file with element definitions
-      (also may contain .dclg.xml and .png files for examples)
+      (also may contain .dclg and .png files for examples)
 """
 
 import os
@@ -242,7 +242,7 @@ def load_example_for_element(element_name, input_dir, spec_path):
 
     # Look for files in INPUT_DIR/examples/
     examples_dir = Path(input_dir) / "examples"
-    xml_file = examples_dir / f"{clean_name}.dclg.xml"
+    xml_file = examples_dir / f"{clean_name}.dclg"
 
     xml_content = None
     image_path = None

utils/pack-archive.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Pack a DocLang archive directory into a .dclg OPC ZIP file.
+# Pack a DocLang archive directory into a .dclx OPC ZIP file.
 # Usage: ./utils/pack-archive.sh <source-dir> [output-file]
 
 set -euo pipefail
@@ -11,7 +11,7 @@ fi
 
 SRC=$(cd "$1" && pwd)
 NAME=$(basename "$SRC")
-OUT=${2:-"${NAME}.dclg"}
+OUT=${2:-"${NAME}.dclx"}
 
 if [[ ! -f "$SRC/document.xml" ]]; then
   echo "Error: $SRC/document.xml not found" >&2