Filename case issues for cross-platform document generation

[steve-baker-cradle]

It seems LDoc behaves differently on macOS & Windows with respect to resolving file references.

As an example, my config.ld file contains two files:

topics = { 'Info.md' }
file = { 'app.lua' }

(Note: Info.md has a capital letter at the start.)

app.lua contains the following reference:

--  This should always be @{Info.md|some info}.

When generating the documentation on macOS this works as expected, but the Windows generation produces a module not found warning and the output contains '???' instead of a valid link.

I believe the different arises because the filenames are passed through pl.path.normcase in LDoc's tools.abspath function and converted to lower case on Windows which causes the name mismatch.

Converting the reference only to lower case (@{info.md|some info}) resolves the issue on Windows but then makes it incompatible with macOS where no case conversion takes place, so the only way to make both platforms work is to only use filenames with lower case letters.

Is this expected behaviour?

[Tieske]

there were some fixes in Penlight a while ago wrt normalization...

[steve-baker-cradle]

From the current implementation of path.normcase on the master branch of Penlight:

-- @usage path.normcase("/Some/Path/File.txt")
-- -- Windows: "\some\path\file.txt"
-- -- Others : "/Some/Path/File.txt"

there's still a difference in normalisation on Windows vs. other platforms. Could you clarify?

[Tieske]

The normalization is done to compare files to be the same ones. Since Windows is case insesntive it is normalized to lower case to enable the comparison. That will however break if the result is written to a case sensitive file system (eg. render on Windows, and then push the results to github).

[steve-baker-cradle]

The problem seem to be that the generation (on a single platform) fails as the markdown modules (apologies if I'm using the wrong terminology) are registered using the normalised case filename but looking up the module from a reference doesn't pass through the same normalisation, so using any uppercase characters in the filename (and using the same case in the reference) causes the "module not found" warning.

[Tieske]

It's been a while, but the following will also cause issues;

Have a README.md file to your repo. Add in config.ld the file as readme.md.

On windows+mac ldoc . will work, on unix ldoc . will fail. If you push the results to Github (using the Windows/Mac results), then the links won't work.