Fortran-FOSS-Programmers / Fortran-FOSS-Programmers/ford

Links should not contain absolute paths (Ford 7 regression)

Open
#712 1 comment 0 reactions 0 assignees View on GitHub
bug enhancement
Dominant language
Python
Stars
458
Forks
138
PR merge metrics
No merged PRs in 30d

Description

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](https://github.com/Fortran-FOSS-Programmers/ford/blob/master/docs/user_guide/getting_started.rst?plain=1#L20) with a simple OOP extension)

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

```markdown
---
project: My Fortran project
author: Me
---

This is my Fortran project!
```

---

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

```fortran
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
```

---

```sh
$ 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: hello_here => say_hello
doc/module/my_module.html: hello_here => say_hello
```

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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.