search

Debian / debiman

debiman generates a static manpage HTML repository out of a Debian archive
Apache License 2.0
189 stars 46 forks source link

file:// URLs #59

Open mcepl opened 7 years ago

mcepl commented 7 years ago

Take a look at https://manpages.debian.org/jessie/git-man/git-rebase.1.en.html … it ends with a link to file:///usr/share/doc/git/html/howto/revert-a-faulty-merge.html. Not sure what to do with it, but it should not be both an active link and leading to nowhere, I think.

stapelberg commented 7 years ago

Thanks for the report.

Speaking about the general issue

The link in your example clearly is a valid link, but you may or may not be able to reach the content it refers to, depending on whether you have that file on your disk.

I could see other links behaving in a similar way. E.g., one could put an ipfs link (or gopher, or ftp, or…) into a manpage, and that would only work if the user agent supports the protocol natively or has an external handler correctly configured.

So, in general, links not always working is something that our users unfortunately might sometimes have to cope with anyway. That said, let’s think about how we could improve the situation.

One could argue that we should also extract and host HTML pages found in Debian packages, but I’m not convinced that’s a good idea — at the very least, it’s a significant expansion in scope of the project, and at least right now I don’t think we’re ready for that.

Speaking about the example in particular

The link in the document is defined in http://repo.or.cz/git/debian.git/blob/442dc6d91b3b0c99b084c6178d8b28e060baf484:/Documentation/git-rebase.txt#l339

The base URL is defined in http://repo.or.cz/git/debian.git/blob/442dc6d91b3b0c99b084c6178d8b28e060baf484:/Documentation/Makefile#l163

Now, from the package maintainer’s perspective, the base URL is correct, as local resources are to be preferred where available (for privacy and availability).

If the package was built specifically for manpages.debian.org, we could set the base URL to an online version (on the Git website, presumably). Since manpages.debian.org currently only extracts manpages from Debian packages found in the archive, we’d need to spin up infrastructure to do package builds and carry custom patches to these packages. This sounds too elaborate a fix for the issue at hand.

Any thoughts?

mcepl commented 7 years ago

Yeah, as I said, I don't know what to do about it exactly. Just it feels wrong to have it hanging there, when it doesn't work. Well, if you have packages installed, then you should have /usr/share/doc/ as well, shouldn't you?

stapelberg commented 7 years ago

When you have the git-doc Debian package installed, the link is valid. You still can’t click on it, at least not in Chrome 56, due to security policies preventing websites from referring to file:// content in any way. Copying the link and pasting it into your address bar does work, though.

I’ll close this issue as wontfix for now. If a good solution emerges, I’ll be happy to reopen.

mcepl commented 7 years ago

Oh right, so the problem might be I am on Fedora. Right, makes sense.

stapelberg commented 7 years ago

It occurred to me that the “limitation” label is more appropriate than “wontfix”. This issue is not something we deliberately decided against addressing, it’s something we don’t know how to fix.

anarcat commented 7 years ago

maybe this is like #70 whereas we would want to support more than manpages. we could extract more than just manpages and just lay them down in the tree somewhere those URLs could then link to.

in that sense, the title of this feature request could be "arbitrary HTML documentation extraction and file:// URLs" :)