Windows / Invalid filename

[cvasilak]

Hi all,

noticed an issue when generating 'jazzy' documentation. In particular, if the html filename generated contains a ":" character such as

init(baseURL:sessionConfig:requestSerializer:responseSerializer:).html

fails on windows (eg. checking out a project the contains this file). Is there any way this separator character can be customised in the command line to make windows happy so checking out a project won't fail?

Thank you!

[jpsim]

Fixing this should simply be a matter of sanitizing the name before making a URL out of it.

[mbogh]

@cvasilak, can you provide some way of replicating this outcome?

[jpsim]

I believe the proper fix here is to be URL escaping the declaration name.

[mbogh]

@jpsim are you thinking something as simple as adding the following to sourcekitten.rb

...
require 'uri'
...
              [URI.escape(doc.name) + '.html']
...

makes for somewhat "ugly" file names e.g. "Global%20Variables.html"

[jpsim]

it does make for fairly uglier URLs, but I believe that's the safest way to generate URLs.

[mbogh]

I'll have a go at it if I'm not overwhelmed by todays event 😸

[mbogh]

Hmm simply using URI.escape(doc.name) gives us Global%20Variables.html which makes Safari and Chrome really sad on OS X.

If we use doc.name.gsub(/[^\w\.]/, '_') instead we would gain filenames like Global_Variables.html.

Any comment on this @jpsim ?

[jpsim]

I get the feeling that this has already been solved by other ruby projects in a general way, and that gsub(/[^\w\.]/, '_') may not be sufficient to clean up URLs.

[mbogh]

True, so a gem like https://github.com/agilecreativity/filename_cleaner

require 'filename_cleaner'

[FilenameCleaner.sanitize(doc.name) + '.html']

Would result in Global.Variables.html

And the file:
init(baseURL:sessionConfig:requestSerializer:responseSerializer:).html
would become:
init.baseURL.sessionConfig.requestSerializer.responseSerializer.html

[jpsim]

Hmm simply using URI.escape(doc.name) gives us Global%20Variables.html which makes Safari and Chrome really sad on OS X.

I'm curious, what do you mean by this? Does it cause issues with Safari and Chrome? This seems like a simpler & better supported solution rather than filename_cleaner.

[mbogh]

@jpsim I might have misunderstood the issue but if URI.escape() is applied both to the filename and the link then Safari and Chrome is not able to load the Global Variables.

Should URI.escape() only be applied to the link itself?

[jpsim]

Should URI.escape() only be applied to the link itself?

What happens if you try that?

[mbogh]

Then everything is fine, file is named Global Variables.html and link is href="Global%20Variables.html".

But the file name of the OP will remain and cause trouble? I don't even know how the filename mentioned by OP would come into question.

[jpsim]

But the file name of the OP will remain and cause trouble?

The issue wasn't in saving the file, but rather accessing it unescaped via a URL in a browser.

I don't even know how the filename mentioned by OP would come into question.

A file name like init(baseURL:sessionConfig:requestSerializer:responseSerializer:).html would happen if there's a nested type in there, which is weird but could happen.

[mbogh]

But URI.escape() would not fix the "weird" filename.

head :001 > require 'uri'
 => true 
head :002 > URI.escape("init(baseURL:sessionConfig:requestSerializer:responseSerializer:).html")
 => "init(baseURL:sessionConfig:requestSerializer:responseSerializer:).html" 
head :003 > 

[jpsim]

Ah you're right. Reading the original issue description again, the issue was that the filename is invalid on Windows because it contains colons. I'm not sure how much of a problem this actually is in practice then, because jazzy only runs on OS X and who in the world would run a webserver for Swift documentation on IIS.

I'm inclined to just close this as "won't fix". Am I crazy for thinking this @mbogh @segiddins ?

[mbogh]

We could apply URI.escape() to be good web citizens?, but yeah it seems unlikely to host swift documentation on an IIS.

[jpsim]

We could apply URI.escape() to be good web citizens?

But then this would uglify URLs for everyone, with the only benefit being allowing these docs to be hosted on Windows?

[mbogh]

True, it would seem that all modern browser does not break if whitespace e.g. is not escaped.

Should I simply delete my branches(prs)?

[jpsim]

I think so. I really appreciate you digging into this though, but it feels better to leave this one as-is IMO. Closing.

[SDGGiesbrecht]

The configuration option use_safe_filenames and the corresponding flag --use-safe-filenames are now available. Until 0.7.4 is released, you can build and run from source (in your project directory):

git clone https://github.com/realm/jazzy
cd jazzy
bundle install
cd ..
jazzy/bin/jazzy --use-safe-filenames
rm -rf jazzy

Any other flags you normally use (such as --clean) can be added to the second last line.