Deprecated "character attributes" could be elaborated for the uninitiated

[lread]

As always: thanks so much for Asciidoctor, it is a wonderful tool!

I was experimenting with coloring text in asciidoctor and verifying the results in html (using the default asciidoctor css). Everything looks fine. My test document includes:

=== foreground color

We have a choice of 16 foreground colors: [aqua]#aqua# [black]#black#
[blue]#blue# [fuchsia]#fuschia# [gray]#gray# [green]#green# [lime]#lime#
[maroon]#maroon# [navy]#navy# [olive]#olive# [purple]#purple# [red]#red#
[silver]#silver# [teal]#teal# [white]#white# [yellow]#yellow#.

=== background color

The same 16 colors are available as background colors: [aqua-background]#aqua#
[black-background]#black# [blue-background]#blue# [fuchsia-background]#fuschia#
[gray-background]#gray# [green-background]#green# [lime-background]#lime#
[maroon-background]#maroon# [navy-background]#navy# [olive-background]#olive#
[purple-background]#purple# [red-background]#red# [silver-background]#silver#
[teal-background]#teal# [white-background]#white# [yellow-background]#yellow#

=== combinations

Roles can be combined, some examples:
[white black-background]#white on black-background#
[red yellow-background]#red on yellow background#
[big blue line-through fuchsia-background]#big blue line-through maroon-background#

I thought I was using roles appropriately but then I noticed in the docs that "character attributes" have been deprecated.

I could not find a definition nor syntax example for "character attributes". Is what I am doing above deprecated?

Once I understand what is what, I am happy to submit a PR with clarifications.

[lread]

As I dig into the asciidoctor user manual (it is really quite a wonderful manual) I see reference to custom styling with attributes which looks a lot like my samples above.

I'm going to assume these aren't the deprecated "character attributes" but would love confirmation from someone who knows.

[mojavelinux]

This is really more of a suggestion / best practice than an outright deprecation. In general, roles should be semantic rather than an alias for a visual style. There are numerous built-in roles in Asciidoctor (and AsciiDoc.py before it) that referred directly to a visual style. Those are as follows:

• big
• small
• (named colors)
• (named background colors)

These role names will not likely be mandated by the AsciiDoc language specification. And the named color roles are definitely going to be removed in a future version of Asciidoctor.

The underline, overline, and line-through roles likely won't be removed since they are just as much about the semantics as the style. So you probably don't have to worry about those.

For reference, the correct link to the docs page is this one: https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#inline-formatting

I realize that the built-in roles are not documented in the AsciiDoc language docs. I will open an issue there to document them. I will also put a stronger statement in about the named color roles being deprecated in the Asciidoctor docs.

[mojavelinux]

Done: https://docs.asciidoctor.org/asciidoc/latest/text/text-span-built-in-roles/

[lread]

Thanks @mojavelinux, much appreciated!