From 52cadf11a1598a63e106e892b7918ba34a2d22c5 Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Tue, 14 Apr 2026 09:20:44 -0400 Subject: [PATCH] Create a style guide for the documentation. Addresses bz57819 --- content/docs-project/contribute.md | 4 +- content/docs-project/docsformat.md | 3 + content/docs-project/index.md | 8 + content/docs-project/style-guide.md | 400 ++++++++++++++++++++++++++++ 4 files changed, 414 insertions(+), 1 deletion(-) create mode 100644 content/docs-project/style-guide.md diff --git a/content/docs-project/contribute.md b/content/docs-project/contribute.md index 1218350..f52ba21 100644 --- a/content/docs-project/contribute.md +++ b/content/docs-project/contribute.md @@ -38,7 +38,9 @@ into other languages, writing tutorials to help new users, or just expressing your opinion about suggested changes. For information on our use of XML in the documentation, see our -[Documentation Format and Transformation](docsformat.html) page. +[Documentation Format and Transformation](docsformat.html) page. For +markup conventions and prose style, see the [Documentation Style +Guide](style-guide.html). If you need inspiration for something to work on, look at our [STATUS](https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/STATUS) diff --git a/content/docs-project/docsformat.md b/content/docs-project/docsformat.md index 837bb34..35ecde5 100644 --- a/content/docs-project/docsformat.md +++ b/content/docs-project/docsformat.md @@ -14,6 +14,9 @@ example of the format with extensive comments is also available in [mod_template.txt](mod_template.txt). (Ordinarily, the file extension will be `xml`. It is changed here to make online viewing simpler.) +For detailed conventions on which markup elements to use and when, see the +[Documentation Style Guide](style-guide.html). + Various formatting syntax can be used such as: diff --git a/content/docs-project/index.md b/content/docs-project/index.md index e760321..02cd7d7 100644 --- a/content/docs-project/index.md +++ b/content/docs-project/index.md @@ -15,6 +15,8 @@ love to have your help too. - [I'd like to build the manual from local source](#build) +- [I want to follow the documentation style conventions](#style) + - [I'd like to join the docs team mailing list](#ml) - [I want to help translate the documentation](#translate) @@ -62,6 +64,12 @@ docs-build directory and run the relevant build scripts to produce all of the relevant transformations. Please see [docs build](docsformat.html) for more information. +# Style Guide {#style} + +When writing or editing documentation, please follow the conventions in our +[Documentation Style Guide](style-guide.html). It covers inline markup, +directive syntax definitions, prose style, and formatting standards. + # The docs mailing list {#ml} The discussion surrounding the documentation project happens on the diff --git a/content/docs-project/style-guide.md b/content/docs-project/style-guide.md new file mode 100644 index 0000000..e8b2f82 --- /dev/null +++ b/content/docs-project/style-guide.md @@ -0,0 +1,400 @@ +Title: Documentation Style Guide +license: https://www.apache.org/licenses/LICENSE-2.0 + +# Apache HTTP Server Documentation Style Guide # + +This guide defines conventions for writing and editing the Apache HTTP +Server documentation. + +There are two main audiences for this guide: + +1. Documentation writers — how to author and mark up content. +2. Documentation readers — how to interpret typographic conventions + (see the [Reader's Guide](#readers-guide) section at the end). + +# Inline Markup # + +## `` — User-Supplied Placeholders ## + +Use `` for any value the user must replace with their own input. +This includes placeholders in directive syntax definitions, prose +descriptions of arguments, and inline references to user-supplied +values. + + Listen port + AuthUserFile file-path +

Replace hostname with your server's FQDN.

+ +Do **not** use `` for placeholders. Legacy files use `` in this role; +new and updated content should use `` exclusively. + +## `` — Emphasis ## + +Use `` only for rhetorical emphasis — drawing attention to a word +or phrase in running prose. + +

The directive must appear before any VirtualHost blocks.

+

This applies to all requests, not just local ones.

+ +Common legitimate uses: *not*, *must*, *only*, *all*, *any*, *before*, *after*, +*e.g.*, *i.e.*, etc. + +Do **not** use `` for placeholder variables (use ``), for keywords +(use ``), or for strong warnings (use ``). + +## `` — Literal Values and Inline Code ## + +Use `` for any literal string that appears in configuration, +commands, output, or protocols: + +- Filenames and paths: `.htaccess`, `httpd.conf` +- HTTP methods: `GET`, `POST` +- Header names: `Content-Type`, `ETag` +- Configuration keywords: `On`, `Off`, `None` +- MIME types: `text/html` +- Environment variables: `PATH_INFO` +- CLI flags and arguments: `-k`, `graceful` +- Signal names: `TERM`, `USR1` + +Do **not** nest `` inside ``. If emphasis is needed on a code +element, restructure the sentence so the emphasis is in the prose. + +## `` — Strong Emphasis ## + +Use `` sparingly, for critical warnings or to highlight a word +that the reader must not miss: + +

You should not use this in production.

+ +Do **not** use `` inside `` blocks. Do **not** use `` where +`` would be more appropriate. + +## `` — Apache httpd Programs ## + +Use `` for any executable that ships with httpd and has its +own manual page: + + httpd + apachectl + htpasswd + rotatelogs + configure + +This generates a cross-reference link to the program's documentation. +Do **not** use `` for httpd program names. + +## `` — Module Names ## + +Use `` for Apache module names. This generates a cross-reference +link to the module's documentation: + + mod_rewrite + mod_ssl + core + +Do **not** use `` for module names. + +## `` — Directive Names ## + +Use `` for Apache directive names. Include the `module` +attribute when referencing a directive outside its own module's +documentation: + + ServerRoot + Listen + +Within a module's own documentation, the module attribute may be +omitted: + + Listen + +For section directives, add `type="section"`: + + VirtualHost + +## `` — Glossary Terms ## + +Use `` for terms defined in the project glossary. Use the +`ref` attribute when the link target differs from the display text: + + APR + regular expression + MIME-type + +# Directive Syntax Definitions # + +## Placeholder Arguments ## + +Use `` for all user-supplied arguments in `` blocks: + + ServerRoot directory-path + Timeout time-interval[s] + +## Keyword Arguments ## + +Literal keyword choices appear untagged, separated by `|`: + + AllowOverride All|None|directive-type + [directive-type] ... + + EnableSendfile On|Off + +## Standard Argument-Type Names ## + +Use these lowercase hyphenated names consistently in `` tags: + +| Name | Meaning | +|------|---------| +| `file-path` | Filesystem path (ServerRoot-relative if not absolute) | +| `directory-path` | Filesystem directory path | +| `URL-path` | URL path component (e.g. /images/) | +| `url` | Full URL | +| `filename` | Bare filename without directory | +| `extension` | File extension (e.g. .html) | +| `regex` | Regular expression | +| `expression` | ap_expr expression | +| `number` | Integer | +| `bytes` | Size in bytes | +| `seconds` | Time in seconds | +| `duration` | Time interval (may include unit suffix) | +| `hostname` | DNS hostname | +| `name` | Generic identifier | +| `value` | Generic value | +| `provider-name` | Authentication/authorization provider name | +| `env-variable` | Environment variable name | +| `MIME-type` | Media type (e.g. text/html) | +| `method` | HTTP method | + +## Quoting in Configuration Examples ## + +In `` blocks, quote these argument types: + +- 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 a nested `` block: + + + + Listen 80 + Listen 8000 + + + +Valid language values: `config` (most common), `lua`, `c`, `perl`, `sh`, `html`. + +Do **not** use bare `` with `
` for line breaks. This is a +legacy pattern. Convert to `` when editing such files. + +If an example needs a title, use ``: + + <example> + <title>2.4 configuration: + + Require all granted + + + +## Notes and Warnings ## + +Use `` for informational callouts: + + +

When you issue a restart, a syntax check is run first.

+ + +Use `` for critical warnings: + + +

Overlapping Listen directives will cause a fatal error.

+ + +A `` may contain a `` for labeled callouts: + + <note><title>Mixing old and new directives +

...

+ + +Do **not** use `Note:` in prose as a substitute for ``. + +## See Also ## + +Place `` elements after `` and before the first +`
`: + + Virtual Hosts + httpd + mod_ssl + +# Prose Style # + +## Voice and Person ## + +Address the reader directly in second person: + +> "You should review your configuration before upgrading." +> "If you want httpd to handle IPv4 connections only..." + +Use "we" occasionally when speaking as the project: + +> "We recommend using the apachectl control script." + +Avoid impersonal third-person constructions when second person is +natural: + +- **Avoid:** "The administrator should configure..." +- **Prefer:** "You should configure..." + +## Contractions ## + +Contractions are acceptable and widely used throughout the +documentation. Use them naturally: + +> "If it doesn't exist..." +> "...they won't be lost..." +> "...you can't use apachectl..." + +## Spelling ## + +Use American English spelling: + +- behavior (not behaviour) +- customize (not customise) +- recognize (not recognise) +- authorize (not authorise) +- color (not colour) + +## Product Name ## + +Use these forms in these contexts: + +- First reference in a page: "Apache HTTP Server" or "Apache httpd" +- Subsequent references: "httpd" (wrapped in `` when + referring to the executable, or bare when referring to the server generally) +- In `` tags: `httpd` + +Do **not** use bare "Apache" to refer to the server. "Apache" is the +foundation; "httpd" is the server. + +## Oxford Comma ## + +Use the Oxford (serial) comma: + +> "...addresses, hostnames, and ports." +> "...stop, restart, and graceful-stop." + +## Sentence Structure ## + +Prefer active voice over passive: + +- **Avoid:** "The directive is used to configure..." +- **Prefer:** "Use this directive to configure..." + +Keep sentences concise. Break complex instructions into numbered +steps or bullet lists. + +# Formatting and Structure # + +## Indentation ## + +Use spaces, not tabs. Indent consistently within each file (2 or 4 +spaces are both acceptable, but do not mix within a single file). + +Content inside `` blocks should be left-aligned (no leading +indentation) for config examples, since the whitespace is preserved +in output: + + + Listen 80 + Listen 8000 + + +## File Structure ## + +Every manual page follows this structure: + + + + + + + + + Page Title + ... + ... +
+ Section Title + ... +
+ + +## Section IDs ## + +Section `id` values should be short, lowercase, hyphenated English +identifiers: + +
+
+
+ +These IDs form URL anchors and must remain stable once published. + +## Character Encoding ## + +Use UTF-8 encoding for all new files. Write non-ASCII characters as +literal UTF-8 (e.g. é à ü), not as XML entities (e.g. `é`), +unless the file already uses XML entities consistently (as some +older German translations do). + +# Reader's Guide {#readers-guide} # + +When reading the Apache HTTP Server documentation: + +- *Italic text* (``) indicates emphasis — pay special attention + to the marked word. + +- *Slanted/colored text* (``) indicates a placeholder — replace + it with your own value. For example, `file-path` means + you supply an actual filesystem path. + +- `Monospace text` (``) indicates a literal value — type it + exactly as shown. This includes filenames, keywords, HTTP methods, + and header names. + +- **Bold text** (``) indicates a critical point — do not skip it. + +- Linked module names (``) and directive names (``) + are clickable cross-references to the relevant documentation. + +- Linked program names (``) are clickable cross-references + to the program's manual page. + +- Shaded blocks (``/``) contain configuration + snippets or shell commands that you can copy and adapt. + +- Callout boxes (``) contain supplementary information. + Warning boxes (``) indicate potential pitfalls + or destructive actions. + +- In directive syntax lines: + - UPPERCASE or lowercase-hyphenated placeholders are values you + supply (e.g. `file-path`, `URL-path`, `regex`). + - Literal keywords are shown as-is (e.g. `On`, `Off`, `All`, `None`). + - Square brackets `[ ]` indicate optional arguments. + - Pipe characters `|` separate alternative choices. + - Ellipsis `...` indicates the argument may be repeated. + - Quoted arguments in examples indicate that the quotes are + required or recommended in your configuration file.