On 29 April 2013 18:16, Alexander Kjeldaas <[email protected]> wrote: > I see the pluggable markup being pushed in this thread again. > > I just want to remind everybody that we currently have a flavor of a markup > issue on github. > > The ghc source code uses literal haskell, and it does not work well on > github. > > http://www.haskell.org/pipermail/ghc-devs/2013-April/001099.html > > Any markup that is not widely supported makes it harder for third parties to > support and parse. > > The solution is *not* to reimplement github in haskell, but to standardize > markup as much as possible. > > Pluggable markup makes the probability that a github-like service, IDEs and > similar can make use of the documentation arbitrarily close to zero.
If it's pluggable, doesn't it make the situation _worse_, as you choose a plug-in that works with one service but then fails for all the others? I think this is a bit of a non-issue: services like github should _not_ mark-up documentation (as you're going to have some kind of issue where it's rendered when you didn't expect it or vice-versa, thus making it different to read the actual code). I tend to agree with Richard, etc.: I'd rather either extend the existing Haddock mark-up or choose a sane markup language if we wish to replace/augment it (I use markup, but find a lot of its conventions appalling). > > > Alexander > > > > On Mon, Apr 29, 2013 at 8:04 AM, Richard A. O'Keefe <[email protected]> > wrote: >> >> I should add that as a consumer of Haddock documentation >> I can testify that fancier styling (in whatever format) >> would be of little benefit to _me_. What I need is more >> plain text and more examples. >> >> To be perfectly honest, most of the time when looking at >> a Haddock page, I end up clicking on the Source button >> because there are things I need to know that are in the >> source but not the documentation. >> >> So I do agree that markup that doesn't get in the way of >> a _reader_ who is looking at the source code is an excellent >> thing. >> >> I say this as someone who had to read some Java today and >> ended up stuffing it through a comment stripper so that I >> could easily find what I needed to find. >> >> This thread is not about the "visually lightweight" aspect of >> Markdown. That's a good thing. No argument there. >> >> The thread is about how well documented the notation should be. >> >> >> _______________________________________________ >> Haskell-Cafe mailing list >> [email protected] >> http://www.haskell.org/mailman/listinfo/haskell-cafe > > > > _______________________________________________ > Haskell-Cafe mailing list > [email protected] > http://www.haskell.org/mailman/listinfo/haskell-cafe > -- Ivan Lazar Miljenovic [email protected] http://IvanMiljenovic.wordpress.com _______________________________________________ Haskell-Cafe mailing list [email protected] http://www.haskell.org/mailman/listinfo/haskell-cafe
