Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update dependency handlebars to v4 for mdman #13162

Closed
weihanglo opened this issue Dec 13, 2023 · 1 comment · Fixed by #13168
Closed

Update dependency handlebars to v4 for mdman #13162

weihanglo opened this issue Dec 13, 2023 · 1 comment · Fixed by #13168
Assignees
Labels
A-cli-help Area: built-in command-line help C-cleanup Category: cleanup within the codebase P-low Priority: Low S-accepted Status: Issue or feature is accepted, and has a team member available to help mentor or review

Comments

@weihanglo
Copy link
Member

weihanglo commented Dec 13, 2023

Problem

Renovate bot found a newer version available for dependency handlebars in #13090. handlebars is used by mdman for templatizing and generating man pages.

However, looks like the new version of handlebars does something different, so man pages are not generated correctly.

mdman's test suite was failed as well. Click to See details

 running 5 tests
test links ... FAILED
test tables ... ok
test formatting ... ok
test options ... FAILED
test vars ... FAILED

failures:

---- links stdout ----
thread 'links' panicked at crates/mdman/tests/compare.rs:25:9:

---- expected: tests/compare/expected/links.md
++++ actual:   In-memory
   1    1 | # links(1)
   2    2 | 
   3    3 | ## NAME
   4    4 | 
   5    5 | links - Test of different link kinds
          ⋮
  30   30 | 
  31   31 | [local-cmd(1)](local-cmd.html)
  32   32 | 
  33   33 | [Some link](foo.html)
  34   34 | 
  35      - <dl>
  36      - <dt class="option-term" id="option-links---include"><a class="option-anchor" href="#option-links---include"></a><code>--include</code></dt>
       35 + <dl><dt class="option-term" id="option-links---include"><a class="option-anchor" href="#option-links---include"></a><code>--include</code></dt>
  37   36 | <dd class="option-desc">Testing an <a href="included_link.html">included link</a>.</dd>
  38      - 
  39   37 | </dl>
  40      - 
  41      - 
  42   38 | ## OPTIONS
  43   39 | 
  44   40 | <dl>
  45      - 
  46   41 | <dt class="option-term" id="option-links---foo-bar"><a class="option-anchor" href="#option-links---foo-bar"></a><code>--foo-bar</code></dt>
  47   42 | <dd class="option-desc">Example <a href="bar.html">link</a>.
  48   43 | See <a href="https://example.org/commands/other-cmd.html">other-cmd(1)</a>, <a href="local-cmd.html">local-cmd(1)</a></dd>
  49   44 | 
  50      - 
  51   45 | </dl>
  52      - 
  53   46 | 
  54   47 | [bar]: https://example.com/bar
  55   48 | [collapsed]: https://example.com/collapsed
  56   49 | [shortcut]: https://example.com/shortcut

Update with SNAPSHOTS=overwrite
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

---- options stdout ----
thread 'options' panicked at crates/mdman/tests/compare.rs:25:9:

---- expected: tests/compare/expected/options.md
++++ actual:   In-memory
   1    1 | # my-command(1)
   2    2 | 
   3    3 | ## NAME
   4    4 | 
   5    5 | my-command - A brief description
          ⋮
  25   25 | ## OPTIONS
  26   26 | 
  27   27 | ### Command options
  28   28 | 
  29   29 | <dl>
  30      - 
  31   30 | <dt class="option-term" id="option-options---foo-bar"><a class="option-anchor" href="#option-options---foo-bar"></a><code>--foo-bar</code></dt>
  32   31 | <dd class="option-desc">Demo <em>emphasis</em>, <strong>strong</strong>, <del>strike</del></dd>
  33   32 | 
  34      - 
  35   33 | <dt class="option-term" id="option-options--p"><a class="option-anchor" href="#option-options--p"></a><code>-p</code> <em>spec</em></dt>
  36   34 | <dt class="option-term" id="option-options---package"><a class="option-anchor" href="#option-options---package"></a><code>--package</code> <em>spec</em></dt>
  37   35 | <dd class="option-desc">This has multiple flags.</dd>
  38   36 | 
  39      - 
  40   37 | <dt class="option-term" id="option-options-named-arg…"><a class="option-anchor" href="#option-options-named-arg…"></a><em>named-arg…</em></dt>
  41   38 | <dd class="option-desc">A named argument.</dd>
  42   39 | 
  43      - 
  44   40 | </dl>
  45      - 
  46   41 | ### Common Options
  47   42 | 
  48      - <dl>
  49      - <dt class="option-term" id="option-options-@filename"><a class="option-anchor" href="#option-options-@filename"></a><code>@</code><em>filename</em></dt>
       43 + <dl><dt class="option-term" id="option-options-@filename"><a class="option-anchor" href="#option-options-@filename"></a><code>@</code><em>filename</em></dt>
  50   44 | <dd class="option-desc">Load from filename.</dd>
  51   45 | 
  52      - 
  53   46 | <dt class="option-term" id="option-options---foo"><a class="option-anchor" href="#option-options---foo"></a><code>--foo</code> [<em>bar</em>]</dt>
  54   47 | <dd class="option-desc">Flag with optional value.</dd>
  55   48 | 
  56      - 
  57   49 | <dt class="option-term" id="option-options---foo[=bar]"><a class="option-anchor" href="#option-options---foo[=bar]"></a><code>--foo</code>[<code>=</code><em>bar</em>]</dt>
  58   50 | <dd class="option-desc">Alternate syntax for optional value (with required = for disambiguation).</dd>
  59   51 | 
  60      - 
  61   52 | </dl>
  62      - 
  63      - 
  64   53 | ## EXAMPLES
  65   54 | 
  66   55 | 1. An example
  67   56 | 
  68   57 |    ```
          ⋮
  73   62 | 
  74   63 |        my-command --xyz
  75   64 | 
  76   65 | ## SEE ALSO
  77   66 | [other-command(1)](other-command.html) [abc(7)](abc.html)

Update with SNAPSHOTS=overwrite

---- vars stdout ----
thread 'vars' panicked at crates/mdman/tests/compare.rs:25:9:

---- expected: tests/compare/expected/vars.md
++++ actual:   In-memory
   1    1 | # vars(7)
   2    2 | 
   3    3 | 
   4      - 
   5    4 | Bar
   6    5 | 
   7    6 | bar

Update with SNAPSHOTS=overwrite


failures:
    links
    options
    vars

test result: FAILED. 2 passed; 3 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s

Steps

  1. Clone rust-lang/cargo
  2. Run cargo build-man
  3. Found that man pages are generated corrupted.

Possible Solution(s)

Look into what have been changed in handlebars and update accordingly.

Notes

No response

Version

8412d308730f1932c4130d3b28ced0e22ecb2ddb
@weihanglo weihanglo added C-cleanup Category: cleanup within the codebase S-accepted Status: Issue or feature is accepted, and has a team member available to help mentor or review P-low Priority: Low A-infrastructure Area: infrastructure around the cargo repo, ci, releases, etc. labels Dec 13, 2023
@leonzchang
Copy link
Contributor

@rustbot claim

@weihanglo weihanglo added A-cli-help Area: built-in command-line help and removed A-infrastructure Area: infrastructure around the cargo repo, ci, releases, etc. labels Dec 14, 2023
bors added a commit that referenced this issue Dec 20, 2023
chore(deps): update rust crate handlebars to `v4.5.0`

In the latest version of `handlebars`, rules for whitespace auto elimination is to check if the directive `{{# xxx}}`` and ``{{/ xxx}}` is holding a whole line, with leading and trailing whitespaces counted, and then remove the trailing NEWLINE (See [`template.rs`](https://github.com/sunng87/handlebars-rust/blob/9d7d5556287e31e4148841a56e0981b64a679fb6/src/template.rs#L568-L889)).

```md
{{#options}}
                              <--- this newline will be removed after a standalone block
{{#option "`-o` _outdir_"}}
                              <--- this newline will be removed
Some content

{{/option}}
                              <--- this newline will be removed
{{/options}}
                              <--- this newline will be removed
```

This PR changes includes (fixes #13162):
1. update `handlebars` crate to `v4.5.0`.
2. add extra NEWLINE to helper blocks `options`, `option` to align with the new strip rules, preserving the original behavior.
3. update doc(the rest handlebars expression) to align with the new strip rules..
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-cli-help Area: built-in command-line help C-cleanup Category: cleanup within the codebase P-low Priority: Low S-accepted Status: Issue or feature is accepted, and has a team member available to help mentor or review
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants