[xmonad] help needed in the documentation effort

[Andrea Rossato]

Hi,

I've just pushed a patch that adds a module, called Documentation,
that will allows us to use Haddock commands to produce a hyperlinked
documentation of the xmonad-contrib library.

Here's the documentation produced with the HEAD tree:
http://gorgias.mine.nu/xmonad/xmonad-contrib/

and this is the specific module I'm talking about:
http://gorgias.mine.nu/xmonad/xmonad-contrib/Documentation.html

As you may see it is just a draft. There's the basic structure, but
you can take it as a proposal. Please send you suggestions, comments,
and patches!!

I'm asking for help, especially from our users who are not really
familiar with Haskell, or with the XMonad code base: helping in
documenting it can be a quite useful learning experience (I know it
because that's my experience too!). Moreover non expert can provide
hints on what must be stressed most, especially for non experienced
users.

In order to help you need:

1. haddock[1] and the haddock documentation[2]

2. darcs to record and send patches (I'm sure you already have darcs
   installed!)

3. if you want to build the core (xmonad) documentation you need to
   build haddock with the attached patch, since by default it doesn't
   handle some of the newtype deriving used in XMonad.Core

That's it.

I'll try to keep the above link as updated as I can.

Thanks for your kind attention. And for the forthcoming help!
;)

Andrea

[1] http://haskell.org/haddock/

[2] http://haskell.org/haddock/haddock-html-0.8/index.html
-------------- next part --------------

New patches:

[work around to parse "deriving" from parameterized types
Andrea Rossato <andrea.rossato at unibz.it>**20070610164400
 
   This is just a work around that will push the paramater (the type) as a
   class in the class list. I did a quick hack to parse XMonad source
   code...;-)
 
] {
hunk ./src/HsParser.ly 547
->	: dclasses ',' qtycls		{ $3 : $1 }
+>	: dclasses qtycls		{ $2 : $1 }
+>	| dclasses ',' qtycls		{ $3 : $1 }
}

Context:

[bug fix
Wolfgang Jeltsch <g9ks157k at acme.softbase.org>**20070419182340
 When Haddock was invoked with the --ignore-all-exports flag but the ignore-exports module attribute wasn't used, hyperlinks weren't created for non-exported names.
 
 This fix might not be as clean as one would wish (since --ignore-all-exports now results in ignore_all_exports = True *and* an additional OptIgnoreExports option for every module) but at least the bug seems to be resolved now.
] 
[URL expansion for %%, %L, %{LINE}
Roberto Zunino <zunrob at users.sf.net>**20070421023643] 
[Add a flag --allow-missing-html
Ian Lynagh <igloo at earth.li>**20070307145955
 With this flag, haddock ignores whether or not the HTML directory of
 packages depended upon exists. We need this when haddocking groups of
 packages that aren't installed yet.
] 
[Add a --ghc-pkg flag
Ian Lynagh <igloo at earth.li>**20070307144253] 
[added substitution %{FILE///c}
Conal Elliott <conal at conal.net>**20070214215400] 
[Do not create empty tables for data declarations which don't have any constructors, instances or comments. Gets better HTML 4.01 compliance
Neil Mitchell**20070206174912] 
[infix type op precedence tweak, ppHsNameAsVar 
Conal Elliott <conal at conal.net>**20070115171157] 
[tweaked tyvarop precedence
Conal Elliott <conal at conal.net>**20070110002300] 
[added infix type operators
Conal Elliott <conal at conal.net>**20070105172038] 
[Make the search box in a form so that enter does the default search
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070112125817] 
[Make the max number of results 75 instead of 50, to allow map searching in the base library to work
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070112122501] 
[Rewrite much of the index searching code, previously was too slow to execute on the base library with IE, the new version guarantees less than O(log n) operations be performed, where n is the number in the list (before was always O(n))
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070112121746] 
[Make the index be in case-insensitive alphabetic order
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111185143] 
[Change from tabs to spaces in the ppHtmlIndex function
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111182244] 
[Delete more stuff that is no longer required
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111182119] 
[Delete dead code, now there is only one index page
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111181746] 
[Add searching on the index page
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111170709] 
[Never do spliting index files into many
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111154115] 
[add test for blank lines inside @...@ code block
Simon Marlow <simonmar at microsoft.com>**20070109131444] 
[allow blank lines inside a @...@ code block
Simon Marlow <simonmar at microsoft.com>**20070109131434] 
[Fix up a case of extra vertical space after a code block
Simon Marlow <simonmar at microsoft.com>**20070105111341
 
 
] 
[TODO: do something better about re-exported symbols from another package
Simon Marlow <simonmar at microsoft.com>**20061215155200] 
[fix <<URL>> image markup
Simon Marlow <simonmar at microsoft.com>**20061208100637] 
[add todo item for --maintainer
Simon Marlow <simonmar at microsoft.com>**20061206160507] 
[fix --use-package error message
Simon Marlow <simonmar at microsoft.com>**20061013105135] 
[Cabal's sdist does not generate "-src.tar.gz" files, but ".tar.gz" ones
sven.panne at aedion.de**20061012152823] 
[Rename haddock.js to haddock-util.js
Simon Marlow <simonmar at microsoft.com>**20061011141737
 haddock.js will be run automatically by Windows when you type
 'haddock' if it is found on the PATH, so rename to avoid confusion.
 Spotted by Adrian Hey.
] 
[TAG 0.8 release
Simon Marlow <simonmar at microsoft.com>**20061010122403] 
Patch bundle hash:
045baf02257bddb4b1ea3e6bdc44dd71895d21e0