From: Fabian Grünbichler <f.gruenbichler@proxmox.com>
Date: Tue, 4 Oct 2016 12:10:23 +0000 (+0200)
Subject: readme: extend macro section
X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=commitdiff_plain;h=8ff3e5f7c146a61e7c54787c6654547f2dc79d55

readme: extend macro section
---

diff --git a/README.adoc b/README.adoc
index 5f2d464..c82d82e 100644
--- a/README.adoc
+++ b/README.adoc
@@ -3,7 +3,7 @@ Proxmox VE Documentation
 include::attributes.txt[]
 
 We try to generate high quality documentation for
-http://www.proxmox.com[Proxmox VE], and choose to use
+{website}[{pve}], and choose to use
 http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
 
 The basic idea is to generate high quality manual pages, and assemble
@@ -48,8 +48,24 @@ Common Macro definition in link:attributes.txt[]
 'asciidoc' allows us to define common macros, which can then be
 referred to using `{macro}`. We try to use this mechanism to improve
 consistency. For example, we defined a macro called `pve`, which
-expands to "Proxmox VE". The plan is to add more such definitions for
-terms which are used more than once.
+expands to "Proxmox VE".
+
+For URLs which are used more than once, two macros should be defined:
+
+* `{name-url}`, which just contains the http(s) URL
+* `{name}`, which contains the complete link including the canonical
+description
+
+For example, the macro `{forum-url}` expands to {forum-url}, and the macro
+`{forum}` expands to {forum}.
+
+The plan is to add more such definitions for terms which are used more than once.
+
+WARNING: When asciidoc encounters a misspelled macro name, it will silently drop
+the containing line!
+
+WARNING: Never use macros in document titles or the ``NAME'' section of man pages,
+as these get parsed before the `attributes.txt` file gets included.
 
 Autogenerated CLI Command Synopsis
 ----------------------------------