[pve-devel] [PATCH v2 docs 1/2] readme: extend macro section

[Fabian Grünbichler]

---
changes to v1: add second warning

 README.adoc | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

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
 ----------------------------------
-- 
2.1.4