README.adoc

   1 Proxmox VE Documentation
   2 ========================
   3
   4 We try to generate high quality documentation for
   5 {website}[{pve}], and choose to use
   6 http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
   7
   8 The basic idea is to generate high quality manual pages, and assemble
   9 them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
  10 Administration Guide].  So we have one source, and generate several
  11 documents from that. It is also possible to generate printable PDF
  12 files, or ebook formats ('.epub').
  13
  14 When possible, we provide scripts to extract API definitions,
  15 configuration or command line options from the source code.
  16
  17 To simplify the documentation task, we keep all Documentation within
  18 this repository. It is possible to generate the docs without installing
  19 any additional Proxmox packages with:
  20
  21  make index
  22
  23 To update the auto-generate API definitions use:
  24
  25  make update
  26
  27 NOTE: you need a fully installed development environment for that.
  28
  29
  30 Debian Packages
  31 ---------------
  32
  33 We generate a development package called 'pve-doc-generator', which is
  34 used by other Proxmox VE package to generate manual pages at package
  35 build time.
  36
  37 Another package called 'pve-docs' is used to publish generated
  38 '.html' and '.pdf' files on our web servers. You can generate
  39 those Debian packages using:
  40
  41  make deb
  42
  43
  44 Common Macro definition in link:asciidoc/asciidoc-pve.conf[]
  45 ------------------------------------------------------------
  46
  47 'asciidoc' allows us to define common macros, which can then be
  48 referred to using `{macro}`. We try to use this mechanism to improve
  49 consistency. For example, we defined a macro called `pve`, which
  50 expands to "Proxmox VE".
  51
  52 For URLs which are used more than once, two macros should be defined:
  53
  54 * `{name-url}`, which just contains the http(s) URL
  55 * `{name}`, which contains the complete link including the canonical
  56 description
  57
  58 For example, the macro `{forum-url}` expands to {forum-url}, and the macro
  59 `{forum}` expands to {forum}.
  60
  61 The plan is to add more such definitions for terms which are used more
  62 than once.
  63
  64 WARNING: When asciidoc encounters a misspelled macro name, it will
  65 silently drop the containing line!
  66
  67
  68 Autogenerated CLI Command Synopsis
  69 ----------------------------------
  70
  71 We generate the command line synopsis for all manual pages
  72 automatically. We can do that, because we have a full declarative
  73 definition of the {pve} API. I added those generated files
  74 ('*-synopsis.adoc') to the git repository, so that it is possible to
  75 build the documentation without having a fully installed {pve}
  76 development environment.
  77
  78 Style Guide
  79 -----------
  80
  81 'asciidoc' uses a fairly simple markup syntax for formatting content.
  82 The following basic principles should be followed throughout our
  83 documentation.
  84
  85
  86 Sections
  87 ~~~~~~~~
  88
  89 Sections are formatted using `two-line titles', by adding a line of
  90 the appropriate characters and of the same length as the section title
  91 below the title text:
  92
  93  Level 0 (top level):     ======================
  94  Level 1:                 ----------------------
  95  Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
  96  Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
  97  Level 4 (bottom level):  ++++++++++++++++++++++
  98
  99 Section titles should always be preceded by two empty lines. Each word
 100 in a title should be capitalized except for ``articles, coordinating
 101 conjunctions, prepositions, and the word to in infinitives unless they
 102 appear as the first or last word of a title'' (see
 103 http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]).
 104
 105
 106 Lists
 107 ~~~~~
 108
 109 Numbered Lists
 110 ^^^^^^^^^^^^^^
 111
 112 Numbered lists should be created using the implicit numbering format:
 113
 114 -----
 115 . First level
 116 .. Second level
 117 . First level again
 118 -----
 119
 120 . First level
 121 .. Second level
 122 . First level again
 123
 124
 125 Bulleted Lists
 126 ^^^^^^^^^^^^^^
 127
 128 Bulleted lists should be created using the '*' symbol:
 129
 130 -----
 131 * First level
 132 ** Second level
 133 * First level again
 134 -----
 135
 136 * First level
 137 ** Second level
 138 * First level again
 139
 140
 141 Labeled Lists
 142 ^^^^^^^^^^^^^
 143
 144 Labeled lists should be used to make lists of key-value style text
 145 more readable, such as command line parameters or configuration options:
 146
 147 .Regular labeled lists
 148 -----
 149 First Label Text::
 150
 151 Element text paragraph
 152
 153 Second Label Text::
 154
 155 Another element text paragraph.
 156 -----
 157
 158 First Label Text::
 159
 160 Element text paragraph
 161
 162 Second Label Text::
 163
 164 Another element text paragraph.
 165
 166 .Horizontal labeled lists
 167 -----
 168 [horizontal]
 169 First Label Text:: Element text paragraph
 170
 171 Second Label Text:: Another element text paragraph.
 172 -----
 173
 174 creates
 175
 176 [horizontal]
 177 First Label Text:: Element text paragraph
 178
 179 Second Label Text:: Another element text paragraph.
 180
 181 The FAQ section uses a special questions and answers style for
 182 labeled lists.
 183
 184
 185 Text and Block Styles
 186 ~~~~~~~~~~~~~~~~~~~~~
 187
 188 'asciidoc' offers a wide range of default text styles:
 189
 190 * 'Emphasized text': created using \'text', used for emphasizing words
 191 and phrases
 192 * `Monospaced text`: created using \`text`, used for command / program
 193 names, file paths, in-line commands, option names and values
 194 * *Strong text*: created using \*text*, used for emphasizing concepts
 195 or names when first introduced in a section.
 196
 197 There are also different built-in block styles that are used in
 198 our documentation:
 199
 200 Complete paragraphs can be included literally by prepending each
 201 of their lines with whitespace. Use this for formatting complete
 202 commands on their own line, such as:
 203
 204  pct set ID -option value
 205
 206 ----
 207 By surrounding a paragraph with lines containing at least four '-'
 208 characters, its content is formatted as listing.
 209
 210 Use this for formatting file contents or command output.
 211 ----
 212
 213 Specially highlighted 'notes', 'warnings' and 'important' information
 214 can be created by starting a paragraph with `NOTE:`, `WARNING:` or
 215 `IMPORTANT:`:
 216
 217 NOTE: this is a note
 218
 219 WARNING: this is warning
 220
 221 IMPORTANT: this is important information
 222
 223 For each of these blocks (including lists and paragraphs), a block header
 224 can be defined by prepending the block with a `.' character and the header
 225 text:
 226
 227 -----
 228 .Title of List
 229 * First element
 230 * Second element
 231 * Third element
 232 -----
 233
 234 .Title of List
 235 * First element
 236 * Second element
 237 * Third element
 238
 239 For example, block headers can be used to add file names/paths to file
 240 content listings.
 241
 242 Screenshots
 243 -----------
 244
 245 [thumbnail="gui-datacenter-search.png"]
 246
 247 First, it should be noted that we can display screenshots on 'html'
 248 and 'wiki' pages, and we can include them in printed doumentation. But
 249 ith is not possible to render them inside manual pages. So screenshot
 250 inside manual pages should be optional, i.e. the text should not
 251 depend on the visibility of the screenshot. You can include a
 252 screenshot by setting the 'thumbnail' attribute on a paragraph:
 253
 254 ----
 255 [thumbnail="gui-datacenter-search.png"]
 256 First, it should be noted ...
 257 ----
 258
 259 The corresponding file need to reside inside folder
 260 `images/screenshot`, and should be in `.png` image format. We include
 261 the screenshots in printed documentation, and 'pdftex' uses the
 262 density (DPI) specified inside the file. So all screenshots should use
 263 the same density. We currently require the density set to 146 DPI, so
 264 that we can display a 1024 pixels wide image. You should not include
 265 larger screenshots (although it is possible).
 266
 267 You can use the `./png-cleanup.pl` script to set the correct
 268 density. Simply use the following command to import a screenshot
 269 image:
 270
 271 ----
 272 # ./png-cleanup.pl screenshot.png images/screenshot/screenshot.png
 273 ----
 274
 275 TIP: You can use `identify -verbose screenshot.png` command to show
 276 all image attributes (from debian package 'imagemagick')
 277
 278 .Default Screenshot Layout
 279
 280 [thumbnail="gui-datacenter-search.png"]
 281
 282 We normally display screenshots as small thumbnail on the right side
 283 of a paraprah. On printed docomentation, we render the full sized
 284 graphic just before the paragraph, or between the title and the text
 285 if the paragraph has a title. It is usually a good idea to add a title
 286 to paragraph with screenshots.
 287
 288 [thumbnail="gui-datacenter-search.png", float="left"]
 289
 290 If you need to render many screenshots, it is possible to place them
 291 on the left side, so you can alternate the thumbnail position using the
 292 `float` attribute:
 293
 294 ----
 295 [thumbnail="gui-datacenter-search.png", float="left"]
 296 If you need to render many screenshots ...
 297 ----
 298
 299 Please avoid to many consecutive screenshots to avoid rendering
 300 problems. Also verify the printed documentation to see if large
 301 screenshots create layout problems.
 302
 303
 304 Copyright
 305 ---------
 306
 307 Copyright (C) 2016 Proxmox Server Solutions Gmbh
 308
 309 Permission is granted to copy, distribute and/or modify this document
 310 under the terms of the GNU Free Documentation License, Version 1.3 or
 311 any later version published by the Free Software Foundation; with no
 312 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
 313 copy of the license is included in the link:LICENSE[LICENSE] file.