Ticket #252 (closed enhancement: fixed)

Opened 14 months ago

Last modified 8 months ago

Allow markdown inside of emphasis

Reported by: DanielDiaz Owned by: Fūzetsu
Priority: minor Milestone:
Version: Keywords:
Cc: dhelta.diaz@…

Description

By request, I copied below an e-mail I sent to David Waern about an issue with Haddock.


These are the HTML output of two docs written in Haddock syntax.

Yes, I κ.

<p>Yes, I &#954;.</p>
Yes, I /&#954;/.

<p>Yes, I <em>&amp;#954;</em>.</p>

Therefore, my question is, why is the ampersand escaped when it is inside the emphasis block, but it is not when outside? Is this consistent? I really would like to be able to emphasize characters written as HTML codes.

I guess that this is happening because inside an emphasis block no Haddock parsing is done, since I noticed that inline code blocks (@...@) do not work either, which forces me to do things like:

/The command /@foo@/ does not work./

Not a big issue, because at least is possible to get the correct output. However, the same cannot be said about HTML codes.

Another note: I think this could imply a drastic change in the Haddock parser, but it would be great if I would not need to emphasize a text line-by-line. Let me explain myself with an example. I would like to write:

-- /I divided this emphasized
-- text in multiple lines
-- because it was too long for
-- a single line./

Instead of:

-- /I divided this emphasized/
-- /text in multiple lines/
-- /because it was too long for/
-- /a single line./

Change History

follow-up: ↓ 2   Changed 13 months ago by Fūzetsu

  • owner set to Fūzetsu
  • type changed from defect to enhancement
  • summary changed from HTML codes and emphasized blocks to Allow markdown inside of emphasis

First case: that's right, you currently can not have anything but plain text inside of emphasis: the parser simply swallows up everything until a ‘/’. This is also the behaviour in the new parser I wrote simply because the first goal for it was to reproduce the old behaviour exactly. I have discussed this problem very briefly with Simon Hengel just over a week ago and the general opinion seems that it would be nice to be able to have markup inside of emphasis (note that I have currently implemented support for bold text (with 2 underscores) which also exhibits this rather nasty behaviour) and I would be all for it. It is certainly possible to do with the new parser and the implementation wouldn't be very difficult. The only obstacle is that I have no data on how much old documentation this would change and I'd like to have some numbers to back the change up. I do think that this is a nice change and that in the end, it will be put in.

For this very same reason, HTML codes aren't converted. It is certainly something that can be addressed. I will do some research into how much documentation would potentially change (to worse) but I suspect the answer will be that the benefit far outweighs any changes.

Regards multi-line emphasis: this is known, have a look at ticket #126 from years ago where I ask whether there's actually interest with this. While the implementation is certainly possible (if not quite as simple as the previous one), I am more reluctant about implementing this. With the old parser, a single unescaped ‘/’ on a line would make the parsing fail. With the current parser, it gets treated as plain text. In light of this, do you believe that multi-line emphasis is more common than single ‘/’ on a line on its own? In the end, I just don't think that multi-line emphasis warrants the additional parsing complexity and syntax rules. I would appreciate it if you could reply to this part of the ticket on the ticket #126.

I'm changing the summary to deal with allowing markdown inside of emphasis and the other part of the discussion can be carried on in #126.

Sorry for late reply, I had problem with e-mail that I was not aware of until today.

in reply to: ↑ 1   Changed 13 months ago by DanielDiaz

  • cc dhelta.diaz@… added

Replying to Fūzetsu:

First case: that's right, you currently can not have anything but plain text inside of emphasis: the parser simply swallows up everything until a ‘/’. This is also the behaviour in the new parser I wrote simply because the first goal for it was to reproduce the old behaviour exactly. I have discussed this problem very briefly with Simon Hengel just over a week ago and the general opinion seems that it would be nice to be able to have markup inside of emphasis (note that I have currently implemented support for bold text (with 2 underscores) which also exhibits this rather nasty behaviour) and I would be all for it. It is certainly possible to do with the new parser and the implementation wouldn't be very difficult. The only obstacle is that I have no data on how much old documentation this would change and I'd like to have some numbers to back the change up. I do think that this is a nice change and that in the end, it will be put in.

These are good news. About old documentation compatibility, probably there are some docs around using markdown inside of emphasis, knowing that the character will show up. Something in the lines of "/Take 'it'!/". If we apply the proposed changes, the output of those docs would change. This is all hypothetical, but given the number of packages, we surely have some cases like this. If something is feasible, it will be done.

For this very same reason, HTML codes aren't converted. It is certainly something that can be addressed. I will do some research into how much documentation would potentially change (to worse) but I suspect the answer will be that the benefit far outweighs any changes. Regards multi-line emphasis: this is known, have a look at ticket #126 from years ago where I ask whether there's actually interest with this. While the implementation is certainly possible (if not quite as simple as the previous one), I am more reluctant about implementing this. With the old parser, a single unescaped ‘/’ on a line would make the parsing fail. With the current parser, it gets treated as plain text. In light of this, do you believe that multi-line emphasis is more common than single ‘/’ on a line on its own? In the end, I just don't think that multi-line emphasis warrants the additional parsing complexity and syntax rules. I would appreciate it if you could reply to this part of the ticket on the ticket #126.

I wrote my response in the mentioned ticket.

I'm changing the summary to deal with allowing markdown inside of emphasis and the other part of the discussion can be carried on in #126. Sorry for late reply, I had problem with e-mail that I was not aware of until today.

Thank you! :)

follow-up: ↓ 4   Changed 13 months ago by Fūzetsu

  • status changed from new to assigned

If we apply the proposed changes, the output of those docs would change.

Yes, you're right. After reading a fair amount of documentation and giving it some though, I do not think that this will actually matter. There certainly might be some documentation around that will change because of this but the change will not be huge, merely slightly aesthetic. If you're making docs with the brand-new Haddock and latest GHC, you're probably prepared for any slight changes that might occur. Announcement with changes and fresh documentation will also be released beforehand so active folk can read what's going on. Inactive folk won't be regenerating docs anyway.

I do not have the numbers to back it up though. I started writing something to quantify this but I have not had time to develop it properly.

This has actually been implemented already. I'm just doing some slight debugging but I think that the general opinion is that this is a welcome feature, far outweighing individual snippets of code that might change here and there. We're adding functionality and old behaviour can still be achieved by escaping the characters.

Here's a small snippet of documentation rendered with this suggestion in place. http://fuuzetsu.co.uk/blog/images/inside_markup.png

in reply to: ↑ 3   Changed 13 months ago by DanielDiaz

This has actually been implemented already. I'm just doing some slight debugging but I think that the general opinion is that this is a welcome feature, far outweighing individual snippets of code that might change here and there. We're adding functionality and old behaviour can still be achieved by escaping the characters. Here's a small snippet of documentation rendered with this suggestion in place. http://fuuzetsu.co.uk/blog/images/inside_markup.png

Thank you! This is actually a great improvement over the current state.

Is the handling of HTML codes inside emphasized (or bold faced) blocks solved yet?

  Changed 13 months ago by Fūzetsu

  • version 2.11.0 deleted

Sorry, I forgot to reply:

*Haddock.ParseSpec> parseParas "__yes, it should be &#65;__"
Just (DocParagraph (DocAppend (DocBold (DocString "yes, it should be A")) (DocString "\n")))

So that would be a ‘yes’.

I think the merging will be done relatively soon so it will land in HEAD in a while.

  Changed 8 months ago by Fūzetsu

  • status changed from assigned to closed
  • resolution set to fixed

This is now fixed in HEAD, you can grab it and regenerate your docs if you want.

Note: See TracTickets for help on using tickets.