New syntax design

The web and publishing continue to move forward at a rapid pace, and so must AsciiDoc. While the focus for AsciiDoc will always be on keeping markup to a minimum, new macros are necessary to keep up with the times. This page serves as a whiteboard for ideas about new syntax.

UI button

Purpose

To markup a reference to a UI button in a semantic way.

Proposals

Macro style 1

btn:[Save]
btn:[Comment & Close]
bnt:[{plus}]

Macro style 2

btn:Save[]
btn:Comment & Close[]
btn:{plus}[]

Related Issue

None

Menu item

Purpose

To markup a reference to a UI menu item in a semantic way.

Proposals

Shorthand style

File>New...
File>"New Tab"
View>"Highlight Mode">Markup>AsciiDoc

Macro style

menu:File[]
menu:File[Close]
menu:File[New,Message]

Related issue

#173

Key combination

Purpose

To markup a reference to a key binding in a semantic way.

Proposals

Macro style 1

key:Enter[]
key:Ctrl,S[]

Macro style 2

key:[Enter]
key:[Ctrl,S]
key:[Ctrl,Shift,T]

Shorthand style 1

<Enter>
<Ctrl><S>
<Ctrl><Shift><T>

Shorthand style 2

Ctrl+S
Ctrl+Shift+T

Related issue

None

File or path

Purpose

To markup a reference to a file or file system path in a semantic way.

Proposals

Macro style

path:/etc/hosts[]
path:/usr/share/gems[]

Literal text role

[path]+/etc/hosts+
[path]+/usr/share/gems+

If the path ends with a forward slash, we can assume it’s a directory and mark it as such. Another option is to have another prefix for directories:

path:/etc/[]
dir:/etc[]
[path]+/etc/+
[dir]+/etc+

Related issues

None