Stylistically disambiguate julia> in docstrings

[tecosaur]

If the styling is exactly the same, occasionally this can produce a bit of confusion or a double take when people mix it up with the REPL Julia prompt.

This has come up in OhMyREPL, and was brought up by @BioTurboNick after #54423 was merged.

There are a few ways we can try varying the style, here I've picked one of them so we've actually got a starting point for discussion: italic + different shade of green.

[mcabbott]

I agree it's confusing that the prompt in docstring examples is the same as the real prompt (only slightly indented). This change still seems very slight.

How about just removing the colour completely? Green is a "live" prompt, plain white/black is documentation.

[KristofferC]

OhMyREPL used red, people haven't complained about that.

[tecosaur]

I somewhat don't like red because it makes me think shell>, but it's just a default so I'm happy to PR whatever the general opinion is.

[mcabbott]

help?> is yellow, if it must be coloured then that might be the natural clue to pick up.

But really black/white seems fine -- leave colour for the top-level things, and make the whole block of examples pretty plain. They are all short (or should be!) so the text is clear enough (or should be made so!). No need to highlight every single level of sub-headings.

[fingolfin]

How short examples "should" be is IMHO very subjective and possibly depends on subject matter? Not everything can be demonstrated with a "short" example.

To me the colored prompts in examples are actually very helpful, for docstrings with examples that have a slightly long-ish output -- it makes it visually very easy to go from one input line to the next, skipping the output.

Granted, a similar effect would be attained for me if instead the output lines were shaded in gray or something like that.

[mcabbott]

My big complaint is that the extensive highlighting (new on 1.12 beta) breaks the biggest distinction you want to make visually, in favour of making tiny distinctions.

What I mean is this. When I ask for help inline at the REPL, my screen now has my input & output, and text & examples from help. Distinguishing those very clearly is the first concern. The second is clearly distinguishing text from example code, within the help. On 1.11 this is achieved by a small indent, and by making the whole example code block a different colour, which is great. Perhaps the 3rd concern is separating input from output within an example.

On 1.12, there is still an indent, but the example code blocks are very hard to spot. They use the same bright highlighting for the example prompt as for the real live prompt. And they use no less than 5 different colours to tell me which parts of sum(A; dims=3) are brackets, functions, and literals. That seems really the wrong focus, it's the 4th most important thing (in my counting).

I realise some people really love everything highlighted in as many colours as possible everywhere. That's why we have OhMyREPL. Maybe Base/REPL should provide hooks to make it easy for that to hook onto the example printing.

I also realise making this work was some work, and I don't want to disparage anyone. Maybe this work can still be made useful into OhMyREPL or something. But I'd vote to remove it from Base.

This PR makes a super-tiny change, to add italics to julia> prompts in docstring examples. That's really subtle and doesn't address this "what distinctions come first?" concern.

There might be other ways to address this concern. For instance, maybe help printing should have a bracket around it, like what @info prints. I think that at present this would break the ability to copy & paste examples to live prompt...

julia> │ julia> sind(45)
       │ 0.7071067811865476
       │
       │ julia> sinpi(1/4)
       └ 0.7071067811865475

ERROR: ParseError:
# Error @ REPL[225]:1:2

similar effect would be attained for me if instead the output lines were shaded in gray or something like that

This might be nice. This is what I called the 3rd distinction above. IMO experimenting with such things is the right level here. But really focused on what we want to achieve, and what we do not want to lose.

Not everything can be demonstrated with a "short" example.

That's true. But compared to real code, when writing examples you have more freedom to pick a nice compact presentation, and good names. Which makes tools for seeing through the thicket less important.

[tecosaur]

Granted, a similar effect would be attained for me if instead the output lines were shaded in gray or something like that.

On that note, there's been some conversation on Slack about this and it's probably worth sharing this screenshot here:

We can do this by querying the terminal background, which works pretty much everywhere (the Linux virtual console is the only exception I'm aware of, cmd.exe probably is another one).

The difficulty lies in how we capture the response.

[IanButterworth]

One thing that would make it clearer is help mode being within a pager which triage was in support of #41423
I haven't looked into that PR and importantly don't know if it always shows the pager footer even for short results.