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

diff --git a/share/man/nitdoc.md b/share/man/nitdoc.md
index d39c076..af3d95c 100644
--- a/share/man/nitdoc.md
+++ b/share/man/nitdoc.md
@@ -2,91 +2,88 @@
 
 # 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.
 
-`-W`, `--warn`
-:   Show more warnings
+The documentation is extracted from the comments found above the definition of modules, classes, and properties.
 
-`-w`, `--warning`
-:   Show/hide a specific warning
+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`.
 
-`-q`, `--quiet`
-:   Do not show warnings
+The documentation of the Nit [standard library] is generated with this tool.
 
-`--stop-on-first-error`
-:   Stop on first error
+  [graphviz]: http://www.graphviz.org
+  [standard library]: http://nitlanguage.org/doc/stdlib
 
-`--no-color`
-:   Do not use color to display errors and warnings
+# DOCUMENTATION FORMAT
 
-`--log`
-:   Generate various log files
+The format of the documentation is a dialect of [markdown] that allows GitHub fences (`~~~`).
 
-`--log-dir`
-:   Directory where to generate log files
+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 niunit(1) for details.
 
-`-h`, `-?`, `--help`
-:   Show Help (This screen)
+  [markdown]: http://daringfireball.net/projects/markdown
 
-`--version`
-:   Show version and exit
+# OPTIONS
 
-`--set-dummy-tool`
-:   Set toolname and version to DUMMY. Useful for testing
+`-d`, `--dir`
+:   output directory.
 
-`-v`, `--verbose`
-:   Verbose
+    Where the HTML files are generated.
 
-`--bash-completion`
-:   Generate bash_completion file for this program
+    By default, the directory is named `doc`.
 
-`--stub-man`
-:   Generate a stub manpage in pandoc markdown format
+`--source`
+:   Format to link source code.
 
-`--disable-phase`
-:   DEBUG: Disable a specific phase; use `list` to get the list.
+    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.
 
-`-I`, `--path`
-:   Set include path for loaders (may be used more than once)
+    For instance, the [standard library] use the following value to link to files in GitHub:
 
-`--only-parse`
-:   Only proceed to parse step of loaders
+        "https://github.com/privat/nit/blob/$(git rev-parse HEAD)/%f#L%l-%L"
 
-`--only-metamodel`
-:   Stop after meta-model processing
+    Here, the `git rev-parse HEAD` is used to link to the current snapshot revision of the file.
 
-`--ignore-visibility`
-:   Do not check, and produce errors, on visibility issues.
+`--no-attribute`
+:   Ignore the attributes.
 
-`-d`, `--dir`
-:   output directory
+    Note: In Nit, attributes are private. Therefore, this option is only useful
+    when combined with `--private`.
 
-`--source`
-:   link for source (%f for filename, %l for first line, %L for last line)
+`--no-dot`
+:   do not generate graphs with graphviz.
+
+`--private`
+:   also generate private API.
+
+## CUSTOMIZATION
 
 `--sharedir`
-:   directory containing nitdoc assets
+:   directory containing nitdoc assets.
 
-`--shareurl`
-:   use shareurl instead of copy shared files
+    By default `$NIT_DIR/share/nitdoc/` is used.
 
-`--no-dot`
-:   do not generate graphes with graphviz
+`--shareurl`
+:   use shareurl instead of copy shared files.
 
-`--private`
-:   also generate private API
+    By default, assets from the sharedir a copied into the output directory and refered with a relative path in the generated files.
+    Whith this option, the assets are not copied and the given URL of path is used in the generated files to locate assets.
 
 `--custom-title`
-:   custom title for homepage
+:   custom title for homepage.
 
 `--custom-footer-text`
-:   custom footer text
+:   custom footer text.
 
 `--custom-overview-text`
 :   custom intro text for homepage
@@ -94,6 +91,8 @@ nitdoc [*options*]...
 `--custom-brand`
 :   custom link to external site
 
+## SERVICES
+
 `--github-upstream`
 :   Git branch where edited commits will be pulled into (ex: user:repo:branch)
 
@@ -104,7 +103,7 @@ nitdoc [*options*]...
 :   Git working directory used to resolve path name (ex: /home/me/myproject/)
 
 `--piwik-tracker`
-:   Piwik tracker URL (ex: nitlanguage.org/piwik/)
+:   Piwik tracker URL (ex: `"nitlanguage.org/piwik/"`)
 
 `--piwik-site-id`
 :   Piwik site ID