root/docs/haddock_tips

This is a Quick Reference for 


Haddock is the POD of Haskell, it's used in the Pugs source to
document the Haskell code.  "make haskell" generates cross-linked
html documentation in the ./dist/doc/html directory.
Haddock is also able to extract type, function and module information 
automatically.

Haddock's homepage is:

  http://www.haskell.org/haddock/
  http://cvs.haskell.org/darcs/haddock/examples/

An online copy of Pugs haddock output is available at:

  http://nothingmuch.woobling.org/pugs_test_status/haddock/

This document is intended to aid Pugs documentation and code contributors
who want to get started with a minimum of effort.
This file is just plain text to avoid requiring any kind of escaping.
Scan this file for "===" to see the topics covers

POD <=> Haddock Phrase Book
===========================
POD                         Haddock
Paragraph \n\n+ separated   Paragraph also \n\n+ separated
E<gt>,E<sol>                \>,\/   use \ to escape /, ', `, ", @, <
                                    or *, - a the start of a line
  verbatim paragraph        > verbatim paragraph 
L<Perl::Module::function>   'Haskell.Module.function'  hyperlinks (or `T')
                            Strings in '' which aren't identifiers are ignored
L<url>                      <url>
L<Module>                   "Module"
L<Module/Section>           'Module#Section'
X<SectionAnchor>            #SectionAnchor# a non-rendered target for '#sec'
C<monospaced code>          @monospaced code@
B<emphasis>                 /emphasis/
=head1                      -- *
=head2                      -- **
=head3                      -- ***
=over, =back                Nothing
=item *                     * or - at start of paragraph
=item 1.                    (1) or 1. at start of paragraph
=item name                  [@name@] at start of paragraph

--| Documentation for the next thing (top level or in declarations)
{-| Multiline version of above -}

--^ Documentation for the previous thing (top level or in declarations)
{-^ Multiline version of above -}


Documentation Build Process
===========================

make haddock

This produces the cross-linked html documentation for Pugs in the
./dist/doc/html directory.  If any of the input .hs files is causes
haddock to fail then the haddock-broken make target can be used to produce
documentation for one file at a time.  This is inferior to make haddock
as the identifier links aren't correctly produced.

Internally, make haddock first filters the .hs files to remove
problematic constructs.  The haddock program can be confused by some
GHC extensions and the util/munge_haddock.pl attempts to avoid this.

Note that Haddock only builds documentation for the interface of
modules, so the documentation for internal methods may not appear 
in the output.  The --# ignore-exports (or {-# ignore-exports}) option
can appear for the module definition to override this.

Understanding and Correcting Errors
===================================

If make haddock fails then you can use make haddock-broken to produce
inferior documentation.  There are a few strategies available to fix 
the file which breaks haddock.  Note that the location of the error
messages are not always helpful, for example, a "string" pages above
can cause an error at the first line of code below it.

As haddock ignore plain {-  -} comments, you can just change the "{-|"
to test whether a particular comment block is causing the problem.

Once the block has been found, it can be split with "-}{-" to binary
search for the problem.  Turning a paragraph into a verbatim block
with s/^/> / can also isolate the trouble.  Individual files can
be run with haddock $filename.

Common problems:
 - @Larry unescaped @ characters 
 - "double-quoted strings" which are not links to modules  
 - -- | ControlEnv !Env, misinterpreted commenting out (-- \| instead)

To fix problems you can escape with \, rephrase or use a non-haddock 
comment block.

If the code is the source of the problem then the following #ifdefs
can be used to remove the code before haddock sees it.  This is done
in munge_haddock.pl

#ifndef HADDOCK
#endif HADDOCK

Haddock Vim Syntax File
=================

Ask bsb on #perl6 if you want to take it for a spin