mediawiki.conf: add more descriptive comment

[pve-docs.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 67179cee44bf34989640c059de250ef94af8ea85..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.


@@ -37,7 +37,7 @@ build time.
 
 Another package called 'pve-docs' is used to publish generated
 '.html' and '.pdf' files on our web servers. You can generate
 
 Another package called 'pve-docs' is used to publish generated
 '.html' and '.pdf' files on our web servers. You can generate

-those debian packages using:
+those Debian packages using:

 
  make deb
 
 
  make deb
 


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


@@ -82,7 +98,7 @@ below the title text:
  Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
  Level 4 (bottom level):  ++++++++++++++++++++++
 
  Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
  Level 4 (bottom level):  ++++++++++++++++++++++
 

-Section titles should always be preceeded by two empty lines. Each word
+Section titles should always be preceded by two empty lines. Each word

 in a title should be capitalized except for ``articles, coordinating
 conjunctions, prepositions, and the word to in infinitives unless they
 appear as the first or last word of a title'' (see
 in a title should be capitalized except for ``articles, coordinating
 conjunctions, prepositions, and the word to in infinitives unless they
 appear as the first or last word of a title'' (see


@@ -128,7 +144,7 @@ Labeled Lists
 ^^^^^^^^^^^^^
 
 Labeled lists should be used to make lists of key-value style text
 ^^^^^^^^^^^^^
 
 Labeled lists should be used to make lists of key-value style text

-more readable, such as command line parameters or config options:
+more readable, such as command line parameters or configuration options:

 
 .Regular labeled lists
 -----
 
 .Regular labeled lists
 -----


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