Are symbol links case-sensitive or not?

Development Swift-DocC
1

i am told that symbollinks/codelinks have become case sensitive.

For example, a type and a property like this

enum Something {}
var something: Something

needed to be written as Something-swift.enum and something-swift.property to match those "topic references". If the enum link was lowercase—like something-swift.enum—it wouldn't resolve.

this is a good idea and i wholeheartedly support it.

on the other hand, i notice certain packages, such as SwiftNIO, have articles that use case-insensitive autolinks:


<!-- links -->
[module-core]: ./niocore
[module-posix]: ./nioposix
[module-embedded]: ./nioembedded
[module-concurrency-helpers]: ./nioconcurrencyhelpers
[module-embedded]: ./nioembedded
[module-foundation-compatibility]: ./niofoundationcompat
[module-http1]: ./niohttp1
[module-tls]: ./niotls
[module-websocket]: ./niowebsocket
[module-test-utilities]: ./niotestutils

[ch]: ./niocore/channelhandler
[c]: ./niocore/channel
[chc]: ./niocore/channelhandlercontext
[ec]: ./nioembedded/embeddedchannel
[el]: ./niocore/eventloop
[eel]: ./nioembedded/embeddedeventloop
[elg]: ./niocore/eventloopgroup
[bb]: ./niocore/bytebuffer
[elf]: ./niocore/eventloopfuture
[elp]: ./niocore/eventlooppromise
[cp]: ./niocore/channelpipeline
[mtelg]: ./nioposix/multithreadedeventloopgroup
[sb]: ./nioposix/serverbootstrap
[cb]: ./nioposix/clientbootstrap
[db]: ./nioposix/datagrambootstrap
[pthreads]: https://en.wikipedia.org/wiki/POSIX_Threads
[kqueue]: https://en.wikipedia.org/wiki/Kqueue
[epoll]: https://en.wikipedia.org/wiki/Epoll

it appears that the DocC engine does not even bother trying to resolve them, they just become relative URLs that the browser resolves, which means they only work if the article is bound to a module. (e.g., not a standalone article.) moreover, these links return 404 when viewed on GitHub.

when i feed the package into my own documentation tooling, the links fail to resolve because their casing does not match. (correctly-cased cross-target links do work.)

what is our policy towards all-lowercased symbol links?

2

the easiest way to resolve this issue turned out to just be updating the article source in NIO to use the correct casing. thanks to @lukasa for the speedy PR review!

3

A small but important clarification; symbol links in DocC were always case sensitive.

What previously made the symbol links appear to be case insensitive was that that Something and something used to have a name collision which meant that they needed to be written with both the correct capitalization and with disambiguation.

As of 5.9 symbols with different capitalization no longer need further disambiguation.

This looks to me like it's relying on the URLs that DocC creates for these pages being all lowercase. DocC intentionally lowercases symbol names in the URLs and it would be a very big breaking change to stop doing so.

IIRC this was done to avoid differences in behavior across servers with case sensitive and case insensitive URL handling.

My personal opinion about this is that symbol links (using the ``SymbolName`` syntax) should be capitalized the same way as those symbol names are capitalized when in source code.

DocC doesn't attempt to resolve regular web links (neither absolute not relative links) so a link that references a DocC page using a regular web link is essentially invisible to DocC.