README.adoc: add info about macro usage
[pve-docs.git] / README.adoc
1 Proxmox VE Documentation
2 ========================
3 include::attributes.txt[]
4
5 What is this?
6 -------------
7
8 This is an experimental project, trying to generate high quality
9 documentation for http://www.proxmox.com[Proxmox VE]. We choose to use
10 http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
11
12 One idea is to generate high quality manual pages, and assemble them
13 into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
14 Administration Guide].  So we have one source, and generate several
15 documents from that. It is also possible to generate printable PDF
16 files, or ebook formats ('.ebup').
17
18 Common Macro definition in link:attributes.txt[]
19 ------------------------------------------------
20
21 'asciidoc' allows us to define common macros, which can then be
22 referred to using `{macro}`. We try to use this mechanism to improve
23 consistency. For example, we defined a macro called `pve`, which
24 expands to "Proxmox VE". The plan is to add more such definitions for
25 terms which are used more than once.
26
27 NOTE: The github 'asciidoc' viewer does not expand those macros.
28
29 Autogenerated CLI Command Synopsis
30 ----------------------------------
31
32 We generate the command line synopsis for all manual pages
33 automatically. We can do that, because we have a full declarative
34 definition of the {pve} API. I added those generated files
35 ('*-synopsis.adoc') to the git repository, so that it is possible to
36 build the documentation without having a fully installed {pve}
37 development environment.
38
39 Copyright
40 ---------
41
42 Copyright (C) 2016 Proxmox Server Solutions Gmbh
43
44 Permission is granted to copy, distribute and/or modify this document
45 under the terms of the GNU Free Documentation License, Version 1.3 or
46 any later version published by the Free Software Foundation; with no
47 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
48 copy of the license is included in the link:LICENSE[LICENSE] file.