--- title: "Style Guide" teaching: 10 exercises: 0 questions: - "How are keyboard key combinations written?" objectives: - "Explain keyboard key combination." keypoints: - "Keyboard keys need to use `` HTML tag." --- ## Emphasis Markdown treats asterisks (_*_) indicators of emphasis, and renders text marked up like this in italics. We use emphasis - to highlight a word, phrase, or character where it is itself the object of discussion. For example, ~~~ We want to output the lines that do not contain the word *the*. ~~~ {: .source} This is preferable instead of the use of quotation marks. See the "Keyboard Key" section for characters or keyboard keys that the learn should type. - for words and phrases that are still regarded as unfamiliar. - for titles of books, periodicals, plays, films, TV, radio series, and music albums. For example, ~~~ We will use a file that contains three haikus taken from a 1998 competition in *Salon* magazine. ~~~ {: .source} ## Strong Emphasis Markdown treats double asterisks (_**_) as indicators of strong emphasis, and renders text marked up like this in boldface. We use strong emphasis - to highlight a newly introduced term, often one that is going to be defined or explained. For example, ~~~ We are all familiar with **graphical user interfaces** ~~~ {: .source} ## Span of Code Markdown treats backtick quotes (_\`_) as indicators of a span of code. We use span of code - to highlight part of some code where it is itself the object of discussion. For example, ~~~ For example, `range(3, 10, 2)` produces ~~~ {: .source} - to highlight one command where it is itself the object of discussion. For example, ~~~ you can run it by opening a terminal and typing `bash`. ~~~ {: .source} When the object of discussion is the program or language in a broad sense, we don't use span of code. For example, ~~~ The most popular Unix shell is Bash. ~~~ {: .source} - to highlight one function where it is itself the object of discussion. For example, ~~~ `len` is much faster than any function we could write ourselves. ~~~ {: .source} - to highlight one file name where it is itself the object of discussion. For example, ~~~ `my_file.txt` can also be viewed in your GUI file explorer. ~~~ {: .source} - to highlight any sequence of character that the user is expected to type. ## Keyboard Key When making reference to a keyboard key that the reader should press the HTML tag `` **must** be used to enclose the key label. For example, "to delete the cell press D" should be write as ~~~ to delete the cell press D ~~~ {: .html} The table below covers most of the keyboard key labels. |-------------------+--------------------------------------------------------------------+--------------------------| | Keyboard key | Style Note | Example | |-------------------+--------------------------------------------------------------------+--------------------------| | Letters | Always capital. | `A` | |-------------------+--------------------------------------------------------------------+--------------------------| | Numbers | | `1` | |-------------------+--------------------------------------------------------------------+--------------------------| | Punctuation mark | | `*` | |-------------------+--------------------------------------------------------------------+--------------------------| | Function | Capital F followed by the number. | `F12` | |-------------------+--------------------------------------------------------------------+--------------------------| | Alt | Only first letter capital. | `Alt` | |-------------------+--------------------------------------------------------------------+--------------------------| | Backspace | Only first letter capital. | `Backspace` | |-------------------+--------------------------------------------------------------------+--------------------------| | Command | Only first letter capital. | `Command` | |-------------------+--------------------------------------------------------------------+--------------------------| | Ctrl | Only first letter capital. | `Ctrl` | |-------------------+--------------------------------------------------------------------+--------------------------| | Delete | Only first letter capital. | `Delete` | |-------------------+--------------------------------------------------------------------+--------------------------| | End | Only first letter capital. | `End` | |-------------------+--------------------------------------------------------------------+--------------------------| | Esc | Only first letter capital. | `Esc` | |-------------------+--------------------------------------------------------------------+--------------------------| | Home | Only first letter capital. | `Home` | |-------------------+--------------------------------------------------------------------+--------------------------| | Insert | Only first letter capital. | `Insert` | |-------------------+--------------------------------------------------------------------+--------------------------| | Page Down | Use "PgDn". | `PgDn` | |-------------------+--------------------------------------------------------------------+--------------------------| | Page Up | Use "PgUp". | `PgUp` | |-------------------+--------------------------------------------------------------------+--------------------------| | Print Screen | Use "PrtScr". | `PrtScr` | |-------------------+--------------------------------------------------------------------+--------------------------| | Return | Only first letter capital. We use "Return" instead of "Enter". | `Return` | |-------------------+--------------------------------------------------------------------+--------------------------| | Shift | Only first letter capital. | `Shift` | |-------------------+--------------------------------------------------------------------+--------------------------| | Spacebar | Only first letter capital. | `Spacebar` | |-------------------+--------------------------------------------------------------------+--------------------------| | Tab | Only first letter capital. | `Tab` | |-------------------+--------------------------------------------------------------------+--------------------------| | Down arrow | Use Unicode "Downwards arrow" (8595). | `↓` | |-------------------+--------------------------------------------------------------------+--------------------------| | Left arrow | Use Unicode "Leftwards arrow" (8592). | `←` | |-------------------+--------------------------------------------------------------------+--------------------------| | Right arrow | Use Unicode "Rightwards arrow" (8594). | `→` | |-------------------+--------------------------------------------------------------------+--------------------------| | Up arrow | Use Unicode "Upwards arrow" (8593). | `↑` | |-------------------+--------------------------------------------------------------------+--------------------------| ## Keyboard Key Combination When making reference to a keyboard key combination that the reader should press, insert a plus sign **without space** between each one of the keys. For example, "press Ctrl+X to quit nano" should be written as: ~~~ press Ctrl+X to quit nano. ~~~ {: .html} ## Links Please label links with meaningful texts, in order to [improve accessibility](https://webaccess.berkeley.edu/ask-pecan/click-here). Please avoid `click here` or similar. ## Title Casing Lesson and episode titles should be written in title case e.g. > Saving the World, One Commit at a Time An exception should be made where the title includes the name of a tool/library/command that must be typed in lower case when used, e.g. > Data Visualisation with `matplotlib` (In HTML files, such as the workshop schedule and syllabus files in the [workshop webpage template](https://github.com/carpentries/workshop-template), tool/command/library names such as `matplotlib` in the example above can be correctly formatted using `` tags.) {% include links.md %}