To $ or Not to $: Anzeige von Terminal-Code Snippets

Es ist sehr beliebt, ein $ vor Zeilen zu setzen, die als Befehl in der Dokumentation von Code, der das Terminal (d. h. die Kommandozeile) betrifft, gedacht sind.

So wie das

$ brew install somepackage

Der Sinn dahinter ist, dass es die Eingabeaufforderung nachahmt, die Sie möglicherweise auf Ihrer Kommandozeile sehen. Hier ist meine:

Das Dollarzeichen ($) ist also eine kleine Technik, die Leute verwenden, um anzuzeigen, dass diese Codezeile auf der Kommandozeile ausgeführt werden soll.

Kleinere Schwierigkeiten

Das Problem dabei ist, dass ich (und ich wette, die meisten anderen Leute auch) Befehle wie diese aus der Dokumentation kopieren und einfügen werde.

Wenn ich den obigen Befehl genau so, wie er geschrieben ist, in meinem Terminal ausführe…

…dann funktioniert er nicht. $ ist kein Befehl. Wie geht man damit um? Man muss es einfach wissen. Man muss dieses Problem schon einmal gehabt und irgendwie gelernt haben, dass das, was die Dokumentation tatsächlich aussagt, darin besteht, den Befehl brew install somepackage (ohne das Dollarzeichen) auf der Kommandozeile auszuführen.

Ich sage kleinere Schwierigkeiten, da es in jedem Beruf der Welt allerlei Dinge wie diese gibt. Wenn ich etwas wie font-size: 2.2rem in einen Blogbeitrag schreibe, sage ich nicht auch: „Fügen Sie diese Deklaration in eine Regelmenge in einer CSS-Datei ein, die Ihre HTML-Datei verlinkt.“ Das muss man eben wissen.

Behebung mit CSS

Die Tatsache, dass es sich nur um kleinere Schwierigkeiten handelt und die Technik voller Dinge ist, die man einfach wissen muss, bedeutet nicht, dass wir nicht versuchen können, dies zu beheben und uns ein wenig zu verbessern.

Die Idee für diesen Beitrag stammt aus diesem Tweet, der viel mehr Likes erhielt, als ich erwartet hatte

Wenn Sie wirklich denken, dass es verständlicher ist, ein $ in Docs für Terminalbefehle einzufügen, z. B.

$ brew install buttnugget

dann ist ein UX-Touch:

code.command::before {
content: "$ ";
}

damit ich es nicht kopiere, wenn ich den Befehl kopiere, und es im eigentlichen Terminal fehlschlägt.

— Chris Coyier (@chriscoyier) 5. Mai 2021

Um das zu erweitern, gehe ich davon aus, dass Sie Ihre Dokumente wahrscheinlich ungefähr so ​​formatieren:

<p>Install package like:</p>

<pre><code class="command">brew install package</code></pre>

Jetzt können Sie das $ als Pseudo-Element und nicht als tatsächlichen Text einfügen

code.command::before {
  content: "$ ";
}

Jetzt sparen Sie nicht nur ein Zeichen im HTML, das $ kann nicht ausgewählt werden, da Pseudo-Elemente so funktionieren. Sie sind also jetzt im UX-Bereich etwas besser. Selbst wenn der Benutzer auf die Zeile doppelklickt oder versucht, alles auszuwählen, erhält er nicht das $, das das Kopieren und Einfügen ruiniert.

Hoffentlich sind sie nicht gleichermaßen frustriert, weil sie das $ nicht kopieren können. 😬

Also, jedenfalls, etwas wie dieses unglaubliche Design von mir

Behebung mit Text

Viele Dokumentationen für Code-Dinge befinden sich an öffentlichen Git-Repository-Orten wie GitHub. Sie haben keinen Zugriff auf CSS, um das Aussehen von GitHub zu gestalten. Obwohl Tricksereien verfügbar sind, können Sie dort nicht einfach eine Zeile CSS einfügen, um Dinge zu formatieren.

Wir müssen (gasp) unsere Worte benutzen

<p>
  Install the package by entering this 
  command at your terminal:
</p>

<kbd class="command">brew install package</kbd>

Andere Gedanken

• Sie würden es wahrscheinlich gar nicht erst mit Syntax-Highlighting versehen. Ich glaube nicht, dass ich jemals ein Terminal gesehen habe, das Befehle syntaxhervorhebt, während Sie sie eingeben.
• Eric Meyer schlug das <kbd>-Element vor, das das Keyboard Input Element ist. Das gefällt mir. Ich habe lange Zeit <code> verwendet, aber ich denke, <kbd> ist hier angemessener.
• Tim Chase schlug vor, eine <span> zu verwenden und die Eingabeaufforderung in den HTML-Code aufzunehmen, damit Sie sie bei Bedarf einzigartig formatieren können, einschließlich der Möglichkeit, sie mit user-select: none; nicht auswählbar zu machen.
• Justin Searls hat einen Dotfiles-Trick, bei dem, wenn Sie versehentlich das $ kopieren/einfügen, es einfach ignoriert wird und alles danach ausgeführt wird.
• Jackson Bates rät zur Vorsicht beim Kopieren und Einfügen in ein Terminal.
• Ich habe erfahren, dass $ auch eine Möglichkeit ist, „nicht privilegierte“ Befehle zu bezeichnen, während # für Root-Befehle steht. Ein Teil des Grundes dafür ist, dass, wenn Sie einen Root-Befehl kopieren und einfügen, er nicht ausgeführt wird, da er als Kommentar erkannt wird.