Expand delimiters if code contains backticks

[mtkraai]

Summary

Generated markdown was incorrect when an inline code block contained backticks.

Additional Context

Markdown inline code or fenced code blocks do not allow for the closing delimiter to be escaped. Instead, the length of the delimiter can be changed to accommodate any reasonable content.

I have also made the stylistic change of making single-line code strings longer than 70 characters into fenced blocks, so that the code displays in its original horizontal format, instead of being wrapped by the browser.

Examples

1. Backtick in data type:

The original case that prompted me to do this was a Pattern type that included a backtick in a character class.

type My_module::My_type = Pattern[/\A[- \w~`<>.,?\/"#]+\z/]

Which produced this:

Alias of `Pattern[/\A[- \w~`<>.,?\/"#]+\z/]`

And looks like this:

Alias of Pattern[/\A[- \w~<>.,?/"#]+\z/]`

After the change, it produces this:

Alias of ``Pattern[/\A[/\A[- \w~`<>.,?\/"#]+\z/]``

Which looks like this:

Alias of Pattern[/\A[/\A[- \w~`<>.,?\/"#]+\z/]

2. Fenced code in example:

This is the case I contrived to test the change as it applies to fenced blocks.

# @example Basic usage
#   $md_content = @(EndMD)
#     # Documentation
#     We're documenting something
#
#     ## Code
#     Here's a code example:
#
#     ```javascript
#     let x = 10;
#     ```
#
#     ## More Info
#     Lorem ipsum whatever.
#     | EndMD
#
#   my_module::markdown_file { '/srv/docs_md/something.md':
#     ensure  => 'file',
#     content => $md_content,
#   }

Which produced:

#### Examples

##### Basic usage

```puppet
$md_content = @(EndMD)
  # Documentation

  We're documenting something

  ## Code

  Here's a code example:

  ```javascript
  let x = 10;
  ```

  ## More Info

  Lorem ipsum whatever.
  | EndMD

my_module::markdown_file { '/srv/docs_md/something.md':
  ensure  => 'file',
  content => $md_content,
}
```

#### Parameters
…

And is broken like this:

Examples

Basic usage

$md_content = @(EndMD)
  # Documentation

  We're documenting something

  ## Code

  Here's a code example:

  ```javascript
  let x = 10;

More Info

Lorem ipsum whatever.
| EndMD

my_module::markdown_file { '/srv/docs_md/something.md':
ensure => 'file',
content => $md_content,
}

#### Parameters
…

After the change we get:

#### Examples

##### Basic usage

````puppet
$md_content = @(EndMD)
  # Documentation

  We're documenting something

  ## Code

  Here's a code example:

  ```javascript
  let x = 10;
  ```

  ## More Info

  Lorem ipsum whatever.
  | EndMD

my_module::markdown_file { '/srv/docs_md/something.md':
  ensure  => 'file',
  content => $md_content,
}
````

#### Parameters
…

Which displays correctly:

Examples

Basic usage

$md_content = @(EndMD)
  # Documentation

  We're documenting something

  ## Code

  Here's a code example:

  ```javascript
  let x = 10;
  ```

  ## More Info

  Lorem ipsum whatever.
  | EndMD

my_module::markdown_file { '/srv/docs_md/something.md':
  ensure  => 'file',
  content => $md_content,
}

Parameters

…

3. Long value:

To demonstrate the advantage of using block style for long values, I'll borrow a data type from the stdlib module.

Old:

Alias of `Enum['ACL', 'BASELINE-CONTROL', 'BIND', 'CHECKIN', 'CHECKOUT', 'CONNECT', 'COPY', 'DELETE', 'GET', 'HEAD', 'LABEL', 'LINK', 'LOCK', 'MERGE', 'MKACTIVITY', 'MKCALENDAR', 'MKCOL', 'MKREDIRECTREF', 'MKWORKSPACE', 'MOVE', 'OPTIONS', 'ORDERPATCH', 'PATCH', 'POST', 'PRI', 'PROPFIND', 'PROPPATCH', 'PUT', 'REBIND', 'REPORT', 'SEARCH', 'TRACE', 'UNBIND', 'UNCHECKOUT', 'UNLINK', 'UNLOCK', 'UPDATE', 'UPDATEREDIRECTREF', 'VERSION-CONTROL']`

Which renders:

Alias of Enum['ACL', 'BASELINE-CONTROL', 'BIND', 'CHECKIN', 'CHECKOUT', 'CONNECT', 'COPY', 'DELETE', 'GET', 'HEAD', 'LABEL', 'LINK', 'LOCK', 'MERGE', 'MKACTIVITY', 'MKCALENDAR', 'MKCOL', 'MKREDIRECTREF', 'MKWORKSPACE', 'MOVE', 'OPTIONS', 'ORDERPATCH', 'PATCH', 'POST', 'PRI', 'PROPFIND', 'PROPPATCH', 'PUT', 'REBIND', 'REPORT', 'SEARCH', 'TRACE', 'UNBIND', 'UNCHECKOUT', 'UNLINK', 'UNLOCK', 'UPDATE', 'UPDATEREDIRECTREF', 'VERSION-CONTROL']

New:

Alias of

```puppet
Enum['ACL', 'BASELINE-CONTROL', 'BIND', 'CHECKIN', 'CHECKOUT', 'CONNECT', 'COPY', 'DELETE', 'GET', 'HEAD', 'LABEL', 'LINK', 'LOCK', 'MERGE', 'MKACTIVITY', 'MKCALENDAR', 'MKCOL', 'MKREDIRECTREF', 'MKWORKSPACE', 'MOVE', 'OPTIONS', 'ORDERPATCH', 'PATCH', 'POST', 'PRI', 'PROPFIND', 'PROPPATCH', 'PUT', 'REBIND', 'REPORT', 'SEARCH', 'TRACE', 'UNBIND', 'UNCHECKOUT', 'UNLINK', 'UNLOCK', 'UPDATE', 'UPDATEREDIRECTREF', 'VERSION-CONTROL']
```

And that looks like this, which I think is more code-like and a little easier to read, even though the whole thing can't be seen at once:

Alias of

Enum['ACL', 'BASELINE-CONTROL', 'BIND', 'CHECKIN', 'CHECKOUT', 'CONNECT', 'COPY', 'DELETE', 'GET', 'HEAD', 'LABEL', 'LINK', 'LOCK', 'MERGE', 'MKACTIVITY', 'MKCALENDAR', 'MKCOL', 'MKREDIRECTREF', 'MKWORKSPACE', 'MOVE', 'OPTIONS', 'ORDERPATCH', 'PATCH', 'POST', 'PRI', 'PROPFIND', 'PROPPATCH', 'PUT', 'REBIND', 'REPORT', 'SEARCH', 'TRACE', 'UNBIND', 'UNCHECKOUT', 'UNLINK', 'UNLOCK', 'UPDATE', 'UPDATEREDIRECTREF', 'VERSION-CONTROL']

Related Issues (if any)

I did not find anything related. The original code comments do mention the omission.

Tests

I did not find any test that directly tests the code_maybe_block() function, or I would have added a couple of test cases. Additionally, the the test that might apply is very simplistic, and additions that would properly test this function and change would, I think, substantially change the existing test in ways I don't know if they would be acceptable.

• 🟢 Spec tests.
• 🟢 Acceptance tests.
• Manually verified.
  In addition to testing with my own modules, I ran the puppetlabs/stdlib and puppetlabs/apache modules through this. When I diffed the results, the only changes were as expected.

[CLAassistant]

All committers have signed the CLA.

[bastelfreak]

@mtkraai could you share an example how it looked in the past VS how it looks now?

[mtkraai]

I have updated the PR top post with an example of the inline case.

However, when trying to contrive a reasonable example of a block case, I found that the template does not call this function for the location of my example. I tried updating the templates to call code_maybe_block() from more places, but it's not working yet.

I'd like to finish expanding the improvements, but it will take some time to troubleshoot (working around my regular work).

[mtkraai]

@bastelfreak I made additional changes, did more testing, and updated the PR top comment.

[mtkraai]

Apologies for the force pushes, I accidentally used my work profile for the update commits.