Updating documentation

[wren ng thornton]

On 11/8/10 5:41 AM, Johan Tibell wrote:
> On Mon, Nov 8, 2010 at 12:36 PM, Sittampalam, Ganesh wrote:
>>
>> That feels to me like a rule that would be better applied by the
>> documentation tool, than by the individual writing the documentation.
>> Especially as the syntax is more lightweight than in Java, it's so much
>> easier to just automatically do it for everything than to stop and think
>> each time.
>
> In my experience, I don't think there's automatic way to decided where
> to link or not. It's really a judgement call (and I sometimes go back
> and remove or add hyperlinks). Sometimes I don't hyperlink an
> identifier even the first time it's mentioned, for example because it
> was hyperlinked in the introduction.

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).

Another benefit is that there is often debate about stylistic 
differences like this, and so it makes sense not to hardcode that into 
the documentation itself, but rather to let you change the style easily 
by altering the flags you pass to haddock. When LaTeXing I do this sort 
of thing often, by using semantically oriented macros whose definition 
can be easily swapped out in header files according to the whims of 
different journals. One of the main problems of JavaDoc, IMO, is the 
focus on an operational kind of markup instead of a semantic markup that 
actually captures what you mean.

Assuming I've read Ganesh Sittampalam's suggestion accurately, I'm all 
for this. I may even have some time to offer once classes are out.

-- 
Live well,
~wren