X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=README.adoc;h=754ca1e4410ec64823ded49a026be1f695151ae4;hp=2970e60fa9f476ed2b346744b69492b77b9f1f15;hb=HEAD;hpb=0d1b9a161a2277dfc19e61617e8f83f201b4fe79 diff --git a/README.adoc b/README.adoc index 2970e60..3d614e5 100644 --- a/README.adoc +++ b/README.adoc @@ -18,6 +18,7 @@ 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 pve-doc-generator.mk make index To update the auto-generate API definitions use: @@ -96,6 +97,10 @@ below the title text: Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ +NOTE: Level 4 headings are currently not working for `manpage` outputs, you may +want to use `.SECTION' instead, which results in the same rendering, and this +level of Heading isn't displayed in any Index/TOC anyway. + 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 @@ -138,6 +143,24 @@ Bulleted lists should be created using the '*' symbol: * First level again +If you need to have other elements on the same level as a list element you +can do this with the '+' symbol: + +---- +. First level +.. Second level ++ +Another Sentence (or Block) on the continued second level. +. First level again +---- + +. First level +.. Second level ++ +Another Sentence (or Block) on the continued second level. + +. First level again + Labeled Lists ^^^^^^^^^^^^^ @@ -210,10 +233,12 @@ 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 +Specially highlighted 'tips', 'notes', 'warnings' and 'important' information +can be created by starting a paragraph with `TIP`, `NOTE:`, `WARNING:` or `IMPORTANT:`: +TIP: this is a tip + NOTE: this is a note WARNING: this is warning @@ -239,30 +264,96 @@ text: 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"] +[thumbnail="screenshot/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 +and 'wiki' pages, and we can include them in printed documentation. But +it 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"] +[thumbnail="screenshot/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="screenshot/gui-datacenter-search.png"] + +We normally display screenshots as small thumbnail on the right side +of a paragraph. On printed documentation, 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="screenshot/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="screenshot/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 --------- -Copyright (C) 2016 Proxmox Server Solutions Gmbh +Copyright (C) 2016-2021 Proxmox Server Solutions GmbH Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or