readme: extend macro section
authorFabian Gr├╝nbichler <f.gruenbichler@proxmox.com>
Tue, 4 Oct 2016 12:10:23 +0000 (14:10 +0200)
committerDietmar Maurer <dietmar@proxmox.com>
Wed, 5 Oct 2016 04:42:39 +0000 (06:42 +0200)
README.adoc

index 5f2d464..c82d82e 100644 (file)
@@ -3,7 +3,7 @@ Proxmox VE Documentation
 include::attributes.txt[]
 
 We try to generate high quality documentation for
 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
 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
 '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
 ----------------------------------
 
 Autogenerated CLI Command Synopsis
 ----------------------------------