From d42b5af1f19d118931384ca78fd36067538da78f Mon Sep 17 00:00:00 2001 From: krasimir Date: Sat, 31 Jul 2004 21:17:51 +0000 Subject: [haddock @ 2004-07-31 21:17:51 by krasimir] Document new features in HtmlHelp --- doc/haddock.sgml | 117 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 72 insertions(+), 45 deletions(-) diff --git a/doc/haddock.sgml b/doc/haddock.sgml index 06386dfb..3d355d9b 100644 --- a/doc/haddock.sgml +++ b/doc/haddock.sgml @@ -21,7 +21,7 @@ - + Introduction @@ -99,7 +99,7 @@
Obtaining Haddock - + Distributions (source & binary) of Haddock can be obtained from its web site. @@ -162,7 +162,7 @@
Acknowledgements - + Several documentation systems provided the inspiration for Haddock, most notably: @@ -223,7 +223,7 @@ indentifiers it couldn't resolve. The modules should not be mutually - recursive, as Haddock don't like swimming in circles. + recursive, as Haddock don't like swimming in circles. The following options are available: @@ -368,29 +368,56 @@ - - - + + (In HTML mode only) Produce extra contents and index - files for the Microsoft HTML Help system. The files created - will be named index.hhc and - index.hhk respectively. + files for given HTML Help system. Currently supported Help + systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp. Using the Microsoft HTML Help system provides two advantages over plain HTML: the help viewer gives you a nice hierarchical folding contents pane on the left, and the documentation files are compressed and therefore much - smaller (roughly a factor of 10). The disadvantages are - that the viewer is only available on Windows, and the help - can't be viewed over the web. + smaller (roughly a factor of 10). The disadvantage is that + the help can't be viewed over the web. In order to create a compiled Microsoft help file, you also need the Microsoft HTML Help compiler, which is - available free from http://www.microsoft.com/ + available free from + http://www.microsoft.com/ (search for HTML Help compiler). + + Viewers + + + Microsoft HTML Help Viewer + Distributed with Microsoft Windows + + + xCHM + a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru + + + JouleData Solutions' CHM Viewer + a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform + + + GnoCHM + a CHM file viewer. It is designed to integrate nicely with Gnome. + + + + The GNOME DevHelp also provides help viewer which looks like + MSHelp viewer but the documentation files aren't compressed. + The documentation can be viewed with any HTML browser but + DevHelp gives you a nice hierarchical folding contents and + keyword index panes on the left. The DevHelp expects to see + *.devhelp file in the folder where the documentation is placed. + The file contains all required information + to build the contents and index panes. + @@ -574,7 +601,7 @@ $ haddock -h Foo.hs ...
- + Documentation and Markup @@ -640,7 +667,7 @@ square x = x * x Some people like to write their documentation after the declaration; this is possible in Haddock too: - + square :: Int -> Int -- ^The 'square' function squares an integer. @@ -651,7 +678,7 @@ square x = x * x — if you don't write the type signature for a function, then Haddock can't tell what its type is and it won't be included in the documentation. - + Documentation annotations may span several lines; the annotation continues until the first non-comment line in the source file. For example: @@ -675,24 +702,24 @@ square x = x * x square :: Int -> Int square x = x * x - +
Documenting parts of a declaration - + In addition to documenting the whole declaration, in some cases we can also document individual parts of the declaration.
Class methods - + Class methods are documented in the same way as top level type signatures, by using either the -- | or -- ^ annotations: - + class C a where -- | This is the documentation for the 'f' method @@ -710,9 +737,9 @@ class C a where data T a b -- | This is the documentation for the 'C1' constructor - = C1 a b + = C1 a b -- | This is the documentation for the 'C2' constructor - | C2 a b + | C2 a b or like this: @@ -727,14 +754,14 @@ data T a b styles: -data R a b = +data R a b = C { -- | This is the documentation for the 'a' field a :: a, -- | This is the documentation for the 'b' field b :: b } -data R a b = +data R a b = C { a :: a -- ^ This is the documentation for the 'a' field , b :: b -- ^ This is the documentation for the 'b' field } @@ -748,7 +775,7 @@ data R a b =
Function arguments - + Individual arguments to a function may be documented like this: @@ -775,10 +802,10 @@ module Foo where ...
- +
Controlling the documentation structure - + Haddock produces interface documentation that lists only the entities actually exported by the module. The documentation for a module will include all entities @@ -849,7 +876,7 @@ module Foo (
Re-exporting an entire module - + Haskell allows you to re-export the entire contents of a module (or at least, everything currently in scope that was imported from a given module) by listing it in the export @@ -859,7 +886,7 @@ module Foo ( module A ( module B, module C - ) where + ) where What will the Haddock-generated documentation for this @@ -876,7 +903,7 @@ module A ( module A ( module B, module C - ) where + ) where import B hiding (f) import C (a, b) @@ -896,10 +923,10 @@ import C (a, b) is never cross-referenced; the contents are always expanded in place in the re-exporting module.
- +
Omitting the export list - + If there is no export list in the module, how does Haddock generate documentation? Well, when the export list is omitted, e.g.: @@ -937,7 +964,7 @@ module Foo ( ) where - + If the documentation is large and placing it inline in the export list might bloat the export list and obscure the @@ -954,7 +981,7 @@ module Foo ( ... ) where --- $doc +-- $doc -- Here is a large chunk of documentation which may be referred to by -- the name $doc. @@ -968,8 +995,8 @@ module Foo (
- Hyperlinking and re-exported entities - + Hyperlinking and re-exported entities + When Haddock renders a type in the generated documentation, it hyperlinks all the type constructors and class names in that type to their respective definitions. But for a @@ -1038,7 +1065,7 @@ import B
Module Attributes - + Certain attributes may be specified for each module which affects the way that Haddock generates documentation for that module. Attributes are specified in a comma-separated list in a @@ -1068,7 +1095,7 @@ module A where definitions. - + prune hide @@ -1077,7 +1104,7 @@ module A where annotations from the generated documentation. - + ignore-exports hide @@ -1103,7 +1130,7 @@ module A where
Paragraphs - + One or more blank lines separates two paragraphs in a documentation comment.
@@ -1263,7 +1290,7 @@ module A where
Definition lists - + Definition lists are written as follows: @@ -1275,7 +1302,7 @@ module A where To produce output something like this: - + foo @@ -1322,7 +1349,7 @@ module A where #label#, where label is the name of the anchor. An anchor is invisible in the generated documentation. - + To link to an anchor from elsewhere, use the syntax "module#label" where module is the module name -- cgit v1.2.3