From 2d3a4b0c42ef8afa30ceab082078e79674772ad7 Mon Sep 17 00:00:00 2001 From: Duncan Coutts Date: Mon, 23 Jan 2006 14:12:16 +0000 Subject: Add documentation for the new --source-* and --comments-* command line options --- doc/haddock.xml | 134 +++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 118 insertions(+), 16 deletions(-) (limited to 'doc/haddock.xml') diff --git a/doc/haddock.xml b/doc/haddock.xml index ca49bf38..41e0cb9b 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -16,7 +16,7 @@ Simon Marlow - This document describes Haddock version 0.6, a Haskell + This document describes Haddock version 0.8, a Haskell documentation tool. @@ -467,34 +467,136 @@ - - URL + + =URL - - =URL + + =URL + + + + =URL Include links to the source files in the generated - documentation, where URL is the - base URL where the source files can be found. The following - substitutions are made within the string - URL: + documentation. Use the option to add a + source code link in the header bar of the contents and index pages. + Use the to add a source code link in + the header bar of each module page. Use the + option to add a source code link + next to the documentation for every value and type in each module. + + + In each case URL is the base URL + where the source files can be found. For the per-module and + per-entity URLs, the following substitutions are made within the + string URL: - The string %M is replaced by the module name - (with ‘.’ replaced by ‘/’). + The string %M or %{MODULE} + is replaced by the module name. Note that for the per-entity URLs + this is the name of the exporting module. - The string %F is replaced by the - source file name. + The string %F or %{FILE} + is replaced by the original source file name. Note that for the + per-entity URLs this is the name of the defining + module. + + + The string %N or %{NAME} + is replaced by the name of the exported value or type. This is + only valid for the option. + + + The string %K or %{KIND} + is replaced by a flag indicating whether the exported name is a value + 'v' or a type 't'. This is + only valid for the option. - For example, if your sources are online in a single directory, - you would say haddock -s - url/%F. + For example, if your sources are online under some directory, + you would say + haddock --source-base=url/ + --source-module=url/%F + + If you have html versions of your sources online with anchors + for each type and function name, you would say + haddock --source-base=url/ + --source-module=url/%M.html + --source-entity=url/%M.html#%N + + For the %{MODULE} substitution you may want to + replace the '.' character in the module names with + some other character (some web servers are known to get confused by + multiple '.' characters in a file name). To + replace it with a character c use + %{MODULE/./c}. + + + + + + + + URL + + + + =URL + + + Deprecated aliases for + + + + + + + =URL + + + + =URL + + + + =URL + + + Include links to pages where readers may comment on the + documentation. This feature would typically be used in conjunction + with a Wiki system. + + Use the option to add a + user comments link in the header bar of the contents and index pages. + Use the to add a user comments + link in the header bar of each module page. Use the + option to add a comments link + next to the documentation for every value and type in each module. + + + In each case URL is the base URL + where the corresponding comments page can be found. For the + per-module and per-entity URLs the same substitutions are made as + with the and + options above. + + For example, if you want to link the contents page to a wiki + page, and every module to subpages, you would say + haddock --comments-base=url + --comments-module=url/%M + + If your Wiki system doesn't like the '.' + character in Haskell module names, you can replace it with a + different character. For example to replace the + '.' characters with '_' use + haddock --comments-base=url + --comments-module=url/%{MODULE/./_} + -- cgit v1.2.3