Add space between property name and its description

[davegomez]

As you can see in the screenshot, when swift-doc publish the GitHub Wiki documentation, there is no separation between the property names and their description.

The lack of space between them is grammatically incorrect and also looks terrible.

[mattt]

Hi @davegomez. I'm unable to reproduce this issue. I just regenerated the documentation for SwiftSemantics, and everything looks fine.

Jumping into the code, here's the part responsible for what you'd see on the Home page in the wiki:

swift-doc/Sources/swift-doc/Supporting Types/Pages/HomePage.swift

Line 69 in 581af2f

Abstract(for: symbol, baseURL: baseURL).fragment

Here's the relevant line in the Abstract component:

swift-doc/Sources/swift-doc/Supporting Types/Components/Abstract.swift

Lines 23 to 26 in 581af2f

	#"""
	[\#(symbol.id)](\#(path(for: symbol, with: baseURL))):
	\#(summary)
	"""#

As you can see, there's a newline separating the colon and description, which is interpreted in CommonMark as a soft break and typically rendered as a space.

Could you please share more details about how you got these results?

[davegomez]

Hello @mattt, thank you for the swift response.

I checked the documentation of SwiftSemantics you shared, and it has the same issue.

As you can see in the following screenshot, there is no space after the colon:

This issue is happening in Chrome, Firefox, and Edge. The only browser rendering the space is Safari.

As you will be able to see in the following screenshots, the rendering of the string is quite literal in Chrome, Firefox, and Edge, while in Safari the string is joined to add the space after the colon correctly:

Chrome

Safari

These browsers are rendering the line break as zeroed width space &#8203, which is more of a line break control than space.

[mattt]

Thanks for clarifying, @davegomez. I've been doing web development for a long time and am no stranger to browser quirks, but this is weird and unexpected.

According to the GFM spec:

6.13 Soft line breaks

A regular line break (not in a code span or HTML tag) that is not preceded by two or more spaces or a backslash is parsed as a softbreak. (A softbreak may be rendered in HTML either as a line ending or as a space. The result will be the same in browsers. In the examples here, a line ending will be used.)

A conforming parser may render a soft line break in HTML either as a line break or as a space.

I can't say for sure, but I believe GitHub uses this library to render markdown on the site. I'm not 100% sure whether Wiki is doing something different.

Here's some Ruby code I used to try to reproduce this locally:

require 'github/markup'
GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, File.read(/Home.md"))

Running the code produces the following: https://gist.github.com/mattt/cd16d1b3c7757fb4fea6a0840a2f4b0e

Full HTML Output

<h1>Types</h1>\n<ul>\n<li><a href=\"./DeclarationCollector\">DeclarationCollector</a>:​\nA Swift syntax visitor that collects declarations.</li>\n<li><a href=\"./AssociatedType\">AssociatedType</a>:​\nAn associated type declaration.</li>\n<li><a href=\"./Class\">Class</a>:​\nA class declaration.</li>\n<li><a href=\"./ConditionalCompilationBlock\">ConditionalCompilationBlock</a>:​\nA conditional compilation block declaration.</li>\n<li><a href=\"./ConditionalCompilationBlock_Branch\">ConditionalCompilationBlock.Branch</a>:​\nA conditional compilation block branch.</li>\n<li><a href=\"./Deinitializer\">Deinitializer</a>:​\nA class deinitializer declaration.</li>\n<li><a href=\"./Enumeration\">Enumeration</a>:​\nAn enumeration declaration.</li>\n<li><a href=\"./Enumeration_Case\">Enumeration.Case</a>:​\nAn enumeration case.</li>\n<li><a href=\"./Extension\">Extension</a>:​\nAn extension declaration.</li>\n<li><a href=\"./Function\">Function</a>:​\nA function declaration.</li>\n<li><a href=\"./Function_Signature\">Function.Signature</a>:​\nA function signature.</li>\n<li><a href=\"./Function_Parameter\">Function.Parameter</a>:​\nA function parameter.</li>\n<li><a href=\"./Import\">Import</a>:​\nAn import declaration.</li>\n<li><a href=\"./Initializer\">Initializer</a>:​\nAn initializer declaration.</li>\n<li><a href=\"./Operator\">Operator</a>:​\nAn operator declaration.</li>\n<li><a href=\"./Operator_Kind\">Operator.Kind</a>:​\nThe kind of operator (prefix, infix, or postfix).</li>\n<li><a href=\"./PrecedenceGroup\">PrecedenceGroup</a>:​\nAn operator precedence group declaration.</li>\n<li><a href=\"./PrecedenceGroup_Associativity\">PrecedenceGroup.Associativity</a>:​\nThe associativity of an operator,\nwhich determines how operators of the same precedence\nare grouped in the absence of parentheses.</li>\n<li><a href=\"./PrecedenceGroup_Relation\">PrecedenceGroup.Relation</a>:​\nThe relation of operators to operators in other precedence groups,\nwhich determines the order in which\noperators of different precedence groups are evaluated\nin absence of parentheses.</li>\n<li><a href=\"./Protocol\">Protocol</a>:​\nA protocol declaration.</li>\n<li><a href=\"./Structure\">Structure</a>:​\nA structure declaration.</li>\n<li><a href=\"./Subscript\">Subscript</a>:​\nA subscript declaration.</li>\n<li><a href=\"./Typealias\">Typealias</a>:​\nA type alias declaration.</li>\n<li><a href=\"./Variable\">Variable</a>:​\nA declaration for a property or a top-level variable or constant.</li>\n<li><a href=\"./Variable_Accessor\">Variable.Accessor</a>:​\nA computed variable or computed property accessor.</li>\n<li><a href=\"./Variable_Accessor_Kind\">Variable.Accessor.Kind</a>:​\nThe kind of accessor (<code>get</code> or <code>set</code>).</li>\n<li><a href=\"./Attribute\">Attribute</a>:​\nA declaration attribute.</li>\n<li><a href=\"./Attribute_Argument\">Attribute.Argument</a>:​\nAn attribute argument.</li>\n<li><a href=\"./GenericParameter\">GenericParameter</a>:​\nA generic parameter.</li>\n<li><a href=\"./GenericRequirement\">GenericRequirement</a>:​\nA generic requirement.</li>\n<li><a href=\"./GenericRequirement_Relation\">GenericRequirement.Relation</a>:​\nA relation between the two types identified\nin the generic requirement.</li>\n<li><a href=\"./Modifier\">Modifier</a>:​\nA declaration modifier.</li>\n</ul>\n<h1>Protocols</h1>\n<ul>\n<li><a href=\"./Declaration\">Declaration</a>:​\nA Swift declaration.</li>\n<li><a href=\"./ExpressibleBySyntax\">ExpressibleBySyntax</a>:​\nA type that can be initialized with a Swift syntax node.</li>\n</ul>

The relevant detail here is the newline after the colons. In HTML, whitespace characters — including newlines — are collapsed into a single space between inline elements, which Safari appears to be doing (correctly). I could be missing something obvious, but I don't understand why Chrome and Firefox are behaving any differently.

<!-- Snip -->
<li><a href=\"./Class\">Class</a>:​\nA class declaration.</li>
<!-- Snip -->

Saving the output to a local file and opening in Safari, Chrome, and Firefox, I'm able to reproduce the behavior we see on GitHub with this minimal example. Searching around for any explanation hasn't yielded anything other than entry-level Stack Overflow questions about <br/> tags and the like...

---

So yeah, I'm genuinely curious about what's going on. But short of patching major browser engines, I want to make this work for SwiftDoc. I believe the fix should be as simple as bringing the interpolated summary on the same line as the link, and will have a PR to do that soon.

Edit: @davegomez I just tweeted about this to see if anyone could help explain what was going on here. Just wanted to give you a heads-up about that.