X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=README.adoc;h=18afecc139abcb8de25934207b3a978fb513e661;hp=ed031141cf3e1be4673fefb1683750383cea542e;hb=f00afaef559beefc56c8eed970c5b8ef2a550ada;hpb=7aacca6f1d325ac2014e98852a40d3e967ccb216 diff --git a/README.adoc b/README.adoc index ed03114..18afecc 100644 --- a/README.adoc +++ b/README.adoc @@ -1,16 +1,15 @@ Proxmox VE Documentation ======================== -include::attributes.txt[] We try to generate high quality documentation for -http://www.proxmox.com[Proxmox VE], and choose to use +{website}[{pve}], and choose to use http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format. 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. @@ -37,19 +36,34 @@ 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: +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 consistency. For example, we defined a macro called `pve`, which -expands to "Proxmox VE". The plan is to add more such definitions for -terms which are used more than once. +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! + Autogenerated CLI Command Synopsis ---------------------------------- @@ -61,6 +75,256 @@ 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. + + +Online Help +----------- +Each {pve} installation contains the full documentation in HTML format, +which is then used as the target of various help buttons in the GUI. + +If after adding a specific entry in the documentation you want to +create a help button pointing to that, you need to do the +following: + +* add a string id in double square brackets before your +documentation entry, like `[[qm_general_settings]]` +* rebuild the `asciidoc-pve` script and the HTML chapter file containing +your entry +* add a property `onlineHelp` in the ExtJS panel you want to document, +using the above string, like `onlineHelp: qm_general_settings` +This panel has to be a child class of PVE.panel.InputPanel + +On calling `make install` the asciidoc-pve script will populate +a JS object associating the string id and a link to the +local HTML documentation, and the help button of your input panel +will point to this link. + + +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 ... +---- + +The corresponding file need to reside inside folder +`images/screenshot`, and should be in `.png` image format. We include +the screenshots in printed documentation, and 'pdftex' uses the +density (DPI) specified inside the file. So all screenshots should use +the same density. We currently require the density set to 146 DPI, so +that we can display a 1024 pixels wide image. You should not include +larger screenshots (although it is possible). + +You can use the `./png-cleanup.pl` script to set the correct +density. Simply use the following command to import a screenshot +image: + +---- +# ./png-cleanup.pl screenshot.png images/screenshot/screenshot.png +---- + +TIP: You can use `identify -verbose screenshot.png` command to show +all image attributes (from debian package 'imagemagick') + +.Default Screenshot Layout + +[thumbnail="gui-datacenter-search.png"] + +We normally display screenshots as small thumbnail on the right side +of a paraprah. On printed docomentation, we render the full sized +graphic just before the paragraph, or between the title and the text +if the paragraph has a title. It is usually a good idea to add a title +to paragraph with screenshots. + +[thumbnail="gui-datacenter-search.png", float="left"] + +If you need to render many screenshots, it is possible to place them +on the left side, so you can alternate the thumbnail position using the +`float` attribute: + +---- +[thumbnail="gui-datacenter-search.png", float="left"] +If you need to render many screenshots ... +---- + +Please avoid to many consecutive screenshots to avoid rendering +problems. Also verify the printed documentation to see if large +screenshots create layout problems. + + Copyright ---------