UI macros markup with AsciiDoc

Project Discussion
1

In documentation pages, if the article describes interactions with keybindings and user interface (web or graphical software), It is possible to use AsciiDoc page or site attribute to mark up a keybindings or a button.

I see some markup is not rendered correctly because page or site attribute is not added.

Issues

Various conventions are used to describe ‘actions’ in words.

For consistency, docs writers and reviewers need to present a button, a keyboard, and keyboard bindings.

Suggestions

if the article you write or edit describes interactions with keybindings and user interface (web or graphical software), we could benefit from putting attributes onto the heading of .adoc page like below.

= Creating GPG Keys
:experimental:

What do you think?

1 Like
2

Sorry, just detected this. And I understand now your comment in the ticket.

To use a button representation makes the text better readable, I think. So we should encourage writers to use it. Maybe, we should add that to our guides.

Question is, include the experimental tag by default, or just for pages which use it? Generally I prefer the latter to keep everything small and lean. But in this case it may prevent a general usage of this feature.

On the other hand: can :experimental: negative effects?

3

That sounds like a plan.

4

No. Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc and used in latest Quick Docs edited.

I have added a paragraph and AsciiDoc examples.

Can you check this MR and approve?

1 Like
5

I would like to do, but darkao beat me to it :slight_smile:

1 Like