X-Git-Url: http://nitlanguage.org

diff --git a/share/man/nitdoc.md b/share/man/nitdoc.md
index d39c076..0b42d2f 100644
--- a/share/man/nitdoc.md
+++ b/share/man/nitdoc.md
@@ -1,113 +1,118 @@
-% NITDOC(1)
-
 # NAME
 
-Generates HTML pages of API documentation from Nit source files.
+nitdoc - generates HTML pages of API documentation from Nit source files.
 
-# SYNOPSYS
+# SYNOPSIS
 
-nitdoc [*options*]...
+nitdoc [*options*]... FILE...
 
-# OPTIONS
+# DESCRIPTION
+
+`nitdoc` takes one or more modules and generate HTML pages of API documentation for these modules and their imported modules.
+
+The documentation is extracted from the comments found above the definition of modules, classes, and properties.
+
+Internally, `nitdoc` relies on the presence of the `dot` command from the [graphviz] project.
+If the dot program is not present or not found, no image of hierarchies are generated.
+See option `--no-dot`.
 
-`-W`, `--warn`
-:   Show more warnings
+The documentation of the Nit [standard library] is generated with this tool.
 
-`-w`, `--warning`
-:   Show/hide a specific warning
+  [graphviz]: http://www.graphviz.org
+  [standard library]: http://nitlanguage.org/doc/stdlib
 
-`-q`, `--quiet`
-:   Do not show warnings
+# DOCUMENTATION FORMAT
+
+The format of the documentation is a dialect of [markdown] that allows GitHub fences (`~~~`).
+
+Code blocks are interpreted as snippets of Nit programs and intended to be used as examples of code.
+When these code snippets are valid, executable and contain at least and `assert` clause, they could be automatically executed and verified.
+See `nitunit(1)` for details.
+
+  [markdown]: http://daringfireball.net/projects/markdown
+
+# OPTIONS
 
-`--stop-on-first-error`
-:   Stop on first error
+### `-d`, `--dir`
+Output directory.
 
-`--no-color`
-:   Do not use color to display errors and warnings
+Where the HTML files are generated.
 
-`--log`
-:   Generate various log files
+By default, the directory is named `doc`.
 
-`--log-dir`
-:   Directory where to generate log files
+### `--source`
+Format to link source code.
 
-`-h`, `-?`, `--help`
-:   Show Help (This screen)
+The format string is used to generated links to some parts of the source-code.
+Use `%f` for filename, `%l` for first line, and `%L` for last line.
 
-`--version`
-:   Show version and exit
+For instance, the [standard library] use the following value to link to files in GitHub:
 
-`--set-dummy-tool`
-:   Set toolname and version to DUMMY. Useful for testing
+    "https://github.com/nitlang/nit/blob/$(git rev-parse HEAD)/%f#L%l-%L"
 
-`-v`, `--verbose`
-:   Verbose
+Here, the `git rev-parse HEAD` is used to link to the current snapshot revision of the file.
 
-`--bash-completion`
-:   Generate bash_completion file for this program
+### `--no-attributes`
+Ignore the attributes.
 
-`--stub-man`
-:   Generate a stub manpage in pandoc markdown format
+Note: In Nit, attributes are private. Therefore, this option is only useful
+when combined with `--private`.
 
-`--disable-phase`
-:   DEBUG: Disable a specific phase; use `list` to get the list.
+### `--no-dot`
+Do not generate graphs with graphviz.
 
-`-I`, `--path`
-:   Set include path for loaders (may be used more than once)
+### `--private`
+Also generate private API.
 
-`--only-parse`
-:   Only proceed to parse step of loaders
+## CUSTOMIZATION
 
-`--only-metamodel`
-:   Stop after meta-model processing
+### `--share-dir`
+Directory containing tools assets.
 
-`--ignore-visibility`
-:   Do not check, and produce errors, on visibility issues.
+By default `$NIT_DIR/share/nitdoc/` is used.
 
-`-d`, `--dir`
-:   output directory
+### `--shareurl`
+Use shareurl instead of copy shared files.
 
-`--source`
-:   link for source (%f for filename, %l for first line, %L for last line)
+By default, assets from the sharedir a copied into the output directory and referred with a relative path in the generated files.
+With this option, the assets are not copied and the given URL of path is used in the generated files to locate assets.
 
-`--sharedir`
-:   directory containing nitdoc assets
+### `--custom-title`
+Custom title for homepage.
 
-`--shareurl`
-:   use shareurl instead of copy shared files
+### `--custom-footer-text`
+Custom footer text.
 
-`--no-dot`
-:   do not generate graphes with graphviz
+### `--custom-overview-text`
+Custom intro text for homepage.
 
-`--private`
-:   also generate private API
+### `--custom-brand`
+Custom link to external site.
 
-`--custom-title`
-:   custom title for homepage
+## SERVICES
 
-`--custom-footer-text`
-:   custom footer text
+### `--github-upstream`
+Git branch where edited commits will be pulled into (ex: user:repo:branch).
 
-`--custom-overview-text`
-:   custom intro text for homepage
+### `--github-base-sha1`
+Git sha1 of base commit used to create pull request.
 
-`--custom-brand`
-:   custom link to external site
+### `--github-gitdir`
+Git working directory used to resolve path name (ex: /home/me/myproject/).
 
-`--github-upstream`
-:   Git branch where edited commits will be pulled into (ex: user:repo:branch)
+### `--piwik-tracker`
+Piwik tracker URL (ex: `nitlanguage.org/piwik/`).
 
-`--github-base-sha1`
-:   Git sha1 of base commit used to create pull request
+### `--piwik-site-id`
+Piwik site ID.
 
-`--github-gitdir`
-:   Git working directory used to resolve path name (ex: /home/me/myproject/)
+## TESTING
 
-`--piwik-tracker`
-:   Piwik tracker URL (ex: nitlanguage.org/piwik/)
+### `--test`
+Print test data (metrics and structure).
 
-`--piwik-site-id`
-:   Piwik site ID
+### `--no-render`
+Do not render HTML files.
 
 # SEE ALSO