Update documentation about "create -c"

[HealthyPear]

Description

Specify that the use of single quotes to retain RST or Markdow syntax.

Checklist

• [x] Make sure changes are covered by existing or new tests.
• [x] For at least one Python version, make sure local test run is green.
• [x] Create a file in src/towncrier/newsfragments/. Describe your change and include important information. Your change will be included in the public release notes.
• [x] Make sure all GitHub Actions checks are green (they are automatically checking all of the above).
• [x] Ensure docs/tutorial.rst is still up-to-date.
• [ ] If you add new CLI arguments (or change the meaning of existing ones), make sure docs/cli.rst reflects those changes.
• [ ] If you add new configuration options (or change the meaning of existing ones), make sure docs/configuration.rst reflects those changes.

[codecov[bot]]

Codecov Report

Base: 100.00% // Head: 100.00% // No change to project coverage :thumbsup:

Coverage data is based on head (0a440af) compared to base (826beac). Patch has no changes to coverable lines.

:exclamation: Current head 0a440af differs from pull request most recent head 670c0a4. Consider uploading reports for the commit 670c0a4 to get more accurate results

Additional details and impacted files

@@            Coverage Diff            @@
##             trunk      #477   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           13        13           
  Lines          627       622    -5     
  Branches       145       144    -1     
=========================================
- Hits           627       622    -5     

Impacted Files	Coverage Δ
src/towncrier/create.py	100.00% <0.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

:umbrella: View full report at Codecov.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

[HealthyPear]

Can you update the examples to match? It seems confusing that it shows double quotes, but then says you should use single quotes. Also, why not use double quotes? If someone needs to be told that single quotes are better, they're unlikely to know why.

Are you referring to the "Creating News Fragments" section? The examples there using this feature are already correct, that is the point of my PR: to specify why you need to use single quotes, which I did in the note box just after the example box.

[SmileyChris]

One problem with using single quotes is that "A single quote may not occur between single quotes, even when preceded by a backslash.". So...

towncrier create -c 'You can\'t do this!'

So technically, double quotes and appropriate escaping is a more complete option.

As an aside, I don't know if this needs a note on the tutorial. Personally I think it'd be fine to mention this only in the cli docs.

[exarkun]

One problem with using single quotes is that "A single quote may not occur between single quotes, even when preceded by a backslash.". So...

towncrier create -c 'You can\'t do this!'

So technically, double quotes and appropriate escaping is a more complete option.

In POSIX sh this works:

towncrier create -c 'You can'\''t not do this!'

As an aside, I don't know if this needs a note on the tutorial. Personally I think it'd be fine to mention this only in the cli docs.

I agree. Actually, I don't even know if it belongs in the cli docs. It's entirely up to the shell. Who is to say the user is even using a POSIX sh at all? They might be using PowerShell or fish or something.

[adiroiban]

Thanks for the feedback. I am closing this as won't fix.

I don't think that this is an towncrier issue.

It's just how various shell works... you can use towncrier on Linux, Unix, Window, with various shells ...and each might handle the arguments in different way