Backslashes in inline Fortran comments

[Meax5qiu]

Ford 6.1.11

I'm currently setting up Ford for a project where it could be incredibly useful, if it only did treat standalone Markdown input and Markdown-formatted comments in the Fortran source identically. I just found this weird inconsistency:

title: MD MWE
project: Ford Inline TeX
docmark: >
predocmark: !

$$\begin{split} 
   a&=x+5 \\
   a+b+c&=5 \\
\end{split}$$

given to Ford as a static Markdown (-p on the ford commandline) works as a TeX-literate human would expect it (displays a standalone formula with two lines):

Screenshot: Working MWE (Markdown)

However, once the MD is prepended with docmark and put into a Fortran source file...

!> $$\begin{split} 
!>    a&=x+5 \\
!>    a+b+c&=5 \\
!> \end{split}$$

i = 0

Screenshot: Not working MWE (Fortran + docstring)

...it starts doing weird stuff. Looking at the HTML output:

<script type="math/tex; mode=display">\begin{split} 
   a&=x+5 \!>    a+b+c&=5 \!> \end{split}</script>
</p>

the first backslash, instead of literally being passed to MathJax, removes the line break, and prevents the docmark from being removed. \! happens to be a valid TeX macro (thin negative space), so no syntax error is produced, but the output is still wrong (= unexpected, different from original LaTeX input, as well as from the rendering of the standalone MD above).

Observed behaviour In an inline comment TeX environment, put in n backslashes in a row, and n-1 backslashes, followed by the docmark, appear in the HTML.

Expected behaviour In an inline comment TeX environment, put in n backslashes in a row, and n backslashes are handed over to MathJax, without docmarks in between.

I haven't yet had a look into the Ford sources, but it seems to me as if the logic to strip off the docmark signs, and the identification of TeX-style environments/verbatim hand-over to MathJax, are applied in the wrong order.

What makes me wonder is, why this is an issue at all. Multi-line TeX formulas are generally no issue at all, so Ford does the right thing in stripping off the !> in all cases I've looked at, except when backslashes are involved. At some point, Ford puts some extra effort into a special (and in this case unnecessary/harmful) treatment of backslashs/escaping.

[Meax5qiu]

It's even more fundamental: it has nothing to do with TeX/MathJax at all.

Fortran source comment:

!> Back- \
!> slash

HTML output:

<p>Back- !&gt; slash</p>

I can't tell if this is a bug or a feature in general, but with \\ as a fundamental part of multiline TeX math environments, it's definitely a dealbreaker.

[ZedThree]

It took me some time to reproduce this, but it turns out to be the fault of the preprocessor. ford runs cpp -traditional-cpp -E -D__GFORTRAN__ over .F90 files by default, which produces the following (snipped):

# 1 "<command-line>" 2
# 1 "src/prog.F90"
!> $$\begin{split} 
!>    a&=x+5 \!>    a+b+c&=5 \!> \end{split}$$


!>
!> Back-!> slash


i = 0

Unfortunately, this happens very early on in the preprocessing, and there don't appear to be any options to any of the common preprocessors to change this behaviour.

You have three options to deal with this:

1. Turn off preprocessing in ford with preprocess: False
2. Add comments to the end of lines that end with \ (see below)
3. Find or create a preprocessor that doesn't use line continuations with \

Here's how to use comments to avoid this:

I'm afraid there's really not very much we can do in ford about this, as it happens in the preprocessor.

[Meax5qiu]

Thank you so much! I'll have to evaluate first if disabling preprocessing is an option, and if not, a sed -i 's/\\$/\\ %/g' seems within reach in my setup (no issue for porting the existing docs, and for new formulas it has the appeal to still be valid LaTeX).