kai687 / sphinxawesome-sampdirective Goto Github PK

I have to think a bit more about semantics of this construct. I made the following observations:

• The Sphinx :samp: role: A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part Sphinx doc
• The HTML <samp> element: enclose inline text which represents sample (or quoted) output from a computer program. MDN
• The intended semantics for the <samp> element seems to be narrower then that of the :samp: reStructuredText role.

How I've used it mostly was to mark up a placeholder for user input. User input is supposed to be marked up by the <kbd> element:

• represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device. MDN There are examples on that page on how to represent user input in various combinations
• The Sphinx :kbd: role: Mark a sequence of keystrokes. Sphinx doc
• it looks like the Sphinx role is narrower in semantic (key combos rather than generic user input).

Currently, the placeholder part is an 'emphasis' token, with a class of var for variable part. It is maybe ok to leave it like that. In HTML, this becomes <em class="var">.

I think, mostly I want to be able to mark up "an inline character sequence that is a placeholder that the user has to replace with the actual text", such as username, URL, etc.

Maybe better would be <code class="placeholder"> because it could be either program output or user input. (Although echoed user input is probably <kbd> inside <samp>?

Changing the returned node type would be a breaking change.

This should get a highlighted prompt character:

$ echo "Something"

This should not:

$HOME/.bin/something

Write a test for

.. samp:: 

   $ do stuff /here/{PLACEHOLDER}/ 

And if that works fine, write another test for {PLACE_HOLDER}. I might need to modify the token regex.
It would also be nice to log the token/node list after parsing on debug level.

This issue is related to kai687/sphinxawesome-theme#45

This will not be parsed correctly by the directive:

stuff = { "item" : "{PLACEHOLDER}" }

If I can find out, how to only take the innermost pair or curly braces as placeholder, I can fix it.

• empty set {} should be rendered as text
• escaped curly braces should be rendered as single curly braces
• single curly braces { or } should be rendered as text

(Spun off from issue #4 and pull request #5)