Title: Documentation Style Guide license: https://www.apache.org/licenses/LICENSE-2.0
This guide defines conventions for writing and editing the Apache HTTP Server documentation.
There are two main audiences for this guide:
<var> — User-Supplied PlaceholdersUse <var> 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.
<syntax>Listen <var>port</var></syntax> <syntax>AuthUserFile <var>file-path</var></syntax> <p>Replace <var>hostname</var> with your server's FQDN.</p>
Do not use <em> for placeholders. Legacy files use <em> in this role; new and updated content should use <var> exclusively.
<em> — EmphasisUse <em> only for rhetorical emphasis — drawing attention to a word or phrase in running prose.
<p>The directive must appear <em>before</em> any VirtualHost blocks.</p> <p>This applies to <em>all</em> requests, not just local ones.</p>
Common legitimate uses: not, must, only, all, any, before, after, e.g., i.e., etc.
Do not use <em> for placeholder variables (use <var>), for keywords (use <code>), or for strong warnings (use <strong>).
<code> — Literal Values and Inline CodeUse <code> for any literal string that appears in configuration, commands, output, or protocols:
<code>.htaccess</code>, <code>httpd.conf</code><code>GET</code>, <code>POST</code><code>Content-Type</code>, <code>ETag</code><code>On</code>, <code>Off</code>, <code>None</code><code>text/html</code><code>PATH_INFO</code><code>-k</code>, <code>graceful</code><code>TERM</code>, <code>USR1</code>Do not nest <strong> inside <code>. If emphasis is needed on a code element, restructure the sentence so the emphasis is in the prose.
<strong> — Strong EmphasisUse <strong> sparingly, for critical warnings or to highlight a word that the reader must not miss:
<p>You should <strong>not</strong> use this in production.</p>
Do not use <strong> inside <code> blocks. Do not use <strong> where <note type="warning"> would be more appropriate.
<program> — Apache httpd ProgramsUse <program> for any executable that ships with httpd and has its own manual page:
<program>httpd</program> <program>apachectl</program> <program>htpasswd</program> <program>rotatelogs</program> <program>configure</program>
This generates a cross-reference link to the program's documentation. Do not use <code> for httpd program names.
<module> — Module NamesUse <module> for Apache module names. This generates a cross-reference link to the module's documentation:
<module>mod_rewrite</module> <module>mod_ssl</module> <module>core</module>
Do not use <code> for module names.
<directive> — Directive NamesUse <directive> for Apache directive names. Include the module attribute when referencing a directive outside its own module's documentation:
<directive module="core">ServerRoot</directive> <directive module="mpm_common">Listen</directive>
Within a module's own documentation, the module attribute may be omitted:
<directive>Listen</directive>
For section directives, add type="section":
<directive module="core" type="section">VirtualHost</directive>
<glossary> — Glossary TermsUse <glossary> for terms defined in the project glossary. Use the ref attribute when the link target differs from the display text:
<glossary>APR</glossary> <glossary ref="regex">regular expression</glossary> <glossary>MIME-type</glossary>
<rfc> — RFC ReferencesUse <rfc> to link to IETF RFCs. The element content is the RFC number (digits only). The rendered output is “RFC NNNN” linked to https://www.rfc-editor.org/rfc/rfcNNNN.
<rfc>7230</rfc> <rfc>9110</rfc>
To link to a numbered section within an RFC, use the section attribute. This appends #section-N to the URL:
<rfc section="14.24">2616</rfc> <rfc section="4.4">2616</rfc>
To link to a named anchor (appendix, named section heading, etc.), use the anchor attribute. This appends #value to the URL as-is:
<rfc anchor="appendix-B">7231</rfc> <rfc anchor="name-upgrade">9110</rfc> <rfc anchor="name-content-encoding">9110</rfc>
Do not use both section and anchor on the same element.
Do not use <a href="..."> with rfc-editor.org URLs when the <rfc> tag can express the link. Use <a> only for:
Use <var> for all user-supplied arguments in <syntax> blocks:
<syntax>ServerRoot <var>directory-path</var></syntax> <syntax>Timeout <var>time-interval</var>[s]</syntax>
Literal keyword choices appear untagged, separated by |:
<syntax>AllowOverride All|None|<var>directive-type</var> [<var>directive-type</var>] ...</syntax> <syntax>EnableSendfile On|Off</syntax>
Use these lowercase hyphenated names consistently in <var> 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 |
In <highlight language="config"> blocks, quote these argument types:
ServerRoot "/usr/local/apache2"Redirect "/" "https://example.com/"AuthName "Restricted Area"RewriteRule "^/old(.*)" "/new$1"Do not quote bare keywords:
AllowOverride NoneOptions FollowSymLinksRequire all grantedUse <example> with a nested <highlight language="..."> block:
<example> <highlight language="config"> Listen 80 Listen 8000 </highlight> </example>
Valid language values: config (most common), sh, python, lua, c, perl, html.
Do not use bare <example> with <br /> for line breaks. This is a legacy pattern. Convert to <highlight> when editing such files.
If an example needs a title, use <example><title>:
<example> <title>2.4 configuration:</title> <highlight language="config"> Require all granted </highlight> </example>
Use <note> for informational callouts:
<note> <p>When you issue a restart, a syntax check is run first.</p> </note>
Use <note type="warning"> for critical warnings:
<note type="warning"> <p>Overlapping Listen directives will cause a fatal error.</p> </note>
A <note> may contain a <title> for labeled callouts:
<note><title>Mixing old and new directives</title> <p>...</p> </note>
Do not use <strong>Note:</strong> in prose as a substitute for <note>.
Place <seealso> elements after <summary> and before the first <section>:
<seealso><a href="vhosts/">Virtual Hosts</a></seealso> <seealso><program>httpd</program></seealso> <seealso><module>mod_ssl</module></seealso>
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:
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...”
Use American English spelling:
Use these forms in these contexts:
<program> when referring to the executable, or bare when referring to the server generally)<program> tags: <program>httpd</program>Do not use bare “Apache” to refer to the server. “Apache” is the foundation; “httpd” is the server.
Use the Oxford (serial) comma:
“...addresses, hostnames, and ports.” “...stop, restart, and graceful-stop.”
Prefer active voice over passive:
Keep sentences concise. Break complex instructions into numbered steps or bullet lists.
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 <highlight> blocks should be left-aligned (no leading indentation) for config examples, since the whitespace is preserved in output:
<highlight language="config"> Listen 80 Listen 8000 </highlight>
Every manual page follows this structure:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
<!-- $LastChangedRevision: NNNNNNN $ -->
<!-- License block -->
<manualpage metafile="BASENAME.xml.meta">
<title>Page Title</title>
<summary>...</summary>
<seealso>...</seealso>
<section id="unique-id">
<title>Section Title</title>
...
</section>
</manualpage>
Section id values should be short, lowercase, hyphenated English identifiers:
<section id="compile-time"> <section id="access"> <section id="commonproblems">
These IDs form URL anchors and must remain stable once published.
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).
When reading the Apache HTTP Server documentation:
Italic text (<em>) indicates emphasis — pay special attention to the marked word.
Slanted/colored text (<var>) indicates a placeholder — replace it with your own value. For example, <var>file-path</var> means you supply an actual filesystem path.
Monospace text (<code>) indicates a literal value — type it exactly as shown. This includes filenames, keywords, HTTP methods, and header names.
Bold text (<strong>) indicates a critical point — do not skip it.
Linked module names (<module>) and directive names (<directive>) are clickable cross-references to the relevant documentation.
Linked program names (<program>) are clickable cross-references to the program's manual page.
Shaded blocks (<example>/<highlight>) contain configuration snippets or shell commands that you can copy and adapt.
Callout boxes (<note>) contain supplementary information. Warning boxes (<note type="warning">) indicate potential pitfalls or destructive actions.
In directive syntax lines:
file-path, URL-path, regex).On, Off, All, None).[ ] indicate optional arguments.| separate alternative choices.... indicates the argument may be repeated.