README.adoc: explain howto include screenshots

[pve-docs.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index c82d82ed86286498a6f30cf1bb03fd76567fc250..2970e60fa9f476ed2b346744b69492b77b9f1f15 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,6 +1,5 @@
 Proxmox VE Documentation
 ========================
-include::attributes.txt[]
 
 We try to generate high quality documentation for
 {website}[{pve}], and choose to use
@@ -42,8 +41,8 @@ those Debian packages using:
  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
@@ -59,13 +58,12 @@ 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.
+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: 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
 ----------------------------------
@@ -241,6 +239,25 @@ text:
 For example, block headers can be used to add file names/paths to file
 content listings.
 
+Screenshots
+-----------
+
+[thumbnail="gui-datacenter-search.png"]
+
+First, it should be noted that we can display screenshots on 'html'
+and 'wiki' pages, and we can include them in printed doumentation. But
+ith is not possible to render them inside manual pages. So screenshot
+inside manual pages should be optional, i.e. the text should not
+depend on the visibility of the screenshot. You can include a
+screenshot by setting the 'thumbnail' attribute on a paragraph:
+
+----
+[thumbnail="gui-datacenter-search.png"]
+First, it should be noted ...
+----
+
+
+
 
 Copyright
 ---------