Skip to content

Commit

Permalink
Generators/Markdown: fix line break and indentation handling
Browse files Browse the repository at this point in the history
As things were, line breaks in a `<standard>` block were not respected for proper display in markdown.

As a side-effect of this, an indented text line in a `<standard>` block directly after a blank line, would unintentionally cause the markdown to display the line as a code block (via the indentation).

This has now been fixed by:
* Trimming indentation off each line.
* Adding two spaces to the end of each line as long as the line is not followed by a blank line or at the end of the standard block.
    The two spaces will ensure markdown will recognize the line break (in most markdown flavours).

Includes updated test expectations.

Refs:
* https://www.markdownguide.org/basic-syntax/#paragraph-best-practices
* https://www.markdownguide.org/basic-syntax/#line-break-best-practices
* https://daringfireball.net/projects/markdown/syntax#p
  • Loading branch information
jrfnl committed Nov 27, 2024
1 parent 941a00e commit ca4081c
Show file tree
Hide file tree
Showing 6 changed files with 38 additions and 18 deletions.
30 changes: 25 additions & 5 deletions src/Generators/Markdown.php
Original file line number Diff line number Diff line change
Expand Up @@ -117,14 +117,34 @@ protected function printTextBlock(DOMNode $node)
{
$content = trim($node->nodeValue);
$content = htmlspecialchars($content, (ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401));

// Use the correct line endings based on the OS.
$content = str_replace("\n", PHP_EOL, $content);

$content = str_replace('&lt;em&gt;', '*', $content);
$content = str_replace('&lt;/em&gt;', '*', $content);

echo $content.PHP_EOL;
$nodeLines = explode("\n", $content);
$lineCount = count($nodeLines);
$lines = [];

for ($i = 0; $i < $lineCount; $i++) {
$currentLine = trim($nodeLines[$i]);
if ($currentLine === '') {
// The text contained a blank line. Respect this.
$lines[] = '';
continue;
}

// Check if the _next_ line is blank.
if (isset($nodeLines[($i + 1)]) === false
|| trim($nodeLines[($i + 1)]) === ''
) {
// Next line is blank, just add the line.
$lines[] = $currentLine;
} else {
// Ensure that line breaks are respected in markdown.
$lines[] = $currentLine.' ';
}
}

echo implode(PHP_EOL, $lines).PHP_EOL;

}//end printTextBlock()

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Code Comparison, line length

Ensure there is no PHP &quot;Warning: str_repeat(): Second argument has to be greater than or equal to 0&quot;.
Ref: squizlabs/PHP_CodeSniffer#2522
Ensure there is no PHP &quot;Warning: str_repeat(): Second argument has to be greater than or equal to 0&quot;.
Ref: squizlabs/PHP_CodeSniffer#2522
<table>
<tr>
<th>Valid: contains line which is too long.</th>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

There is a blank line at the start of this standard.

And the above blank line is also deliberate to test part of the logic.
And the above blank line is also deliberate to test part of the logic.

Let&#039;s also end on a blank line to test that too.
Let&#039;s also end on a blank line to test that too.

Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Standard Element, handling of HTML tags

The use of *tags* in standard descriptions is allowed and their handling should be *safeguarded*.
Other tags, like &lt;a href=&quot;example.com&quot;&gt;link&lt;/a&gt;, &lt;b&gt;bold&lt;/bold&gt;, &lt;script&gt;&lt;/script&gt; are not allowed and will be encoded for display when the HTML or Markdown report is used.
The use of *tags* in standard descriptions is allowed and their handling should be *safeguarded*.
Other tags, like &lt;a href=&quot;example.com&quot;&gt;link&lt;/a&gt;, &lt;b&gt;bold&lt;/bold&gt;, &lt;script&gt;&lt;/script&gt; are not allowed and will be encoded for display when the HTML or Markdown report is used.

Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## Standard Element, indentation should be ignored

This line has no indentation.
This line has 4 spaces indentation.
This line has 8 spaces indentation.
This line has 4 spaces indentation.
This line has no indentation.
This line has 4 spaces indentation.
This line has 8 spaces indentation.
This line has 4 spaces indentation.

Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Standard Element, line wrapping handling

This line has to be exactly 99 chars to test part of the logic.------------------------------------
And this line has to be exactly 100 chars.----------------------------------------------------------
And here we have a line which should start wrapping as it is longer than 100 chars. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean pellentesque iaculis enim quis hendrerit. Morbi ultrices in odio pharetra commodo.
This line has to be exactly 99 chars to test part of the logic.------------------------------------
And this line has to be exactly 100 chars.----------------------------------------------------------
And here we have a line which should start wrapping as it is longer than 100 chars. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean pellentesque iaculis enim quis hendrerit. Morbi ultrices in odio pharetra commodo.

Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)

0 comments on commit ca4081c

Please sign in to comment.