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