Update documentation structure

README.md

@@ -52,11 +52,15 @@ identifier may be a slug, alias, extension, or filename.
 
 ## Documentation
 
-The [ALTO Language documentation](https://altophp.com/language/) covers:
-
-- [lookup rules](https://altophp.com/language/lookup/);
-- the [bundled catalog](https://altophp.com/language/catalog/);
-- [language definitions and custom registration](https://altophp.com/language/definitions/).
+- [Installation](docs/installation.md)
+- [Getting started](docs/getting-started.md)
+- [Lookup](docs/lookup.md)
+- [Catalog](docs/catalog.md)
+- [Definitions](docs/definitions.md)
+
+The [documentation index](docs/index.md) lists these pages in site navigation
+order. The same documentation is published on
+[altophp.com](https://altophp.com/language).
 
 ## Contributing
 

docs/catalog.md

@@ -16,70 +16,70 @@ $javascriptFamily = Languages::children('javascript');
 `all()` preserves definition loading order. `ofType()` and `children()` return
 filtered lists of `Language` objects.
 
-| Language | Extensions | Type |
-| --- | --- | --- |
-| Bash | `.sh`, `.bash` | Programming |
-| C | `.c`, `.h` | Programming |
-| C# | `.cs` | Programming |
-| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | Programming |
-| Clojure | `.clj`, `.cljs`, `.cljc` | Programming |
-| CMake | `.cmake` | Programming |
-| CoffeeScript | `.coffee` | Programming |
-| CSS | `.css` | Stylesheet |
-| Dart | `.dart` | Programming |
-| Diff | `.diff`, `.patch` | Data |
-| Dockerfile | Exact filenames | Config |
-| Dotenv | Exact filenames | Config |
-| Elixir | `.ex`, `.exs` | Programming |
-| Erlang | `.erl`, `.hrl` | Programming |
-| F# | `.fs`, `.fsi`, `.fsx` | Programming |
-| Git Attributes | Exact filenames | Config |
-| Git Config | Exact filenames | Config |
-| Go | `.go` | Programming |
-| GraphQL | `.graphql`, `.gql` | Query |
-| Groovy | `.groovy`, `.gvy` | Programming |
-| Haskell | `.hs`, `.lhs` | Programming |
-| HCL | `.hcl`, `.tf` | Programming |
-| htaccess | Exact filenames | Config |
-| HTML | `.html`, `.htm` | Markup |
-| HTTP | `.http`, `.rest` | Data |
-| Ignore | Exact filenames | Config |
-| INI | `.ini`, `.cfg` | Config |
-| Java | `.java` | Programming |
-| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | Programming |
-| JSON | `.json` | Data |
-| Julia | `.jl` | Programming |
-| Just | Exact filenames | Config |
-| Kotlin | `.kt`, `.kts` | Programming |
-| Less | `.less` | Stylesheet |
-| Lua | `.lua` | Programming |
-| Makefile | Exact filenames | Programming |
-| Markdown | `.md`, `.markdown` | Prose |
-| NEON | `.neon` | Config |
-| Nix | `.nix` | Programming |
-| Objective-C | `.m`, `.mm` | Programming |
-| OCaml | `.ml`, `.mli` | Programming |
-| Perl | `.pl`, `.pm` | Programming |
-| PHP | `.php`, `.phtml`, `.php3`, `.php4`, `.php5`, `.phps` | Programming |
-| PowerShell | `.ps1`, `.psm1` | Programming |
-| Procfile | Exact filenames | Config |
-| Protocol Buffers | `.proto` | Data |
-| Python | `.py`, `.pyw` | Programming |
-| R | `.r`, `.R` | Programming |
-| Ruby | `.rb` | Programming |
-| Rust | `.rs` | Programming |
-| Sass | `.sass` | Stylesheet |
-| Scala | `.scala`, `.sc` | Programming |
-| SCSS | `.scss` | Stylesheet |
-| SQL | `.sql` | Query |
-| SVG | `.svg` | Markup |
-| Swift | `.swift` | Programming |
-| TOML | `.toml` | Config |
-| Twig | `.twig` | Template |
-| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | Programming |
-| XML | `.xml`, `.xsl`, `.xsd` | Markup |
-| YAML | `.yml`, `.yaml` | Data |
-| Zig | `.zig` | Programming |
+| Language | Extensions | Exact filenames | Type |
+| --- | --- | --- | --- |
+| Bash | `.sh`, `.bash`, `.zsh` | `.bashrc`, `.bash_profile`, `.bash_logout`, `.profile` | Programming |
+| C | `.c`, `.h` | - | Programming |
+| Clojure | `.clj`, `.cljs`, `.cljc`, `.edn` | - | Programming |
+| CMake | `.cmake` | `CMakeLists.txt` | Config |
+| CoffeeScript | `.coffee`, `.litcoffee` | - | Programming |
+| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh`, `.hxx` | - | Programming |
+| C# | `.cs`, `.csx` | - | Programming |
+| CSS | `.css` | - | Stylesheet |
+| Dart | `.dart` | - | Programming |
+| Diff | `.diff`, `.patch` | - | Other |
+| Dockerfile | `.dockerfile` | `Dockerfile`, `Dockerfile.dev`, `Dockerfile.prod` | Config |
+| DotEnv | `.env` | `.env`, `.env.local`, `.env.production`, `.env.development` | Config |
+| Elixir | `.ex`, `.exs` | - | Programming |
+| Erlang | `.erl`, `.hrl` | - | Programming |
+| F# | `.fs`, `.fsx`, `.fsi` | - | Programming |
+| Git Attributes | - | `.gitattributes` | Config |
+| Git Config | `.gitconfig` | `.gitconfig`, `.gitmodules`, `.mailmap` | Config |
+| Go | `.go` | - | Programming |
+| GraphQL | `.graphql`, `.gql` | - | Query |
+| Groovy | `.groovy`, `.gvy`, `.gy`, `.gsh` | - | Programming |
+| Haskell | `.hs`, `.lhs` | - | Programming |
+| HCL | `.hcl`, `.tf`, `.tfvars` | - | Config |
+| Apache Config | - | `.htaccess`, `.htpasswd` | Config |
+| HTML | `.html`, `.htm`, `.xhtml` | - | Markup |
+| HTTP | `.http` | - | Other |
+| Ignore List | - | `.gitignore`, `.dockerignore`, `.npmignore`, `.eslintignore`, `.prettierignore`, `.stylelintignore`, `.hgignore`, `.nowignore`, `.vercelignore`, `.gcloudignore` | Config |
+| INI | `.ini`, `.cfg`, `.properties` | `.editorconfig`, `.npmrc` | Config |
+| Java | `.java` | - | Programming |
+| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | - | Programming |
+| JSON | `.json`, `.jsonc`, `.geojson`, `.json5` | `.prettierrc`, `.eslintrc`, `.babelrc`, `.swcrc`, `composer.lock` | Data |
+| Julia | `.jl` | - | Programming |
+| Just | - | `Justfile`, `justfile` | Config |
+| Kotlin | `.kt`, `.kts` | - | Programming |
+| Less | `.less` | - | Stylesheet |
+| Lua | `.lua` | - | Programming |
+| Makefile | `.mk` | `Makefile`, `GNUmakefile`, `makefile` | Config |
+| Markdown | `.md`, `.markdown`, `.mdx` | - | Prose |
+| NEON | `.neon` | - | Config |
+| Nix | `.nix` | - | Config |
+| Objective-C | `.m`, `.mm` | - | Programming |
+| OCaml | `.ml`, `.mli` | - | Programming |
+| Perl | `.pl`, `.pm`, `.t` | - | Programming |
+| PHP | `.php`, `.phtml`, `.php3`, `.php4`, `.php5`, `.phps` | - | Programming |
+| PowerShell | `.ps1`, `.psm1`, `.psd1` | - | Programming |
+| Procfile | - | `Procfile` | Config |
+| Protocol Buffers | `.proto` | - | Data |
+| Python | `.py`, `.pyi`, `.pyw` | - | Programming |
+| R | `.r`, `.R`, `.rmd` | - | Programming |
+| Ruby | `.rb`, `.rake`, `.gemspec` | `Gemfile`, `Rakefile`, `Guardfile`, `Vagrantfile`, `Podfile`, `Capfile`, `Brewfile`, `Berksfile` | Programming |
+| Rust | `.rs` | - | Programming |
+| Sass | `.sass` | - | Stylesheet |
+| Scala | `.scala`, `.sc` | - | Programming |
+| SCSS | `.scss` | - | Stylesheet |
+| SQL | `.sql` | - | Query |
+| SVG | `.svg` | - | Markup |
+| Swift | `.swift` | - | Programming |
+| TOML | `.toml` | - | Data |
+| Twig | `.twig`, `.html.twig` | - | Template |
+| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | - | Programming |
+| XML | `.xml`, `.xsd`, `.xsl`, `.xslt`, `.wsdl` | - | Markup |
+| YAML | `.yml`, `.yaml` | - | Data |
+| Zig | `.zig` | - | Programming |
 
 Types are represented by `LanguageType`: `Programming`, `Markup`, `Data`,
 `Prose`, `Query`, `Stylesheet`, `Template`, `Config`, and `Other`.

docs/definitions.md

@@ -39,6 +39,10 @@ describe common conventions; they are not a parser grammar.
 ## Register an application language
 
 ```php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
 use Alto\Language\CodeMarkers;
 use Alto\Language\Language;
 use Alto\Language\LanguageRegistry;
@@ -55,6 +59,15 @@ $registry->register(new Language(
 ));
 
 $language = $registry->fromExtension('.myl');
+printf("%s (%s)\n", $language?->name, $language?->slug);
+echo json_encode($language?->markers->lineComments, JSON_THROW_ON_ERROR), "\n";
+```
+
+Output:
+
+```text
+My Language (my-language)
+["\/\/"]
 ```
 
 Bundled definitions are loaded lazily. A custom registration with the same
@@ -63,3 +76,7 @@ extension, alias, or filename.
 
 Inspect collisions with `$registry->conflicts()`. The result groups repeated
 keys under `extension`, `alias`, and `filename`.
+
+Keep application registries separate when one service should not see another
+service's custom definitions. Check `conflicts()` before choosing an ambiguous
+alias or extension. Registration changes lookup metadata, not a syntax parser.

docs/getting-started.md

@@ -3,23 +3,38 @@
 Use `Languages::fromFilename()` when an application has a path and wants the
 best matching bundled definition.
 
+After [installation](installation.md), save this as `language.php` beside `vendor`
+and run `php language.php`. An unknown identifier is a normal `null` result.
+
 ```php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
 use Alto\Language\Languages;
 
 $language = Languages::fromFilename('templates/home.html.twig');
-
 if (null === $language) {
-    throw new RuntimeException('Unknown language.');
+    echo "Unknown language\n";
+    return;
 }
+printf("name=%s type=%s\n", $language->name, $language->type->value);
+echo Languages::resolve('not-a-language')?->name ?? 'Unknown language', "\n";
+```
+
+Output:
 
-echo $language->name;
-echo $language->type->value;
+```text
+name=Twig type=template
+Unknown language
 ```
 
 Exact filenames such as `Dockerfile` and `.gitignore` are checked first.
 Otherwise, the registry tests extensions from right to left. A compound name
 therefore falls back until a registered suffix matches.
 
+Keep `$language` from the first example when inspecting its metadata below.
+
 ## Inspect the result
 
 ```php

docs/index.md

@@ -1,27 +1,23 @@
 # Alto Language
 
-Alto Language provides structured metadata for 62 programming and document
-languages: extensions, aliases, exact filenames, relationships, and syntax
-markers.
+Alto Language resolves immutable metadata for 62 programming and document
+languages from slugs, aliases, extensions, and exact filenames.
 
 ```php
 use Alto\Language\Languages;
 
 $language = Languages::fromFilename('src/Example.php');
-
-echo $language?->name; // PHP
+echo $language?->name;
 ```
 
-## Introduction
-
-- [Installation](installation.md): install the dependency-free package.
-- [Getting started](getting-started.md): resolve a file and inspect its language.
-
-## Languages
+The result is `PHP`. The package returns registered metadata, syntax markers,
+and language relationships. It does not inspect source contents or calculate a
+detection confidence score.
 
-- [Lookup](lookup.md): resolve slugs, aliases, extensions, and filenames.
-- [Catalog](catalog.md): browse and filter the bundled definitions.
-- [Definitions](definitions.md): inspect metadata and register application languages.
+## Documentation
 
-The package returns metadata. It does not inspect file contents or calculate a
-confidence score.
+- [Installation](installation.md)
+- [Getting started](getting-started.md)
+- [Lookup](lookup.md)
+- [Catalog](catalog.md)
+- [Definitions](definitions.md)

docs/lookup.md

@@ -42,3 +42,37 @@ $language = $registry->fromFilename('example.ts');
 
 `LanguageRegistry` exposes the same lookup, catalog, and relationship methods
 without global state. Prefer it in services that use dependency injection.
+
+## Check the lookup boundary
+
+This standalone example shows case and suffix behavior without reading any file:
+
+```php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
+use Alto\Language\Languages;
+
+foreach (['Dockerfile', 'dockerfile', 'home.html.twig', 'settings.unknown'] as $filename) {
+    printf("%s => %s\n", $filename, Languages::fromFilename($filename)?->slug ?? 'unknown');
+}
+printf("alias JS => %s\n", Languages::fromAlias('JS')?->slug);
+printf("extension .PHP => %s\n", Languages::fromExtension('.PHP')?->slug);
+```
+
+Output:
+
+```text
+Dockerfile => dockerfile
+dockerfile => unknown
+home.html.twig => twig
+settings.unknown => unknown
+alias JS => javascript
+extension .PHP => php
+```
+
+If a lookup returns `null`, choose an application fallback or register metadata
+for that language. Language does not examine content or calculate detection
+confidence; use content detection in a separate component if the filename is not
+enough.