Fortran-FOSS-Programmers / Fortran-FOSS-Programmers/ford
Links should not contain absolute paths (Ford 7 regression)
- 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.