readme: extend macro section

[pve-docs.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 41d4cba141cf8b6b009228270b59841266171798..c82d82ed86286498a6f30cf1bb03fd76567fc250 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -3,14 +3,14 @@ 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
 them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
 Administration Guide].  So we have one source, and generate several
 documents from that. It is also possible to generate printable PDF
 http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
 
 The basic idea is to generate high quality manual pages, and assemble
 them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
 Administration Guide].  So we have one source, and generate several
 documents from that. It is also possible to generate printable PDF

-files, or ebook formats ('.ebup').
+files, or ebook formats ('.epub').

 
 When possible, we provide scripts to extract API definitions,
 configuration or command line options from the source code.
 
 When possible, we provide scripts to extract API definitions,
 configuration or command line options from the source code.


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


@@ -176,11 +192,11 @@ Text and Block Styles
 * 'Emphasized text': created using \'text', used for emphasizing words
 and phrases
 * `Monospaced text`: created using \`text`, used for command / program
 * 'Emphasized text': created using \'text', used for emphasizing words
 and phrases
 * `Monospaced text`: created using \`text`, used for command / program

-names, file paths, inline commands, option names and values
+names, file paths, in-line commands, option names and values

 * *Strong text*: created using \*text*, used for emphasizing concepts
 or names when first introduced in a section.
 
 * *Strong text*: created using \*text*, used for emphasizing concepts
 or names when first introduced in a section.
 

-There are also different builtin block styles that are used in
+There are also different built-in block styles that are used in

 our documentation:
 
 Complete paragraphs can be included literally by prepending each
 our documentation:
 
 Complete paragraphs can be included literally by prepending each