Update the about and user documentation
Parts of this documentation were specific to Markdown and it looked
like no other formats are supported. Make the description more general
and link to the formatter list from the user guide.
Change-Id: I9e7a0f2f69bb91829f6bc47d256ef4bfee1029e0
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 531c7cc..5e99a7f 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -1,6 +1,6 @@
-This plugin serves Markdown project documentation as HTML pages.
+This plugin serves project documentation as HTML pages.
-If projects contain documentation as Markdown files, the plugin
+If projects contain documentation, e.g. as Markdown files, the plugin
automatically serves the generated HTML under
`/@PLUGIN@/project/<project-name>/<file-name>`. The project name and
the file name must be URL encoded.
@@ -15,8 +15,8 @@
`rev` can be any ref or commit that is visible to the calling user.
-If the file name is omitted the plugin serves the `README.md` from the
-project if available.
+If the file name is omitted, by default the plugin serves the
+`README.md` from the project if available.
By setting the URL parameter `raw` the document will be returned as raw
unformatted text.
@@ -27,10 +27,12 @@
The `raw` parameter cannot be used for binary files.
-*WARNING:* All HTML blocks as well as inline HTML tags are suppressed.
-Both will be accepted in the input but not be contained in the output.
+*WARNING:* By default inline HTML blocks as well as inline HTML tags
+may be [suppressed](config.html#formatterAllowHtml) by formatters. If
+suppressed both will be accepted in the input but not be contained in
+the output.
-Images that are stored in the project can be included into the Markdown
+Images that are stored in the project can be included into the project
documentation, but they are only rendered if the image mimetype is
configured as a
[safe mimetype](../../../Documentation/config-gerrit.html#mimetype).
diff --git a/src/main/resources/Documentation/user.md b/src/main/resources/Documentation/user.md
index 9cd5c3e..32473e6 100644
--- a/src/main/resources/Documentation/user.md
+++ b/src/main/resources/Documentation/user.md
@@ -1,21 +1,23 @@
User Guide
==========
-The @PLUGIN@ plugin serves [Markdown](http://daringfireball.net/projects/markdown/)
-project documentation as HTML pages.
+The @PLUGIN@ plugin serves project documentation as HTML pages. Project
+documentation can be written in different syntaxes, e.g. as
+[Markdown](http://daringfireball.net/projects/markdown/) or
+[Asciidoc](http://www.methods.co.nz/asciidoc/userguide.html).
-The entry point to the project documentation is a `README.md` file in
-the root directory of a project (if not [configured](config.html#webIndexFile)
-differently).
+By default the entry point to the project documentation is a
+`README.md` file in the root directory of a project. Another index file
+may be [configured](config.html#webIndexFile).
-If a project has a `README.md` file in its root directory then a link
+If a project contains the index file in its root directory then a link
to the project documentation is displayed for it in the
[project list](@URL@#/admin/projects/).
Clicking on the documentation icon opens the rendered HTML of the
-`README.md` file in a new tab.
+index file in a new tab.
@@ -31,18 +33,19 @@
When reviewing documentation changes a preview of the rendered HTML is
-available for Markdown files. This allows to detect any formatting
-issues quickly. The preview is available from the side-by-side diff
-view and it is opened in a new tab.
+available for project documentation files. This allows to detect any
+formatting issues quickly. The preview is available from the
+side-by-side diff view and it is opened in a new tab.
-The URL scheme of the plugin allows to access the HTML of all Markdown
-file in the project from any revision (branch or commit). The project
-name, the revision and the file name must be URL encoded.
+The URL scheme of the plugin allows to access the HTML of all project
+documentation files in the project from any revision (branch or
+commit). The project name, the revision and the file name must be URL
+encoded.
```
- /@PLUGIN@/project/<project>/rev/<revision>/<file>.md
+ /@PLUGIN@/project/<project>/rev/<revision>/<file>
```
E.g.:
@@ -51,14 +54,14 @@
/@PLUGIN@/project/dev%2Ftools%2Fcode-checks/rev/stable-1.3/docs%2Ffaq.md
```
-A Markdown file can contain links to other Markdown files which are
-contained in the project.
+A project documentation file can contain links to other project
+documentation files which are contained in the project.
```
The installation is described in the [installation guide](install-guide.md).
```
-Images that are stored in the project can be included into the Markdown
+Images that are stored in the project can be included into the project
documentation, but they are only rendered if the image mimetype is
configured on the Gerrit server as a
[safe mimetype](../../../Documentation/config-gerrit.html#mimetype).
@@ -67,12 +70,13 @@
```
-By default inline HTML blocks as well as inline HTML tags are
-[suppressed](config.html#formatterAllowHtml). If suppressed both will
-be accepted in the input but not be contained in the output.
+By default inline HTML blocks as well as inline HTML tags may be
+[suppressed](config.html#formatterAllowHtml) by formatters. If
+suppressed both will be accepted in the input but not be contained in
+the output.
-Markdown files may include the following macros which are automatically
-replaced when the HTML pages are generated.
+Project documentation files may include the following macros which are
+automatically replaced when the HTML pages are generated.
* `\@URL@`: The web URL of the Gerrit server.
* `\@PROJECT@`: The name of the project from which the documentation is shown.
@@ -81,3 +85,8 @@
* `\@GIT_DESCRIPTION@`: The output of `git describe` on the revision
from which the documentation is shown, or the abbreviated ID of the
revision if no names are found.
+
+The plugin provides several [formatters](about.html#formatters) for
+different project documentation syntaxes. The formatters can be
+[configured](config.html#projectConfig) on project level and for some
+formatters the CSS can be [customized](config.html#projectCss).
