Fix dash rendering

[prosilio]

closes #963

PR #759 replaces ndash/ and mdash/ tags with Unicode —, which is not being rendered properly:

Instead, I replace ndash/ and mdash/ with -- and ---, respectively, which are rendered properly in my tests.

Here are some examples:

Text - with - hyphens

Text -- with -- endashes

Text --- with --- emdashes

> This is a block quote with en-dash (two hyphens) attribution.
>
> -- Anonymous

> This is a block quote with em-dash (three hyphens) attribution.
>
> --- Anonymous

> This is a block quote with lots of hyphens in the attribution.
>
> -------------- Anonymous

> -- This is a block quote with en-dashes in the quotation --
>
> -- Anonymous

> -- Dashes -- --- everywhere! ---
>
> -- Here -- --- too! ---
>
> -- --- --Anonymous ---

[sethrj]

I really appreciate this fix! Grepping my sphinx html output for &# I see this in about 7 places in my project's user manual. Could one of the maintainers (@michaeljones perhaps ?) please take a look at this PR? Thanks for your hard work and great product!

[michaeljones]

Hi, thank you for the PR and for attempting to resolve the issue. Unfortunately we have a long standing PR which is going to remove the file that you have changed (breathe/parser/compound.py). We can look at the new approach and see how it handles the ndash and mdash nodes and try to ensure good behaviour. We are hopefully close to doing a alpha release of v5 with the new approach and we can test from there.

As for the attribution handling, I'm not sure that Breathe should be doing things like that? We aim to translate doxygen supported syntax into restructured text nodes and so if there isn't support for the dash in the attribution handling in doxygen then maybe we shouldn't support it here? Otherwise it feels like we're creating a Breathe flavoured markdown or doxygen markup which seems less than ideal? Unless I am getting confused? I'd be happy to hear your thoughts though if you have the time and energy to re-engage at this point.

[sethrj]

Perhaps we just need to make sure that HTML escapes (into XML) are converted into unicode characters?

[prosilio]

Thank you for the comments, @michaeljones. I'm familiar with the long-standing PR you referenced, and I had been wondering if it would obviate this PR. Looking forward to the v5 alpha release! If you want, we can close this PR and wait and see what v5 brings.

My reason for including so many attribution examples is that the intent of PR #759 was to support block quotes, so I wanted to ensure that my changes didn't break the changes from that PR.

And thank you for your enthusiasm, @sethrj! It's nice to know that my work helps someone else.