X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=README.adoc;h=c82d82ed86286498a6f30cf1bb03fd76567fc250;hp=7907228a13625450cecb50bc1de30a62a23eb819;hb=8ff3e5f7c146a61e7c54787c6654547f2dc79d55;hpb=40152dfdb777a82308c35721af45bd9ad46a2bf9 diff --git a/README.adoc b/README.adoc index 7907228..c82d82e 100644 --- a/README.adoc +++ b/README.adoc @@ -1,18 +1,71 @@ Proxmox VE Documentation ======================== +include::attributes.txt[] -What is this? -------------- - -This is an experimental project, trying to generate high quality -documentation for http://www.proxmox.com[Proxmox VE]. We choose to use +We try to generate high quality documentation for +{website}[{pve}], and choose to use http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format. -One idea is to generate high quality manual pages, and assemble them -into a complete book, called link:pve-admin-guide.adoc[Proxmox VE +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. + +To simplify the documentation task, we keep all Documentation within +this repository. It is possible to generate the docs without installing +any additional Proxmox packages with: + + make index + +To update the auto-generate API definitions use: + + make update + +NOTE: you need a fully installed development environment for that. + + +Debian Packages +--------------- + +We generate a development package called 'pve-doc-generator', which is +used by other Proxmox VE package to generate manual pages at package +build time. + +Another package called 'pve-docs' is used to publish generated +'.html' and '.pdf' files on our web servers. You can generate +those Debian packages using: + + make deb + + +Common Macro definition in link:attributes.txt[] +------------------------------------------------ + +'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". + +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! + +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 ---------------------------------- @@ -24,6 +77,171 @@ definition of the {pve} API. I added those generated files build the documentation without having a fully installed {pve} development environment. +Style Guide +----------- + +'asciidoc' uses a fairly simple markup syntax for formatting content. +The following basic principles should be followed throughout our +documentation. + + +Sections +~~~~~~~~ + +Sections are formatted using `two-line titles', by adding a line of +the appropriate characters and of the same length as the section title +below the title text: + + Level 0 (top level): ====================== + Level 1: ---------------------- + Level 2: ~~~~~~~~~~~~~~~~~~~~~~ + Level 3: ^^^^^^^^^^^^^^^^^^^^^^ + Level 4 (bottom level): ++++++++++++++++++++++ + +Section titles should always be preceded by two empty lines. Each word +in a title should be capitalized except for ``articles, coordinating +conjunctions, prepositions, and the word to in infinitives unless they +appear as the first or last word of a title'' (see +http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]). + + +Lists +~~~~~ + +Numbered Lists +^^^^^^^^^^^^^^ + +Numbered lists should be created using the implicit numbering format: + +----- +. First level +.. Second level +. First level again +----- + +. First level +.. Second level +. First level again + + +Bulleted Lists +^^^^^^^^^^^^^^ + +Bulleted lists should be created using the '*' symbol: + +----- +* First level +** Second level +* First level again +----- + +* First level +** Second level +* First level again + + +Labeled Lists +^^^^^^^^^^^^^ + +Labeled lists should be used to make lists of key-value style text +more readable, such as command line parameters or configuration options: + +.Regular labeled lists +----- +First Label Text:: + +Element text paragraph + +Second Label Text:: + +Another element text paragraph. +----- + +First Label Text:: + +Element text paragraph + +Second Label Text:: + +Another element text paragraph. + +.Horizontal labeled lists +----- +[horizontal] +First Label Text:: Element text paragraph + +Second Label Text:: Another element text paragraph. +----- + +creates + +[horizontal] +First Label Text:: Element text paragraph + +Second Label Text:: Another element text paragraph. + +The FAQ section uses a special questions and answers style for +labeled lists. + + +Text and Block Styles +~~~~~~~~~~~~~~~~~~~~~ + +'asciidoc' offers a wide range of default text styles: + +* 'Emphasized text': created using \'text', used for emphasizing words +and phrases +* `Monospaced text`: created using \`text`, used for command / program +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. + +There are also different built-in block styles that are used in +our documentation: + +Complete paragraphs can be included literally by prepending each +of their lines with whitespace. Use this for formatting complete +commands on their own line, such as: + + pct set ID -option value + +---- +By surrounding a paragraph with lines containing at least four '-' +characters, its content is formatted as listing. + +Use this for formatting file contents or command output. +---- + +Specially highlighted 'notes', 'warnings' and 'important' information +can be created by starting a paragraph with `NOTE:`, `WARNING:` or +`IMPORTANT:`: + +NOTE: this is a note + +WARNING: this is warning + +IMPORTANT: this is important information + +For each of these blocks (including lists and paragraphs), a block header +can be defined by prepending the block with a `.' character and the header +text: + +----- +.Title of List +* First element +* Second element +* Third element +----- + +.Title of List +* First element +* Second element +* Third element + +For example, block headers can be used to add file names/paths to file +content listings. + + Copyright ---------