[xmonad] Re: Contrib Documentation (was Webpage information and a (practical) tour of the Xmonad Contrib)

[wirtwolff]

Roman Cheplyaka wrote:
> * Ismael Carnales <icarnales at gmail.com> [2009-01-26 06:58:26-0200]
>  
>> Secondly I'm starting a doc that pretends to be a guided tour
>> lookalike of some of the XMonad Contrib, I'm starting this mainly
>> because I think it's very difficult for newcomers to discover what
>> extra features XMonad provides. Haddock documentation is pretty useful
>> when you know what you are looking for, but when you're looking around
>> to find if some feature is implemented already, the way that the
>> documentation is indexed (by alphabetical order) doesn't help much.
>>
>> The in progress document is located here
>> http://haskell.org/haskellwiki/XMonadContribTour and all are welcomed
>> to contribute/comment/correct/etc.
>>     
>
> Great idea, but I'm not sure about the style.
> Why not just give list of modules and problems, which they solve? It
> would be much easier to update when new modules are released.
> OTOH what you're doing is more like Tips and tricks, why not to add it
> to apropriate page [1]?
>
>   1. http://haskell.org/haskellwiki/Xmonad/General_xmonad.hs_config_tips
>   

In this vein, we also have XMonad.Doc.Extending which is a bit of a pain
to keep updated. It might be nice to script generating its content from
the contrib modules' initial description comments. This would make it
more wordy, but possibly the automation of maintenance and extra
information would be worth it.

For example, for Actions.CopyWindow, the following would be generated:

* "XMonad.Actions.CopyWindow":  Allows you to run internal xmonad
commands (X () actions) using a dmenu menu in addition to key bindings.
Requires dmenu and the Dmenu XMonad.Actions module.

Some module comments are much longer, so the script could use only the
first paragraph rather than the whole module description. If I ever get
around to trying it, will post examples for feedback before creating a 
patch.

-- wmw