remove attributes.txt (use asciidoc/asciidoc-pve.conf instead)

[pve-docs.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 41d4cba141cf8b6b009228270b59841266171798..062b94eff9634b3266b220c2e851ff9ac90e13d2 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,16 +1,15 @@
 Proxmox VE Documentation
 ========================
 Proxmox VE Documentation
 ========================

-include::attributes.txt[]

 
 We try to generate high quality documentation for
 
 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.


@@ -42,14 +41,29 @@ those Debian packages using:
  make deb
 
 
  make deb
 
 

-Common Macro definition in link:attributes.txt[]
-------------------------------------------------
+Common Macro definition in link:asciidoc/asciidoc-pve.conf[]
+------------------------------------------------------------

 
 '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!
+

 
 Autogenerated CLI Command Synopsis
 ----------------------------------
 
 Autogenerated CLI Command Synopsis
 ----------------------------------


@@ -176,11 +190,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