Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
I think this thread has went to became a quest for One True Markup Language... I would like to propose a different approach: while we are at extending Haddock why not make it possible to choose from a set of different documentation plugins? Something that works akin to the type: Text - Environment - Documentation, where Documentation is Haddock AST (possibly extended)? That would make most people happy and put the source code writer in power: they could choose the syntax they would like to write their docs. Whether it is Haddock markup, Github Markdown, RST or OneTrueMarkup (c) (r) (patented). The task of defining such an API could be actually harder than writing support for any particular syntax but I think it is more beneficiary in the long run. *Bonus points:* provide the integration with .cabal files so that each package can inform which plugins it expects. *Extra bonus points:* let the plugin be simply the name of a function (or datatype that implements a typeclass) which in turn would be taken from a well-defined scope. (think: library that can provide its own plugin for documenting itself). Best regards, Krzysztof Skrzętnicki On Fri, Apr 5, 2013 at 4:24 AM, Richard A. O'Keefe o...@cs.otago.ac.nzwrote: On 5/04/2013, at 2:00 PM, Johan Tibell wrote: Would it be too much to ask that a notation be used which has a formal syntax and a formal semantics? We will document our superset, sure. That's what others did as well. The point is using Markdown as the shared base. Nononono. Sure, the others documented their supersets. But they did *NOT* provide what I am asking for: - a FORMAL SYNTAX and - a FORMAL SEMANTICS. I tried to use one of these systems, and found myself unable to determine which combinations of features were legal and what legal combinations of features *meant*. I corresponded with some people who had built markdown parsers, and the answer was the same each time: they had reversed engineered some other parser (typically a Perl one) and bashed on it until they were bug-compatible. If I want to get a particular effect in LaTeX or even in HTML+CSS, I can usually figure it out *without* having to run any program. If I want to get a particular effect in Markdown, I flounder around and end up doing without. I am sick of documentation that vaguely hints at things, and I am especially sick of Markdown so-called documentation. To say it one more time: I was unable to use the official Markdown documentation, http://daringfireball.net/projects/markdown/syntax, to guide the construction of a parser. For example, br is a valid URL enclosed in . . ., so is it a link, as the Automatic Links section would suggest, or is it embedded HTML, as the Inline HTML section would suggest? Can you tell *from the documentation*? For another example, is *foo**bar**ugh* supposed to map to emfoostrongbar/strongugh/em or to emfoo/emembar/ememugh/em? Again, I'm not asking what does this or that *program* do, I'm asking can you tell from the documentation what they *ought* to do? If there is an unambiguous specification of Markdown somewhere (specification; not program), I would be glad to see it. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
On 4 Apr 2013, at 22:53, Aleksey Khudyakov wrote:
If we are going to change haddock syntax we should add ability to add
math formulae to documentation. It's not currently possible and it makes
documenting numeric code properly difficult.
How about support for .lhs files?
- both those with bird-tracks (which I don't use anymore)
and \begin{code}...\end{code} (which I do use).
My .lhs files are also LaTeX sources - I guess some way to nicely integrate
haddock markup/down/whatever with LaTeX stuff would be needed
+1 in any case
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204
Lero@TCD, Head of Foundations Methods Research Group
Director of Teaching and Learning - Undergraduate,
School of Computer Science and Statistics,
Room G.39, O'Reilly Institute, Trinity College, University of Dublin
http://www.scss.tcd.ie/Andrew.Butterfield/
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haskell is a declarative language? Let's see how easy it is to declare types of things.
On Thu, Apr 04, 2013 at 06:29:51PM -0400, Albert Y. C. Lai wrote: You may think you know what's wrong, but you don't actually know until you know how to clarify to the beginners. Note: harping on the word any does not clarify, for the beginners exactly say this: Yeah, t can be *any* type, therefore *I* am making it Char. Isn't that what *any* means? The same reasoning happens in highschool and college math classes: Teacher: prove (t+2)^2 = t^2 + 4t + 4 Student: plug t=0. 2 = 2. works. Teacher: that's wrong, blah blah *any* blah blah Student: Yeah, t can be *any* number, therefore *I* am making it 0. Isn't that what *any* means? any is very ambiguous. Doesn't the problem go away if you replace it with all? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Error when building executable with profiling enabled
Hello, i have an executable where i want to run profiling on. I do: ghc --make -prof -auto-all -fth Custom.hs but it does not built and the output is: bench\HLogo\Custom\Custom.hs:1:1: Dynamic linking required, but this is a non-standard build (eg. prof). You need to build the program twice: once the normal way, and then in the desired way using -osuf to set the object file suffix. I tried googling on the error with no success. What can I do to compile this file for profiling? Cheers, Nikos ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Error when building executable with profiling enabled
You are using TemplateHaskell (-fth switch) which can be tricky. Please see this documentation on profiling with TH: http://www.haskell.org/ghc/docs/7.6.1/html/users_guide/template-haskell.html#id624714. Other than following the documentation I would recommend using Cabal which handles the necessary flags and double-compilation process itself. Best regards, Krzysztof Skrzętnicki On Fri, Apr 5, 2013 at 4:41 PM, Nikolaos Bezirgiannis bez...@gmail.comwrote: Hello, i have an executable where i want to run profiling on. I do: ghc --make -prof -auto-all -fth Custom.hs but it does not built and the output is: bench\HLogo\Custom\Custom.hs:1:1: Dynamic linking required, but this is a non-standard build (eg. prof). You need to build the program twice: once the normal way, and then in the desired way using -osuf to set the object file suffix. I tried googling on the error with no success. What can I do to compile this file for profiling? Cheers, Nikos ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
On 5 April 2013 12:20, Andrew Butterfield
andrew.butterfi...@scss.tcd.ie wrote:
On 4 Apr 2013, at 22:53, Aleksey Khudyakov wrote:
If we are going to change haddock syntax we should add ability to add
math formulae to documentation. It's not currently possible and it makes
documenting numeric code properly difficult.
How about support for .lhs files?
- both those with bird-tracks (which I don't use anymore)
and \begin{code}...\end{code} (which I do use).
My .lhs files are also LaTeX sources - I guess some way to nicely integrate
haddock markup/down/whatever with LaTeX stuff would be needed
I'm not sure that it would help. If we to use haddock markup it need to
support math typesetting. And LaTeX IMHO isn't right tool for creating
hyperlinked API reference
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
I'm not proposing the LaTeX is used for hyperlinking the
reference - hence my comment about nicely integrating
Perhaps a \begin{haddock} ... \end{haddock} environment* ?
* This would only affect those using LaTeX/lhs - everyone else could haddock**
as usual
** haddock = whatever markdow/up/sideways scheme you guys come up with...
On 5 Apr 2013, at 16:22, Aleksey Khudyakov wrote:
On 5 April 2013 12:20, Andrew Butterfield
andrew.butterfi...@scss.tcd.ie wrote:
On 4 Apr 2013, at 22:53, Aleksey Khudyakov wrote:
If we are going to change haddock syntax we should add ability to add
math formulae to documentation. It's not currently possible and it makes
documenting numeric code properly difficult.
How about support for .lhs files?
- both those with bird-tracks (which I don't use anymore)
and \begin{code}...\end{code} (which I do use).
My .lhs files are also LaTeX sources - I guess some way to nicely integrate
haddock markup/down/whatever with LaTeX stuff would be needed
I'm not sure that it would help. If we to use haddock markup it need to
support math typesetting. And LaTeX IMHO isn't right tool for creating
hyperlinked API reference
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204
Lero@TCD, Head of Foundations Methods Research Group
Director of Teaching and Learning - Undergraduate,
School of Computer Science and Statistics,
Room G.39, O'Reilly Institute, Trinity College, University of Dublin
http://www.scss.tcd.ie/Andrew.Butterfield/
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
Hi,
I also support the idea of having Markdown for Haddock. Using some well
established markup language would make Haddock much easier to adopt and use.
While I like the idea of allowing any markup language (let's say supported
by Pandoc) and freedom it gives to developers, it also has also drawbacks:
It makes contributing more difficult, if a project uses some wierd,
non-standard markup language.
Concerning math expressions, what about using Markdown with MathJAX, like
math.stackexchange.com does?
Best regards,
Petr Pudlak
2013/4/5 Andrew Butterfield andrew.butterfi...@scss.tcd.ie
I'm not proposing the LaTeX is used for hyperlinking the
reference - hence my comment about nicely integrating
Perhaps a \begin{haddock} ... \end{haddock} environment* ?
* This would only affect those using LaTeX/lhs - everyone else could
haddock** as usual
** haddock = whatever markdow/up/sideways scheme you guys come up with...
On 5 Apr 2013, at 16:22, Aleksey Khudyakov wrote:
On 5 April 2013 12:20, Andrew Butterfield
andrew.butterfi...@scss.tcd.ie wrote:
On 4 Apr 2013, at 22:53, Aleksey Khudyakov wrote:
If we are going to change haddock syntax we should add ability to add
math formulae to documentation. It's not currently possible and it
makes
documenting numeric code properly difficult.
How about support for .lhs files?
- both those with bird-tracks (which I don't use anymore)
and \begin{code}...\end{code} (which I do use).
My .lhs files are also LaTeX sources - I guess some way to nicely
integrate
haddock markup/down/whatever with LaTeX stuff would be needed
I'm not sure that it would help. If we to use haddock markup it need to
support math typesetting. And LaTeX IMHO isn't right tool for creating
hyperlinked API reference
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204
Lero@TCD, Head of Foundations Methods Research Group
Director of Teaching and Learning - Undergraduate,
School of Computer Science and Statistics,
Room G.39, O'Reilly Institute, Trinity College, University of Dublin
http://www.scss.tcd.ie/Andrew.Butterfield/
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
On Fri, Apr 5, 2013 at 10:12 AM, Petr Pudlák petr@gmail.com wrote:
While I like the idea of allowing any markup language (let's say supported
by Pandoc) and freedom it gives to developers, it also has also drawbacks:
It makes contributing more difficult, if a project uses some wierd,
non-standard markup language.
I feel pretty strongly about this; I don't think we gain much by allowing
arbitrary formats. I think the same argument for coding conventions
applies here -- consistency is much more important for readability than
flexibility.
--Rogan
Concerning math expressions, what about using Markdown with MathJAX, like
math.stackexchange.com does?
Best regards,
Petr Pudlak
2013/4/5 Andrew Butterfield andrew.butterfi...@scss.tcd.ie
I'm not proposing the LaTeX is used for hyperlinking the
reference - hence my comment about nicely integrating
Perhaps a \begin{haddock} ... \end{haddock} environment* ?
* This would only affect those using LaTeX/lhs - everyone else could
haddock** as usual
** haddock = whatever markdow/up/sideways scheme you guys come up with...
On 5 Apr 2013, at 16:22, Aleksey Khudyakov wrote:
On 5 April 2013 12:20, Andrew Butterfield
andrew.butterfi...@scss.tcd.ie wrote:
On 4 Apr 2013, at 22:53, Aleksey Khudyakov wrote:
If we are going to change haddock syntax we should add ability to add
math formulae to documentation. It's not currently possible and it
makes
documenting numeric code properly difficult.
How about support for .lhs files?
- both those with bird-tracks (which I don't use anymore)
and \begin{code}...\end{code} (which I do use).
My .lhs files are also LaTeX sources - I guess some way to nicely
integrate
haddock markup/down/whatever with LaTeX stuff would be needed
I'm not sure that it would help. If we to use haddock markup it need to
support math typesetting. And LaTeX IMHO isn't right tool for creating
hyperlinked API reference
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204
Lero@TCD, Head of Foundations Methods Research Group
Director of Teaching and Learning - Undergraduate,
School of Computer Science and Statistics,
Room G.39, O'Reilly Institute, Trinity College, University of Dublin
http://www.scss.tcd.ie/Andrew.Butterfield/
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
Johan Tibell johan.tib...@gmail.com writes: I suggest that we implement an alternative haddock syntax that's a superset of Markdown. Definite +1 from me too. -- John Wiegley FP Complete Haskell tools, training and consulting http://fpcomplete.com johnw on #haskell/irc.freenode.net ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
Personally I think Markdown sucks, although perhaps less than Haddock
markup.
Still:
* No document meta data
* No code block meta data like language for syntax highlighting
* No tables
* No footnotes
* HTML fallback is insecure
* Confusing syntax (is it []() or ()[] for links?)
* Syntax that gets in the way (maybe I don't want *stars* emphasized)
* Above point leads to non-standard dialects like GitHub Markdown (no,
GitHub doesn't use markdown)
* Not extensible, leading to even more non-standard hacks and work-arounds
(GitHub Markdown, Pandoc Markdown, other Markdown libraries have their own
incompatible extensions)
* Not well suited for web input (e.g. four-space indentation for code
blocks), although not that important for Haddock
An important thing to note here is that no, Markdown has *not* won because
no one is actually using *Markdown*. They're using their own, custom and
incompatible dialects.
Only two of the above points apply to reStructuredText (web input and
syntax getting in the way), and those particular points don't apply to
Creole. Therefore I tend to advocate Creole for web applications and
reStructuredText for documents.
On Thu, Apr 4, 2013 at 6:49 PM, Johan Tibell johan.tib...@gmail.com wrote:
Hi all,
Haddock's current markup language leaves something to be desired once
you want to write more serious documentation (e.g. several paragraphs
of introductory text at the top of the module doc). Several features
are lacking (bold text, links that render as text instead of URLs,
inline HTML).
I suggest that we implement an alternative haddock syntax that's a
superset of Markdown. It's a superset in the sense that we still want
to support linkifying Haskell identifiers, etc. Modules that want to
use the new syntax (which will probably be incompatible with the
current syntax) can set:
{-# HADDOCK Markdown #-}
on top of the source file.
Ticket: http://trac.haskell.org/haddock/ticket/244
-- Johan
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
I forgot the mention the craziness with the *significant trailing
whitespace*.
On Fri, Apr 5, 2013 at 9:49 PM, dag.odenh...@gmail.com
dag.odenh...@gmail.com wrote:
Personally I think Markdown sucks, although perhaps less than Haddock
markup.
Still:
* No document meta data
* No code block meta data like language for syntax highlighting
* No tables
* No footnotes
* HTML fallback is insecure
* Confusing syntax (is it []() or ()[] for links?)
* Syntax that gets in the way (maybe I don't want *stars* emphasized)
* Above point leads to non-standard dialects like GitHub Markdown (no,
GitHub doesn't use markdown)
* Not extensible, leading to even more non-standard hacks and work-arounds
(GitHub Markdown, Pandoc Markdown, other Markdown libraries have their own
incompatible extensions)
* Not well suited for web input (e.g. four-space indentation for code
blocks), although not that important for Haddock
An important thing to note here is that no, Markdown has *not* won because
no one is actually using *Markdown*. They're using their own, custom and
incompatible dialects.
Only two of the above points apply to reStructuredText (web input and
syntax getting in the way), and those particular points don't apply to
Creole. Therefore I tend to advocate Creole for web applications and
reStructuredText for documents.
On Thu, Apr 4, 2013 at 6:49 PM, Johan Tibell johan.tib...@gmail.comwrote:
Hi all,
Haddock's current markup language leaves something to be desired once
you want to write more serious documentation (e.g. several paragraphs
of introductory text at the top of the module doc). Several features
are lacking (bold text, links that render as text instead of URLs,
inline HTML).
I suggest that we implement an alternative haddock syntax that's a
superset of Markdown. It's a superset in the sense that we still want
to support linkifying Haskell identifiers, etc. Modules that want to
use the new syntax (which will probably be incompatible with the
current syntax) can set:
{-# HADDOCK Markdown #-}
on top of the source file.
Ticket: http://trac.haskell.org/haddock/ticket/244
-- Johan
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
On Thu, Apr 4, 2013 at 11:22 PM, Kim-Ee Yeoh k...@atamo.com wrote: Could you say something about /why/ you make the suggestion? I, for one, would be happy to google and read links, but what's missing from that experience would be input from a fellow haskeller. In context. In real-time. On topic. Pretty much the same reasons Richard O'Keefe has already said more vigorously: Markdown is ambiguous, and thus difficult to write good parsers for, and that makes it hard to write good text that does exactly what you want without struggling and clawing at it and eventually just using some dirty hack workaround you found on Google. Or changing your document's contents to handle a formatting bug/misdesign. People may say well Markdown has won, in which case Markdown _has_ won. But there are still plenty of good alternatives out there that are widely used (RST is just my personal favorite). And there since there are good alternatives out there which don't have these problems, why not use them instead? I didn't really want to start a markup-language-flame-war... except that I'm glad that people are discussing it and thinking about these issues... So maybe I did. :-( Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
I like markdown and use it all the time. While I acknowledge the
problems that have been pointed out, markdown has the advantage of being
easily readable as it is in the source document, and not looking like
markup.
But I do want to point out one problem with markdown as a format for
documentation in Haskell files. Consider:
module MyModule
{-
# Introduction
This is my module
-}
where
import System.Environment
main = getArgs = print
Now try to compile with -cpp, and you'll get an error because of the '#'
in column 1. '#' in column 1 is common in markdown (and even
indispensible for level 3+ headers).
One could work around this by disallowing level 3+ headers, by allowing
the headers to be indented, or by introducing new setext-like syntax for
level 3+ headers, but it is a problem for the idea of using a markdown
SUPERset.
John
+++ dag.odenh...@gmail.com [Apr 05 13 21:59 ]:
I forgot the mention the craziness with the *significant trailing
whitespace*.
On Fri, Apr 5, 2013 at 9:49 PM, [1]dag.odenh...@gmail.com
[2]dag.odenh...@gmail.com wrote:
Personally I think Markdown sucks, although perhaps less than Haddock
markup.
Still:
* No document meta data
* No code block meta data like language for syntax highlighting
* No tables
* No footnotes
* HTML fallback is insecure
* Confusing syntax (is it []() or ()[] for links?)
* Syntax that gets in the way (maybe I don't want *stars* emphasized)
* Above point leads to non-standard dialects like GitHub Markdown
(no, GitHub doesn't use markdown)
* Not extensible, leading to even more non-standard hacks and
work-arounds (GitHub Markdown, Pandoc Markdown, other Markdown
libraries have their own incompatible extensions)
* Not well suited for web input (e.g. four-space indentation for code
blocks), although not that important for Haddock
An important thing to note here is that no, Markdown has *not* won
because no one is actually using *Markdown*. They're using their own,
custom and incompatible dialects.
Only two of the above points apply to reStructuredText (web input and
syntax getting in the way), and those particular points don't apply to
Creole. Therefore I tend to advocate Creole for web applications and
reStructuredText for documents.
On Thu, Apr 4, 2013 at 6:49 PM, Johan Tibell
[3]johan.tib...@gmail.com wrote:
Hi all,
Haddock's current markup language leaves something to be desired
once
you want to write more serious documentation (e.g. several
paragraphs
of introductory text at the top of the module doc). Several features
are lacking (bold text, links that render as text instead of URLs,
inline HTML).
I suggest that we implement an alternative haddock syntax that's a
superset of Markdown. It's a superset in the sense that we still
want
to support linkifying Haskell identifiers, etc. Modules that want to
use the new syntax (which will probably be incompatible with the
current syntax) can set:
{-# HADDOCK Markdown #-}
on top of the source file.
Ticket: [4]http://trac.haskell.org/haddock/ticket/244
-- Johan
___
Haskell-Cafe mailing list
[5]Haskell-Cafe@haskell.org
[6]http://www.haskell.org/mailman/listinfo/haskell-cafe
References
1. mailto:dag.odenh...@gmail.com
2. mailto:dag.odenh...@gmail.com
3. mailto:johan.tib...@gmail.com
4. http://trac.haskell.org/haddock/ticket/244
5. mailto:Haskell-Cafe@haskell.org
6. http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
