Hard breaks aren't reflected in output

[amartini51]

Description

The CommonMark spec allows writers to specify a line break (not a paragraph break) by writing two or more spaces at the end of the line, or by writing a backslash (\) at the end of the line. Currently, the rendered content from DocC doesn't break the line at that location.

Example input:

This text should\
appear on two lines.

This is the second paragraph.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

rdar://101684224

[ethan-kusters]

Thanks for filing this @amartini51!

CC: @QuietMisdreavus

It looks like this fix should be in RenderContentCompiler here:

swift-docc/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

Lines 227 to 229 in 61100a4

	mutating func visitLineBreak(_ lineBreak: LineBreak) -> [RenderContent] {
	return [RenderInlineContent.text(" ")]
	}

.

[Kyle-Ye]

Thanks for filing this @amartini51!

CC: @QuietMisdreavus

It looks like this fix should be in RenderContentCompiler here:

swift-docc/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

Lines 227 to 229 in 61100a4

	mutating func visitLineBreak(_ lineBreak: LineBreak) -> [RenderContent] {
	return [RenderInlineContent.text(" ")]
	}

It looks to be a swift-markdown bug for me.

import Markdown
let string = """
This text should\
appear on two lines.

This is the second paragraph.
"""
let document = Document(parsing: string)
print(document.debugDescription())

// Document
// ├─ Paragraph
// │  └─ Text "This text shouldappear on two lines."
// └─ Paragraph
//    └─ Text "This is the second paragraph."

Also even if I add such text to a docc markdown file, and run docc preview on it. The method visitLineBreak does not seem to be called.

[ethan-kusters]

Hm okay. Let's transfer this issue over there for now then. We can file a new issue on Swift-DocC if it turns out a fix is needed across both repos.

[Iikeli]

Works fine for swift-markdown. Notice that you escape with \ the new line being created in the multiline string. If you wanted to use the backslash, then you need to escape that (with another backslash). See: https://docs.swift.org/swift-book/LanguageGuide/StringsAndCharacters.html

let source = """
             Paragraph.\\
             Still the same paragraph.

             Different paragraph
             """
let document = Document(parsing: source)

print(document.debugDescription())

// Document
// ├─ Paragraph
// │  ├─ Text "Paragraph."
// │  ├─ LineBreak
// │  └─ Text "Still the same paragraph."
// └─ Paragraph
// └─ Text "Different paragraph"

[Kyle-Ye]

import Markdown

// Two space at the end of line 4 of string
let string = #"""
This text should\
appear on two lines.

This text should  
appear on two lines.

This is the second paragraph.
"""#
let document = Document(parsing: string)
print(document.debugDescription())

Document
├─ Paragraph
│  ├─ Text "This text should"
│  ├─ LineBreak
│  └─ Text "appear on two lines."
├─ Paragraph
│  ├─ Text "This text should"
│  ├─ LineBreak
│  └─ Text "appear on two lines."
└─ Paragraph
   └─ Text "This is the second paragraph."

As @Iikeli explained, I forgot to escape the "\". So the markdown has no problem identifying linebreak for 2 spaces and "\".

It looks like this fix should be in RenderContentCompiler here:

swift-docc/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

Lines 227 to 229 in 61100a4

	mutating func visitLineBreak(_ lineBreak: LineBreak) -> [RenderContent] {
	return [RenderInlineContent.text(" ")]
	}

.

If we change the function to return "\n" for RenderInlineContent

mutating func visitLineBreak(_ lineBreak: LineBreak) -> [RenderContent] {
    return [RenderInlineContent.text("\n)]
}

the output json file in .docc-build/data/documentation/demokit.json is expected as follows

{
    "primaryContentSections": [
        {
            "kind": "content",
            "content": [
                ...
                {
                    "type": "paragraph",
                    "inlineContent": [
                        {
                            "type": "text",
                            "text": "This text should"
                        },
                        {
                            "type": "text",
                            "text": "\n"
                        },
                        {
                            "type": "text",
                            "text": "appear on two lines."
                        }
                    ]
                },
                ...
            ]
        }
    ],
    ...
}

But swift-docc-render (Xcode 14.2 Swift toolchain) will still render the paragraph in one line.

So maybe the issue needs a swift-docc and swift-docc-render cross PR to fix.

Could you help transform the issue back to swift-docc @ethan-kusters ? And when the cross PR is ready, I'll file a new issue on swift-docc-render repo.

[gwynne]

Is there any hope of some motion on this? Still hasn't been fixed as of the Xcode 15 beta/Swift 5.9

[Kyle-Ye]

Is there any hope of some motion on this? Still hasn't been fixed as of the Xcode 15 beta/Swift 5.9

Sorry, I almost forgot the issue 😢. Thanks for the reminding.

[Kyle-Ye]

Is there any hope of some motion on this? Still hasn't been fixed as of the Xcode 15 beta/Swift 5.9

I've added the swift-docc PR via #633 and created the corresponding issue to swift-docc-render via apple/swift-docc-render#697. When both of them are ready, the issue will be closed.

Then we may consider cherry-pick this back to the release/5.9 branch.

[Kyle-Ye]

Is there any hope of some motion on this? Still hasn't been fixed as of the Xcode 15 beta/Swift 5.9

The fix had landed on main branch of swift-docc and swift-docc-render. And we are cherry-picking it back to release/5.9.

[mportiz08]

Both PRs have been merged and also cherry-picked to release/5.9 now :)