Updating documentation

Ross Paterson ross at soi.city.ac.uk
Tue Nov 9 04:19:49 EST 2010


On Mon, Nov 08, 2010 at 11:16:59PM -0500, wren ng thornton wrote:
> I believe the suggestion was not to add hyperlinks automatically,
> but rather to *remove* them automatically. For example, with such
> automation I can just write 'Int', 'Foo', or 'Local.Bar' everywhere
> and leave it up to Haddock to ensure properties like only the first
> one actually being a link.
> 
> One reason this would be beneficial is that it means we wouldn't
> have to stop and think about whether a given identifier has already
> been linked for this page, let alone maintain the firstness quality
> when we decide to rearrange the order in which things occur.
> Automating things like firstness is the only reliable way to be
> consistent about it, just like when giving citations in papers
> (e.g., many LaTeX packages will Do The Right Thing).

And because haddock moves documentation between modules, it's often
impossible to distinguish in the source which is the first use of a
name in the modules in which it's used.


More information about the Libraries mailing list