Тег samp (от английского sample, «образец») отмечает пример вывода программы: сообщение, ошибку, результат команды. Так ответ компьютера отделяют от слов автора и от того, что вводит сам читатель. Тег парный, закрывающий обязателен, собственных атрибутов у него нет. Браузер выводит его моноширинным шрифтом и больше ничего не добавляет.
Чем samp отличается от kbd, как записать вывод в несколько строк, как сделать сеанс, который удобно копировать, как отметить сообщения с подстановкой и логи, как оформить вывод в CSS и когда вместо samp нужен output, - ответы ниже.
<p>Программа ответила:
<samp>Файл не найден</samp>.</p>В этой статье
- Тег samp в HTML: что это и для чего нужен
- Тег samp и kbd: что вводит человек и что отвечает программа
- Вывод в несколько строк: тег samp внутри pre
- Копирование вывода samp: как не захватить приглашение командной строки
- Тег samp и var: сообщение с подстановкой и подбор тегов для сеанса
- Тег samp для логов и ответов сервера: обычный вывод и ошибки
- Стили тега samp: оформление вывода как в терминале
- Тег samp или output: результат скрипта на странице
- Частые ошибки с тегом samp
Тег samp в HTML: что это и для чего нужен
Спецификация HTML описывает samp как пример вывода программы или системы, а справка MDN (на английском) говорит о том же: встроенный текст, который представляет образец, а иногда и цитату вывода программы. Читателю показывают то, что программа написала сама: «Готово», Ошибка 404 или список файлов.
Браузер выводит samp моноширинным шрифтом, прямым, без подчёркивания и фона. Размер такой же, как у code: 13 px, когда у родителя размер не задан в пикселях, а при заданном размере текст равен ему. Подробнее об этом написано в разделе про размер шрифта страницы про code.
Отличить samp от code и kbd по виду нельзя: по умолчанию все три выглядят одинаково. Разница в смысле: code - фрагмент кода, kbd - ввод с клавиатуры, samp - ответ программы. Смысл виден только тогда, когда его отделяют стили или программа, читающая разметку.
Тег samp и kbd: что вводит человек и что отвечает программа
Ввод и ответ идут парой: человек вводит команду ls, программа отвечает списком файлов. Команду отмечают тегом kbd, ответ - тегом samp. Когда показывают целый сеанс, kbd вкладывают в samp: всё, что видно на экране терминала, находится внутри одного samp, а введённое человеком выделено отдельно. Такую запись показывает и справка MDN.
<pre><samp>user@host:~$ <kbd>ls</kbd>
notes.txt photos
</samp></pre>Приглашение командной строки - строка, которую программа выводит перед местом ввода, например user@host:~$. Она остаётся обычным текстом внутри samp: её вывела программа, человек её не вводил. Если нужно показать только то, что ввести читателю, ответ не нужен, достаточно одного kbd.
Пример: сеанс в терминале
Выберите команду или введите свою. Кадр выполняет её, добавляет в сеанс и показывает разметку последней команды: ввод внутри kbd, приглашение и ответ обычным текстом внутри samp.
Вывод в несколько строк: тег samp внутри pre
Один samp не сохраняет переносы строк: в Chrome текст из двух строк в нём занимает одну строку, а лишние пробелы схлопываются. Для вывода в несколько строк samp записывают внутри pre: pre сохраняет пробелы и переносы, а samp остаётся смысловой пометкой.
<pre><samp>Готово:
файлов: 3
ошибок: 0
</samp></pre>Порядок вложения один: samp внутри pre. Тег samp строчный, а pre блочный, и блок внутри строчного тега не допускается. Про перенос строки после открывающего тега, отступы и длинные строки подробно написано на странице про pre.
Весь вывод можно оставить в одном samp, а можно отмечать каждую строку отдельным samp. Второй способ нужен, когда строки оформляют по-разному, например обычный вывод и ошибки. Об этом написано в разделе про логи и ответы сервера.
Копирование вывода samp: как не захватить приглашение командной строки
Читатель часто копирует сеанс, чтобы выполнить его в своём терминале. Если приглашение командной строки записано обычным текстом, оно попадёт в копию вместе с командой, и скопированная строка не сработает: приглашение станет частью команды.
Есть два способа исключить приглашение из копии. Его можно записать в span со свойством user-select: none или вывести из CSS через ::before. В Chrome в обоих случаях приглашение остаётся на экране, а в буфер обмена не попадает. Замеры сделаны в Chrome, в других браузерах поведение стоит проверить.
<samp><span class="prompt">$ </span><kbd>ls</kbd>
notes.txt photos
</samp>.prompt {
user-select: none;
}Способ с ::before выводит приглашение из стилей, поэтому в разметке его нет: читатель без стилей и программы, которые читают текст страницы, приглашения не увидят. Способ с user-select оставляет приглашение в тексте страницы, просто оно не копируется.
Пример: что попадёт в буфер обмена
Три способа записать приглашение. Кадр выделяет весь блок, читает выделение так же, как при копировании, и показывает, что попадёт в буфер обмена.
Тег samp и var: сообщение с подстановкой и подбор тегов для сеанса
В сообщениях, которые показывают в документации, часто есть меняющаяся часть: название файла, номер, адрес. Её отмечают тегом var внутри samp, например Файл название не найден. Читатель понимает, что вместо слова «название» в настоящем сообщении будет его значение.
<samp>Файл <var>название</var> не найден</samp>Внутри samp тег var остаётся курсивным, поэтому изменяемая часть заметна в моноширинной строке. Если вы описываете конкретный ответ, где название файла известно, оставляйте его обычным текстом: «Файл notes.md не найден».
Разобрать сеанс по тегам - значит для каждого фрагмента ответить: это ввод человека, ответ программы, изменяемая часть, код или обычное слово. Для каждого ответа свой тег.
Пример: какой тег нужен фрагменту
Нажимайте на слова в рамках, и тег меняется по кругу. Кадр строит разметку и проверяет, у каждого ли фрагмента подходящий тег.
Тег samp для логов и ответов сервера: обычный вывод и ошибки
Тег samp подходит не только для терминала. Им отмечают строки лога, ответ команды проверки связи, тело ответа сервера, которое вы показываете в документации к API. Пока это вывод, который написала программа, а не код и не ввод, тег выбран верно.
<pre><samp>{ "status": "ok", "count": 3 }
</samp></pre>Если у вывода есть обычные строки и ошибки, каждую строку можно отметить своим samp с классом, а вид задать в CSS: обычный вывод остаётся спокойным, ошибка получает цвет. Класс не меняет смысл тега: обе строки остаются выводом программы.
<pre><samp>Готово: 3 файла</samp>
<samp class="error">Ошибка: диск полон</samp></pre>.error {
color: #c0292e;
}Ответ сервера в формате JSON или заголовки HTTP - тоже вывод, поэтому им подходит samp внутри pre. А файл настроек, который читатель должен записать у себя, - это code: его не выводит программа, его пишет человек.
Стили тега samp: оформление вывода как в терминале
По умолчанию samp - моноширинный текст без фона и рамки. Размер зависит от родителя: в обычном абзаце 13 px, в заголовке 19,5 px (в полтора раза больше), а если у родителя размер задан в пикселях, текст равен ему. Курсива и подчёркивания нет, но внутри em или i он становится курсивным.
Оформление вывода как в терминале задают на pre, а не на samp: тёмный фон, светлый текст, отступы. Сам samp можно оставить без стилей.
pre.terminal {
background: #1F2430;
color: #e8e6df;
padding: 12px 16px;
border-radius: 8px;
}Ввод и вывод в таком блоке различают цветом: у kbd свой цвет, а samp остаётся основным. Такой вид показан в первом примере этой статьи.
pre.terminal kbd {
color: #ffd479;
}Тег samp или output: результат скрипта на странице
Тег samp отмечает вывод, который показала другая программа. Если результат считает скрипт на вашей странице, например сумму чисел в форме, подходит другой тег - output. Об этом предупреждает и справка MDN.
<output for="a b">5</output>Тег output - элемент формы. У него есть свойство value и атрибут for со списком полей, из которых считается результат. При сбросе формы output возвращается к начальному значению, а при отправке формы он не передаётся. У samp этого нет: это только текст. В Chrome у output нет моноширинного шрифта, он выглядит как окружающий текст.
| Тег | Что он отмечает | Когда выбрать |
|---|---|---|
samp | Вывод, который показала другая программа | Сообщение, ошибка, результат команды |
output | Результат вычисления на вашей странице | Сумма в форме, итог калькулятора |
| code | Код | Фрагмент, который читатель запишет у себя |
kbd | Ввод с клавиатуры | Команда или клавиша, которую вводит читатель |
| var | Переменная или заполнитель | Меняющаяся часть сообщения или команды |
Пример: output и samp при сбросе формы
Измените числа и нажмите «Сбросить форму». Поля и output вернутся к начальным значениям, а samp останется с прежним текстом.
Частые ошибки с тегом samp
Ошибки с этим тегом связаны с тем, что его путают с соседями по смыслу и не учитывают переносы строк.
| Ошибка | Что происходит | Как исправить |
|---|---|---|
Ввод в теге: <samp>ls</samp> | Команду вводит человек, а не выводит программа | <kbd>ls</kbd> |
Код в теге: <samp>function area(r) {}</samp> | Код пишет человек, программа его не выводит | <code>function area(r) {}</code> |
Результат своего скрипта: <samp id="sum">5</samp> | Это результат вычисления на странице, а не вывод чужой программы | <output for="a b">5</output> |
Несколько строк без pre: <samp>Готово: перенос файлов: 3</samp> | Переносы схлопываются, всё выходит в одну строку | Записать samp внутри pre |
Блок внутри тега: <samp><pre>...</pre></samp> | samp строчный, блок внутри него не допускается | Поменять местами: <pre><samp>...</samp></pre> |
| Приглашение записано обычным текстом | Оно попадает в копию, и скопированная команда не работает | span с user-select: none или ::before |
Меняющаяся часть не отмечена: <samp>Файл название не найден</samp> | Читатель не понимает, что слово «название» заменится своим значением | Файл <var>название</var> не найден |
samp ради моноширинного шрифта: <samp>Скидка 20%</samp> | Тег сообщает, что это вывод программы, а это обычный текст | span с классом и font-family |
Ждут, что samp будет выглядеть иначе, чем code и kbd | По умолчанию все три выглядят одинаково | Различие задать в CSS, смысл оставить в теге |
