Bad representation of expressions with "-"

Documentation
1

The following code snippet is extracted from this documentation page (first code block):

class EnumName([mix-in, ...,] [data-type,] base-enum):

The terms in and type are formatted with special styling – bold and color. This styling should be applied when these terms appear independently, but this is not the case here.
It seems that the “-” character splits the expression into individual terms, and each of them is formatted separatly.

Now I see that something similar happened here too, in, data and enum received special styling.

I’m sure this is not the only case where this problem occurs.

1 Like
2

The issue here isn’t the syntax highlighting, it’s behaving as best it can given the circumstances, correctly showing in as a keyword and type as a builtin (which, indeed, they both would be in that input, if it were valid). Indeed, the syntax highlighting on Discourse shows the exact same thing:

class EnumName([mix-in, ...,], [data-type,] base-enum):
    pass

Something like the following uses valid Python syntax for names, more obviously invalid syntax for placeholders, and highlights less obtrusively and more as intended:

class EnumName([<mix_in>, ...,] [<data_type>,] <base_enum>):
    pass

@stoneleaf , what do you think? If we can agree on a better alternative here, @davem14 you could submit it as a Pull Request to the docs (and backport it accordingly).

2 Likes
3

Since the example is showing optional values in square brackets (i.e., not using actual Python syntax, as a list etc. would be nonsensical there), I think this should be following the other usual conventions… in which case, I would expect the names to be set in italics.

4

The root cause (for the docs, can’t speak for Discourse) will likely be Pygments, who may be able to update their lexer to reject invalid syntax such as an immediate leading or trailing hyphen: https://pygments.org/

cc @jeanas as one of the maintainers

A

1 Like
5

What about disabling syntax highlighting for this code block? It is not valid syntax in any language, so why try to enforce syntax highlighting on it?

6

That’s also a possibility, though given some modest tweaks both clarify the example and allow pygments to highlight what it can while not highlighting what isn’t valid Python, it seems reasonable to retain the highlighting language in this case.

7

Is there any reason for the example to use invalid identifiers like mix-in instead of just using mixin or mix_in?

8

I personally don’t see so, at least not internally to the identifiers, as they are supposed to be valid Python identifiers, just example ones. As such, in my proposed revision I’d made them so, but followed standard convention of wrapping them in (clearly invalid) angle brackets to make clear they were placeholders.

9

I guess I was thinking of it more like the documentation for library functions, etc., where there isn’t even the need for angle brackets, and the identifiers are just “variables” that indicate where you would pass in a real value. I suppose it is a bit different since this is more like a code snippet than just a function signature, but I still think it would probably be fine to just have:

class EnumName([mixins...,] [data_type,] base_enum):
    pass

(Hopefully the highlighting won’t highlight those as lists like it does in this forum. :slight_smile: But it seems like it’s not doing that with the current example anyway. . .)

10

I’m happy with underscores (_) instead of dashes (-).

1 Like