From: Rich Bowen Date: Tue, 14 Apr 2026 15:15:22 +0000 (+0000) Subject: Adds an AGENTS.md file to guide agentic contributions to the X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=15cc845c259bfedbcd5d1f8ae34910c87eb17839;p=thirdparty%2Fapache%2Fhttpd.git Adds an AGENTS.md file to guide agentic contributions to the documentation. Based on the (proposed) style guide that will land in httpd.apache.org/docs-project git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1933046 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/AGENTS.md b/docs/manual/AGENTS.md new file mode 100644 index 0000000000..735d3734c8 --- /dev/null +++ b/docs/manual/AGENTS.md @@ -0,0 +1,133 @@ +# AGENTS.md — Apache HTTP Server Documentation + +This file provides instructions for AI agents working on the Apache HTTP Server documentation. + +## Project Overview + +This is the documentation source for the [Apache HTTP Server](https://httpd.apache.org/). Documentation is written in a custom XML format and transformed via XSLT. The source lives under `docs/manual/`. + +## Inline Markup Rules + +- `` — Use for any user-supplied placeholder value. Never use `` for placeholders. + ```xml + Listen port +

Replace hostname with your server's FQDN.

+ ``` +- `` — Use only for rhetorical emphasis (e.g., *not*, *must*, *only*, *all*, *before*, *after*). Never for placeholders, keywords, or warnings. +- `` — Use for literal strings: filenames, paths, HTTP methods, header names, config keywords (`On`, `Off`, `None`), MIME types, env vars, CLI flags, signal names. Never nest `` inside ``. +- `` — Use sparingly for critical warnings. Never inside ``. Prefer `` when appropriate. +- `` — Use for httpd executables that have manual pages (`httpd`, `apachectl`, `htpasswd`, `rotatelogs`, `configure`). Never use `` for these. +- `` — Use for Apache module names (`mod_rewrite`, `mod_ssl`, `core`). Never use `` for these. +- `` — Use for directive names. Include `module` attribute when referencing outside the directive's own module doc. Use `type="section"` for section directives. + ```xml + ServerRoot + VirtualHost + ``` +- `` — Use for glossary-defined terms. Use `ref` attribute when link target differs from display text. + +## Directive Syntax Definitions + +- Use `` for all user-supplied arguments in `` blocks. +- Literal keyword choices appear untagged, separated by `|`. +- Use these standard argument-type names in `` tags: + `file-path`, `directory-path`, `URL-path`, `url`, `filename`, `extension`, `regex`, `expression`, `number`, `bytes`, `seconds`, `duration`, `hostname`, `name`, `value`, `provider-name`, `env-variable`, `MIME-type`, `method` + +### Quoting in Config Examples + +Quote these in `` blocks: +- Filesystem paths: `ServerRoot "/usr/local/apache2"` +- URLs: `Redirect "/" "https://example.com/"` +- AuthName values: `AuthName "Restricted Area"` +- Regex patterns: `RewriteRule "^/old(.*)" "/new$1"` + +Do NOT quote bare keywords: `AllowOverride None`, `Options FollowSymLinks`, `Require all granted` + +## Block-Level Elements + +### Code Examples + +Use `` with nested ``: + +```xml + + +Listen 80 +Listen 8000 + + +``` + +Valid `language` values: `config`, `lua`, `c`, `perl`, `sh`, `html`. + +Never use bare `` with `
` line breaks — that is a legacy pattern. Convert to `` when editing such files. + +### Notes and Warnings + +```xml + +

Informational callout text.

+ + + +

Critical warning text.

+ +``` + +Never use `Note:` in prose as a substitute for ``. + +### See Also + +Place `` elements after `` and before the first `
`. + +## Prose Style + +- Address the reader in second person ("you"). Avoid impersonal third-person ("the administrator should..."). +- Contractions are acceptable ("doesn't", "won't", "can't"). +- Use American English spelling (`behavior`, `customize`, `recognize`, `authorize`, `color`). +- Product name: first reference → "Apache HTTP Server" or "Apache httpd"; subsequent → "httpd". Never use bare "Apache" for the server. +- Use the Oxford comma ("addresses, hostnames, and ports"). +- Prefer active voice ("Use this directive to..." not "The directive is used to..."). +- Keep sentences concise. Break complex instructions into steps or bullet lists. + +## Formatting and Structure + +- Use spaces, not tabs. Don't mix indentation widths within a file. +- Content inside `` blocks should be left-aligned (whitespace is preserved in output). +- Every manual page follows this structure: + ```xml + + + + + + Page Title + ... + ... +
+ Section Title + ... +
+ + ``` +- Section `id` values: short, lowercase, hyphenated. These are URL anchors and must remain stable once published. +- Use UTF-8 encoding. Write non-ASCII as literal UTF-8 (e.g., `é à ü`), not XML entities, unless the file already uses entities consistently. + +## Reader's Guide (How Markup Renders) + +Understanding how markup renders helps agents write documentation that reads well for end users: + +- `` (italic) — Emphasis. The reader should pay special attention to the marked word. +- `` (slanted/colored) — Placeholder. The reader replaces it with their own value. +- `` (monospace) — Literal value. Type it exactly as shown. +- `` (bold) — Critical point. The reader must not skip it. +- `` and `` — Rendered as clickable cross-reference links to the relevant docs. +- `` — Rendered as a clickable link to the program's manual page. +- ``/`` — Rendered as shaded code blocks the reader can copy and adapt. +- `` — Rendered as a callout box. `` renders as a warning box indicating pitfalls or destructive actions. +- In directive syntax lines: + - Placeholders are values the reader supplies (e.g., `file-path`, `URL-path`, `regex`). + - Literal keywords appear as-is (`On`, `Off`, `All`, `None`). + - `[ ]` indicates optional arguments. + - `|` separates alternative choices. + - `...` indicates the argument may be repeated. + - Quoted arguments in examples mean quotes are required or recommended in the config file. \ No newline at end of file