MAC OS X: Help Menu’s links unresponsive for README.md & NEWS.md files.

[macca8]

Since converting the README & NEWS files to ‘.md’ files, their respective ‘General Information’ & ‘What’s New in ScummVM’ links in the ScummVM application’s Help Menu have become unresponsive.

Both files can be opened directly using TextEdit, either by choosing TextEdit when requested to select a suitable app, or by double clicking the file after setting TextEdit as the default app in the file’s Get Info panel.

However, these links remain unresponsive even with TextEdit set as the default app for opening the file.

All other Help Menu links work as expected.

Current Daily Build: 2.1.0git5180-gbcd44e7d95(18 April 2019)
Platform: Intel Mac (OS X 10.6.8, 10.11.6)

[macca8]

The links can be reactivated by manually removing the '.md' extension from the filename.

However, this just displays the raw text of the relevant document (including the formatting code), rather than the properly formatted document (complete with hyperlinks).
It's the same when opening the '.md' file directly with TextEdit.

[criezy]

That you for reporting this issue.
When pandoc is installed on the computer on which ScummVM is compiled, then it works properly. But indeed if pandoc is not present, the README and NEWS files cannot be open from the Help menu of the ScummVM application. If pandoc is not present to convert the document, there is not much we can do beside displaying the raw document. But I think it would still be better than not opening anything.

[angstsmurf]

Would it make sense to add a check for Pandoc in the build scripts? Not as a required dependency, of course.

[criezy]

There is already a check for it in configure, and it is optional. And if present pandoc is used to convert the .md files. But I will need to add something to properly handle the case when it is not present so that the Help menu works properly in the application.

[criezy]

While looking at this, I am also looking at improving the README we get from the Help menu when pandoc is present. Currently pandoc converts the markdown file to plain text. This is what we had before switching the file to markdown, but we can probably do better now.

One possibility would be to generate a RTF file instead of plain text, which would give us a nice formatting. However it seems that TextEdit does not support having links to bookmark within the document, so while I can generate a nicely formatted RTF, the TOC does not have links, which is a shame.

Another options would be to use html, and use a web browser instead of TextEdit to open the file. With this option we do get links in the TOC. This file would be present locally, so it would not require having internet access.

Do you have a preference between the Help menu opening a README RTF document with no link in the table of content (but external links work properly), and a HTML document with properly working links in the table of content?

For reference in case I forget, if we want to generate RTF file we need to use pandoc to generate html first, and then textutil to generate the RTF file. In theory pandoc can output rtf directly, but it gives a file that cannot be properly displayed in TextEdit.

[macca8]

Thanks for your response criezy.

The formatting provided by either a RTF file or one based on html would be preferable to a plain text version. Personally, I’d be happy with either, but in my opinion, the html option has more upside.

The README document is a very long document with a long TOC, so it makes more sense to give the user the advantage of using the TOC links to navigate within the document.
And with the web browser already open, there’s a seamless transition if the user selects an external link.

For consistency, I’d recommend using the html option for the NEWS document as well. There’s no local links, but there’s at least one external link which would require the web browser to be launched.

There’s also the fact that the first 3 links in the Help Menu (likely to be the most popular) would all open in a web browser, which in itself provides a consistent feel to the user.

[criezy]

In 66ef22d5:

MACOSX: Improve opening files from the Help menu

Now in addition to rtf extension and no extension, it also looks
for the html and md extensions. Also unless the extension is RTF or
HTML, which are widely recognized, it explicitely indicate that the
file should be open with TextEdit.

This fixes bug #10938, with opening the README and NEWS file from
the Help menu failing when the bundle was compiled without using
pandoc and thus the only files available are the markdown ones.

Support for the html extension is to prepare for a future change
to have a nicer README than the plain text one.

[criezy]

Thank you. This confirms what I though, and I have now both fixed this bug (it should properly open the md files if that's all we have becausee pandoc is not installed), and changed the behaviour when pandoc is present to convert the README.md and NEWS.md files to html by default on macOS.

[macca8]

Thanks criezy. Excellent work as usual.

The latest daily build now includes both html & md versions of the README & NEWS files in its bundle, and both html files open as expected through the Help Menu links.