Fortran-FOSS-Programmers / ford

Automatically generates FORtran Documentation from comments within the code.
https://forddocs.readthedocs.io
GNU General Public License v3.0
410 stars 134 forks source link

Markdown line breaks not working in lists #646

Open jatkinson1000 opened 7 months ago

jatkinson1000 commented 7 months ago

I have a list in my documentation page, and I want to insert a line break in some of the list items. Usually in markdown I would use a trailing \ (works in GitHub, GitLab and more generally elsewhere).

However, when the html is created with FORD there is no line break and instead the '\' appears as part of the rendered text. As a workaround I have to resort to using a <br> instead which is less 'markdownthonic'.

If the <br> didn't work either I'd guess the inputs were getting sanitised somewhere to cause this, but I'm not sure why it happens. It'd be a 'nice to have' functionality.

My specific example with <br> where I'd prefer to use \:

* Reducing the overheads for coupling PyTorch machine learning models to Fortran<br>
  ML & DL Seminars, LSCE, IPSL, Paris - November 2023<br>
  [Slides](https://jackatkinson.net/slides/IPSL_FTorch/IPSL_FTorch.html) - [Recording](https://www.youtube.com/watch?v=-NJGuV6Rz6U)
* Reducing the Overhead of Coupled Machine Learning Models between Python and Fortran<br>
  RSECon23, Swansea - September 2023<br>
  [Slides](https://jackatkinson.net/slides/RSECon23/RSECon23.html) - [Recording](https://www.youtube.com/watch?v=Ei6H_BoQ7g4&list=PL27mQJy8eDHmibt_aL3M68x-4gnXpxvZP&index=33)
jatkinson1000 commented 7 months ago

Ah, it seems the training \ is a CommonMark only thing. I'll see if two trailing spaces work, though I dislike this approach as it can be harder to see and trailing whitespace is generally discouraged.

ZedThree commented 7 months ago

Yes, it's unfortunate that Markdown has so many variations and dialects. Nowadays, there's MyST which is a superset of CommonMark with an emphasis on features for scientific writing which would be quite nice to use.

In principle we could swap out the markdown library for another one that supported other dialect(s), and this might also improve performance, but I wouldn't want to break existing projects, so it would have to be optional.

We also have some custom plugins to add some functionality that would need porting, which is another challenge