haskell
Should inline source in haddock files use syntax highlighting?
It was suggested on a reddit UX thread. Interesting question, not sure if I'd want it...
The title of the issue is not a good idea. I frequently use inline code for stuff that is not Haskell.
If anything, we might want to add support for describing which language is used in a code block (and having some flag that, when enabled, packages in some JS library to highlight accordingly).
Also, potentially, e.g. typeclass constraints, instance heads, etc?
I'm not sure what is meant here, but it sounds interesting. Care to elaborate?
What I meant was not just inline code, but the code in haddocks themselves -- type signatures, etc.
Also note that we have a "semi" highlighting that comes from the hyperlinks and i don't know how a typical highlighting lib would interact with that.
Your proposal for code blocks only sounds pretty reasonable.
I think syntax highlighting for example code would be a great idea (trying to figure out if it were possible is how I came upon this ticket).
The title of the issue is not a good idea. I frequently use inline code for stuff that is not Haskell.
I agree that forcing a particular highlight would be bad. I think a correct implementation would have the capability to highlight haskell (or maybe even non-haskell) code, but not necessarily require such highlighting. Something like github's ```<language> syntax highlighting format. (see also: https://help.github.com/articles/creating-and-highlighting-code-blocks/)
I don't know if I already wrote this down into an issue describing the idea, but for code blocks in haddock markup I had planned to do something like
> -- haddock-highlight: c --
>
> size_t mystrlen (const char x[])
> {
> return x ? strlen(x) : 0;
> }
And default to haddock-highlight: plain (i.e. no highlighting at all) and give a way via a {-# HADDOCK_OPTIONS #-} setting to set a default highlighting mode for the current module. (fwiw, one could also default to haddock-highlight: hs by default, at the risk of erring on making an assumption that may be wrong in like 5% of cases)
We need some way to switch on syntax highlighting which gracefully degrades with older Haddock versions, as we don't have a good version feature-gating story for Haddock yet.
Being able to specify the language would be quite nice. With the language specified something like highlightjs could be easily used HTML side at least. OOC if -- haddock-highlight: language-name -- is used in old versions, would it just display this verbatim rather than use highlighting? So no breakages, but noise in output (or folks would employ a a post-processing script so that it is nop).
It would be great to get this! Then code examples on Haddock would be able to get nice syntax highlighting, right? Probably not old ones due to backward compatibility, but at least we would be able to specify the syntax for the new releases, right?
General idea sounds good to me, of by default not having any highlighting, in order to stay backward compatible, but then one could set a default highlighting to be Haskell + one could choose language per code block/snippet that would override the default setting.
What are the needed steps to get this going? I am proficient with Haskell, but have never contributed to Haddock -> is this something a new contributor would be able to tackle? Could you maybe provide some higher-level steps on how to approach this, some pointers on the best way to attack this?
