Some work on py-nutshell.rakudoc

[schultzdavid]

This will partly address issue #2354.

Note to self:

Add a rudimentary section on Raku's type system below the section on variables.
In this new section, include among other things the distinction between definite and indefinite objects.

In the section "Control flow", include (a little bit) of material on given and // – mostly to show what would be Raku equivalents of the common Python idiom if x is not None. Perhaps split the control flow section into the two subsections "Conditionals" (if, given, when...) and "Iteration" (while, for, loop...).

[schultzdavid]

here I replaced two dashes (rendered as two dashes) by an en dash

[arkiuat]

Wouldn't an em-dash be more appropriate here?

[schultzdavid]

I'm not sure.

Current factual usage in the docs is about evenly split between spaced en dashes and unspaced em dashes. (For the convenience of anyone wanting to check with a ripgrep: – and — )

The Wikipedia style says both are fine, just keep it consistent within a given article.

The Chicago Manual of Style and also a guide on technical writing do agree that unspaced em dashes should be used.

However, the text of the Raku docs is not being rendered via LaTeX or any other print-focused typesetting system, but instead (for most people) on the website and (for some people) in the rakudoc CLI tool.

• On the website, unspaced em dashes don't work so well with padded inline code, of which we have a lot. For example, take a look at the bottom of this section.
• In a CLI tool, with a monospace font, unspaced dashes are also problematic.

How others do it:

• The Python docs seem to consistently use spaced em dashes.
• The Ruby docs use em dashes, but very sparingly and not consistenly with regard to spacing
• The git man pages use em dashes. It seems like they prefer spaced ones (e.g. man git, man gitcli, man gitcore-tutorial, man git-blame), but some unspaced ones occur here and there (man gittutorial).

Personally I now tend toward using spaced em dashes, especially because of all the padded inline code on docs.raku.org, and because of the CLI. However, it's probably best if there's a consensus which one can then put into the styleguide.

[arkiuat]

My understanding is that the en dash has three particular use cases that call for it, and that this context isn't one of those.

https://en.wikipedia.org/wiki/Dash#En_dash says

The three main uses of the en dash are:

1. to connect symmetric items, such as the two ends of a range or two competitors or alternatives
2. to contrast values or illustrate a relationship between two things
3. to compound attributes, where one of the connected items is itself a compound

To offset a parenthetical remark, as here, an em dash is called for. I have no opinions about the whitespace; from what you say, it sounds as if it would work better with spaces around it.

If any of those en dashes that you found in the current docs are not examples of one of the three use cases mentioned above, they probably ought to be changed to em dashes.

[coke]

Since wikipedia says either, and the Tribune picks one, I’m happy to make that one the recommendation, add a style test for it, and then make sure we pass the test (and also add it to the styleguide) - Let’s move that into a new ticket and whatever we end up with for this PR is fine, we’ll fix it in post if we have to.

[coke]

Why split this code up?

[schultzdavid]

The intention was to have Python code and Raku code apart like elsewhere in the document to emphasize the shift in language (and to not have Raku code in a block marked as "Python highlighting"). But the example does work well the way it is, perhaps even better, so yes I think I'll revert it (and probably add comments # Python and # Raku to the right of each signature).

[coke]

Oh, I hadn’t even noticed they were not the same language - in that case, sorry, please separate them AND tag each with the right language attribute - the more raku code we can verify the better

[schultzdavid]

Ah, I see – I've done that now