|media| pointing to wrong directory

[mcocdawc]

Dear ford developers,

We have a problem in a larger project of ours that I recreated in the minimal example of ford. See here in our fork.

Let's say I have a media_dir directory (containing a media_dir/test_file.txt) on the same level as my gen_docs.md entry point file. In the settings I correctly specified:

media_dir: ./media_dir

If I then put

[See this test file](|media|/test_file.txt)

in the gen_docs.md file everything works correctly.

But if I have additional pages as for example pages/01_user_doc/01_getting_into_the_game.md and write

[See this test file](|media|/test_file.txt)

there, then |media| does not get expanded to the absolute path of media_dir, but pages/01_user_doc/ is prepended, i.e. the path becomes page/01_user_doc/media/test_file.txt and the link breaks.

Is this desired behaviour? I thought |media| should return the same path everywhere.

You can test reproduce the problem by running

ford example-project-file.md -p pages/

in the example directory of our fork.

[ZedThree]

Thanks for the very clear reproducer @mcocdawc. I think this is the same issue as #461

You're correct that |media| is intended to return the same path everywhere. I think the problem is that we can't just expand the aliases to the absolute path, because this wouldn't work when the docs are deployed online. We also can't expand them in the typical web fashion as relative to the project root, because this wouldn't work when browsing locally.

Needs some careful thinking!

[mcocdawc]

Needs some careful thinking!

Yes, indeed it is not trivial to determine the actually desired behaviour.

We also can't expand them in the typical web fashion as relative to the project root, because this wouldn't work when browsing locally.

Wouldn't it work if |media| always returns relative paths, relative to the current file?

Let's say you have the following structure.

gen_docs.md
pages/installation_instructions.md
media/

Inside gen_docs.md it would be |media| -> ./media and inside installation_instructions.md it would be |media| -> ../media. Using os.path.relpath this seems to be doable.

Another 2cts of mine is that if --output_dir is used, it would be great to have |output_dir| available. This would give us a reasonably clean temporary workaround in the form of |output_dir|/media. I think having |output_dir| to be an absolute path is reasonable.

[ZedThree]

I've had another quick look at this. Due to the way the macros (currently, at least) work is that the substitution text is already expanded when the macro is registered, so we can't make the paths expand differently in different files. We also currently don't have a mechanism to detect which macros are paths and which are plain text.

An alternative is to drop the relative option and instead make the project root be /. This does mean that the links won't work correctly just opening the HTML files locally in a browser, however Python does ship with http.server which can serve the built docs just fine. To make this easier for users, we could add a --serve option to ford to launch the server.

[mcocdawc]

hmm that makes sense and indeed seems cumbersome to fix.

The absolutep path |output_dir| should work though, if I understand it correctly, isn't it?

[ZedThree]

Yes, |output_dir| as an absolute path makes sense, though there might be security implications of using it in production.