Links should not contain absolute paths (Ford 7 regression)

[Meax5qiu]

Our project is making ample use of object-oriented Fortran, deferred procedures etc. FORD is doing an amazing job to translate the inheritance hierarchy of the source code into a hypertext tree, to click through in a web browser. ❤️

However, FORD 7.0.0 introduced changes that are breaking numerous links across internal pages because they now include absolute paths. Not all internal links are affected, but enough that we decided to stay with FORD version 6.2.5 for now, and can't enjoy all the exciting development here in the v7 series 😒.

MWE

(the "Getting Started" example with a simple OOP extension)

Contents of file /PATH/TO/MWE/my_project.md:

---
project: My Fortran project
author: Me
---

This is my Fortran project!

---

Contents of file /PATH/TO/MWE/src/hello.F90:

module my_module
  implicit none

  type :: my_class
  contains
    procedure,nopass :: hello_here => say_hello
  end type

contains

  subroutine say_hello(name)
    !! Our amazing subroutine to say hello
    character(len=*), intent(in) :: name
      !! Who to say hello to
    write(*, '("Hello, ", a)') name
  end subroutine say_hello
end module


program hello
  !! This is our program
  use my_module
  implicit none

  type(my_class) :: my_object

  ! This is just a normal comment
  call my_object%hello_here("World!")

end program hello

---

$ cd /PATH/TO/MWE

$ ford my_project.md
Preprocessing /PATH/TO/MWE/src/hello.F90
  Parsing files         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 1/1 0:00:00 0:00:00 src/hello.F90
  Correlating information from different parts of your project...
  ...done in 0.000s
  Processing comments   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 8/8 0:00:00 0:00:00 my_object
  Creating HTML documentation... done in 0.000s
  Creating search index ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 5/5 0:00:00 0:00:00 sourcefile/hello.f90.html
  Writing files         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 10/10 0:00:00 0:00:00 doc/search.html

Browse the generated documentation: file:///PATH/TO/MWE/doc/index.html

$ grep /PATH/TO/MWE -r doc/
doc/type/my_class.html:  <strong>hello_here</strong> => <a href='/PATH/TO/MWE/doc/proc/say_hello.html'>say_hello</a>
doc/module/my_module.html:  <strong><a href='../type/my_class.html#boundprocedure-hello_here'>hello_here</a></strong> => <a href='/PATH/TO/MWE/doc/proc/say_hello.html'>say_hello</a></td>

Notice how the HTML link to the hello_here interface is relative, but its target procedure say_hello is an absolute path in the HTML source.

Both links will work just fine if you visit the HTML page locally. But move/rename doc/ or one of its parent directories, or upload everything to a web server, then the second type will be broken (and may leak information about your build workflow).

---

Expected behaviour: No reference to the absolute path of the FORD run.

Why does this matter?

Whoever is running FORD in some location, and moves the rendered HTML pages somewhere else afterwards, will have their pages filled with dead links. Think of a Build here, then upload to web server workflow. Not possible with current versions of FORD. (This used to work fine, i. e. relative links everywhere, on FORD v6 series).

Workarounds? Monkey-patching, version freeze on FORD v6.2.5, or telling users to only use FORD locally. Neither sounds recommendable.

[ZedThree]

Thanks @Meax5qiu! We originally switched to trying to do absolute paths everywhere because the relative paths would also end up broken when a page was more nested than expected. I think this was mainly from the pages, rather than the source docs. I did think we tried to be consistent and do absolute links everywhere, so I'm a bit surprised a relative link has got through!

This is another reason why I'd like to somehow port the internals of Ford to using Sphinx, which would take care of this for us!

I'll have a think of how to deal with this.