johan.tibell:

On Sun, Nov 7, 2010 at 5:57 PM, Don Stewart wrote:

...

Hey all,

I'm walking over the libraries@ maintained packages, updating documentation, according to a style guide I'm developing. You should see new releases of libraries@ packages with documentation-only changes in coming days and weeks.

Thanks!

Out of curiosity. Is that style guide based on some existing style guide (Haskell or otherwise)?

At the moment I'm writing a new one, from what I recall of a Python style guide I haven't been able to find.

Johan Tibell wrote:

Like the Javadoc guide, I would encourage people documenting Haskell libraries to not hyperlink too much. Only hyperlink identifier if you think the reader might want to click on the link for some reason. For example, only hyperlink an identifier the first time it's mention in a piece of documentation. Avoid hyperlinking standard, well-know identifiers such as Int or String.

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. Ganesh =============================================================================== Please access the attached hyperlink for an important electronic communications disclaimer: http://www.credit-suisse.com/legal/en/disclaimer_email_ib.html ===============================================================================

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

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.

On Mon, Nov 8, 2010 at 12:57 PM, Roman Leshchinskiy wrote:

Why? I always try to hyperlink identifiers.

Hyperlinking something draws the users attention. Hyperlinking everything is almost the same as making e.g. every 5th word bold.

This provides some syntax highlighting in the comments which I find very useful. Besides, making the reader search for the first occurence of an identifier doesn't sound like a good idea to me. Documentation is rarely read linearly.

You can use @id@ to make the identifier monospaced. It makes it clear that's it's an identifier without the visual weight of a link. By first occurrence I mean first occurrence in some context. Perhaps the context is the documentation of a function. Use your judgement. You're right that documentation is often not read linearly. That applies to Javadoc as well and it's there they established this guideline. Johan

Hi Roman, On Mon, Nov 8, 2010 at 2:30 PM, Roman Leshchinskiy wrote:

I would argue that documentation where every 5th word is an identifier is rather broken.

But it's not that uncommon in Haskell documentation, the main reason is probably that since the parameter names don't appear in the documentation, people refer to the arguments by type. For an example of excessive hyperlinking see: http://hackage.haskell.org/packages/archive/bytestring/0.9.1.7/doc/html/Data... "O(n) The 'intercalate' function takes a 'ByteString' and a list of 'ByteString's and concatenates the list after interspersing the first argument between each element of the list." - The documentation links to it's own definition - The documentation links to ByteString twice. In fact, the whole library links to the ByteString hundreds of times, even though people are highly unlikely to click on these links.

...

You can use @id@ to make the identifier monospaced. It makes it clear that's it's an identifier without the visual weight of a link.

Personally, I don't find hyperlinked identifiers to add any weight compared to monospaced ones. If anything, they are easier to read for me.

We can change the style of the @id@ markup, it's orthogonal to the hyperlinking issue. I personally like the style use in http://code.google.com/appengine/docs/python/datastore/modelclass.html where identifier are monospace but appear in a color that makes them stand out a little bit more.

I don't find their style especially enticing. In particular, they underline their hyperlinks which explains why they try to avoid them as much as possible.

Although that's not the rationale they give for not doing so. Johan

We can change the style of the @id@ markup, it's orthogonal to the hyperlinking issue. I personally like the style use in http://code.google.com/appengine/docs/python/datastore/modelclass.html where identifier are monospace but appear in a color that makes them stand out a little bit more.   I found on that page, because the green monospaced font makes certain identifiers stand out within the middle of a line of ordinary black text, I expected them to be hyperlinked, and was surprised that they are not.  Indeed, the highlighted identifiers (type names, attribute names, etc), would be exactly the kind of thing I would want to lookup in order to fully understand the documentation. Regards,     Malcolm

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 11/8/10 06:56 , Johan Tibell wrote:

On Mon, Nov 8, 2010 at 12:57 PM, Roman Leshchinskiy wrote:

...

Why? I always try to hyperlink identifiers.

Hyperlinking something draws the users attention. Hyperlinking everything is almost the same as making e.g. every 5th word bold.

You're doing it wrong. Hover links (done with CSS) work nicely for this. - -- brandon s. allbery [linux,solaris,freebsd,perl] allbery@kf8nh.com system administrator [openafs,heimdal,too many hats] allbery@ece.cmu.edu electrical and computer engineering, carnegie mellon university KF8NH -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.10 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAkzfBGgACgkQIn7hlCsL25VuuQCfWhhwlAmdgOVEp1akem7j9+dS CHsAn0Jfg9eCFq7gVjpmnMBv7Dk9Mbhv =pAEM -----END PGP SIGNATURE-----