Ambiguity with notating commands

[Winterhuman]

What is the issue with the HTML Standard?

<code>: "The code element represents a fragment of computer code. This could be an XML element name, a filename, a computer program, or any other string that a computer would recognize."

<kbd>: "The kbd element represents user input (typically keyboard input, although it may also be used to represent other input, such as voice commands)."

Given the above definitions, you could argue that a command could fit inside a <code> or <kbd> element depending on context; it isn't clear which one is most semantically-correct.

Some cases seem unambiguous. <pre>-<samp> blocks use <kbd> for commands within the sample block, since a user typed those parts of the text:

<pre><samp><span class="prompt">jdoe@mowmow:~$</span> <kbd>ssh demo.example.com</kbd>
Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1
Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown

<span class="prompt">jdoe@demo:~$</span> <span class="cursor">_</span></samp></pre>

But, what about outside of <samp>? If I state "The command command can be used to ...", then I'm not telling a user to give this input; I'm simply stating a user could type this (compared to "First, execute command ...").

1. ~~Does <kbd> imply a user did type something, or does it also semantically indicate that a user is able to type something?~~ See the following comment for my interpretation.

2. If specified by name vs. by path, would command and /bin/command be notated differently? <code> can semantically mean a filename, implying only <code>/bin/command</code> is correct, but it could be user input too.

3. If a command is using shell-specific syntax, like command >/dev/null 2>&1 for a POSIX-compliant shell, which element is more appropriate? Perhaps both?

4. And if both <code> and <kbd> elements can be simultaneously semantically correct for a command, which element should nest which? Should it depend on context?

Apologies in advance if I've missed a document which explains this in more detail. Let me know what you think!

[Winterhuman]

Further thoughts:

• When <kbd> is nested inside <samp>, with or without <pre>, <kbd> represents the user input that was typed. Therefore, using <samp>-<kbd> to represent a command a user could type doesn't seem correct.
• Keyboard shortcuts (aka. <kbd>-<kbd> or <kbd>-<samp> nestings) do seem to represent things the user can type, but didn't necessarily do at that moment. However, <kbd>-<samp> is intended for notating the names of clickable GUI buttons; commands don't work here either.
• So, based on my interpretation, <samp> (wrapped outside of <kbd>) is what encodes the semantic information that something happened in the past; it's output that has been generated. Therefore, <kbd>command</kbd> could be interpreted as a suggestion just as a keyboard shortcut would be.

My proposal is this: specify a <code>-<kbd> nesting (e.g. <code><kbd>command</kbd></code>) that semantically describes a piece of user input that is valid for execution.

• <code><kbd>/path/to/normal/file</kbd></code> would be incorrect, because file isn't an executable. It is, however, perfectly valid if only <code> or <kbd> was used; <code> can be used for file paths, or the path is user input.
  • A possible exception to this would be if the shell had special functionality that activated if it tried to "execute" a path to a non-executable file (e.g. prompting the user for how they want to proceed); in which case, <code>-<kbd> would actually be correct.
• <code>command</code> is valid, but ambiguous. It could be describing a command that can be ran by the user, but it could also be describing a command that was previously denoted inside a <pre>-<code> or <pre>-<samp> block earlier in the text (e.g. <p>The <code>command</code> in the script written above...</p>).
  • Since this is currently the most common way people notate commands, treating this as invalid would probably be too disruptive.
• And finally, <code><kbd>command</kbd></code>, <code><kbd>/path/to/command</kbd></code>, & <code><kbd>command >/dev/null 2>&1</kbd></code> would all be valid, as they are all keyboard inputs that a computer program (like a shell) could parse and execute as-is.
  • As an example of invalid usage: <p>As seen above, the <code><kbd>if [ "$var" -gt 4 ]; then</kbd></code> line...</p> is invalid because trying to execute if [ "$var" -gt 4 ]; then would be invalid syntax (no fi to close it); this string isn't directly executable (an exception is made for <var>, where a valid value is implied to be in its place). Using only <code> here would be more correct semantically.

[!NOTE] This is purely informational in purpose to generate discussion; I don't intend to submit this as a proposal myself.