I was chatting with Roger Evans and Simon Marlow about the difficulty
in finding documentation and prehooks and posthooks.

The problem isn't so much that the documentation isn't there, but that
(1) it's hidden away in a dedicated 'options common to darcs commands'
section and (2) you aren't always aware that an option is common to
darcs commands.

There must be some way to make this easier to find.
Some ways to approach the problem:
- automatically duplicate the documentation in each command
- automatically insert pointers (for documentation on posthooks
  see section foo?)
- think carefully about commands for which the common options
  are particularly relevant and manually insert pointers
- promote each option to a subsection so that it's at least
  visible in the HTML doc table of contents

Another example of this happening:
- people want to find out what the little one-letter codes in darcs whatsnew are.

You can't see them from whatsnew because this is documentation for --summary
which is common to many commands

Pasting in this reply from Simon:
---------
I'm not sure if there is documentation for the environment variables that      
                                         
the prehooks/posthook scripts get passed.  If there is, I didn't find it!      
                                         
                                                                               
                                         
Wherever you document prehook/posthook, it should be linked from the           
                                         
section on _darcs/prefs/defaults.                                              
                                         
                                                                               
                                         
I noticed that the section on _darcs/prefs/sources gives examples but          
                                         
doesn't actually list the kinds of lines that can be in that file.             
                                         
                                                                               
                                         
The documentation for options seems to be misformatted somehow - see           
                                         
                                                                               
                                         
http://darcs.net/manual/node7.html#SECTION00710000000000000000                 
                                         
                                                                               
                                         
Cheers,                                                                        
                                         
        Simon  
--------------

Misformatting now documented on issue1594.
Simon: see http://www.darcs.net/manual/node7.html#SECTION00710000000000000000

I notice that one issue is that the posthook section doesn't have a title, so it
looks like part of the SENDMAIL documentation

Eric Kow wrote:
> Eric Kow <kowey@darcs.net> added the comment:
> 
> Pasting in this reply from Simon:
> ---------
> I'm not sure if there is documentation for the environment variables that      
>                                          
> the prehooks/posthook scripts get passed.  If there is, I didn't find it!      

It is bundled with the rest of the Environment Variables documentation. 
I agree that it should be cross-linked from the mention of the 
appropriate prehook/posthook command options (which in turn should be 
cross-linked with _darcs/prefs/*).