Содержание
О том, как это делать, смотрите ниже.
Оформление команд
Любые команды, вводимые в консоли, надо заключать в тег <code>
, либо отделять двойным пробелом, что даст тот же эффект. Например:
sudo su rm -rf /
Однако не выделяйте таким образом команды вместе с выводом или с приглашением командной строки (кроме символов # и $, если кто ещё помнит различие между ними).
Кроме того, если необходимо включить в команду некое собирательное понятие, например, «файл», то можно, дабы не возникало путаницы, заключить его в треугольные скобки. Например:
ls -ld <директория>
Если необходимо включить название консольной утилиты в текст, то её необходимо выделить моноширинным курсивом
, например:
- Утилита
ls
выводит содержимое текущей папки.
Не выделяйте подобным образом целые команды, т.е. названия утилит вместе с параметрами, для этого необходимо использовать тег <code>
.
Листинги (содержимое текстовых файлов и вывод команд)
Листинги необходимо заключать в тег <file>
, но если листинг - содержимое скрипта, то крайне желателательно использовать подсветку синтаксиса с тегом <code>
. Заключать листинги в тег <code>
без подсветки запрещено.
Например:
sub LoadResFile { local $_; @_ == 1 or die "Должен быть ровно 1 аргумент!\n"; open INPUT, "<$_[0]" or die "Файл '$_[0]', Ы?\n"; my @results; foreach (<INPUT>) { next if /^\s*$/ or /^\s*#/; #Легко избавляемся от пустых строк и строк-комментариев s/#.*|[\n\r]//g; #Легко кушаем все комментарии и переводы строк my @vals = /(?:\A|,)(.*?)(?=,|\Z)/g; #Легко разделяем строчки по запятым (хм, почему не split) foreach $key (@vals) { $key =~ s!\s!!g; #Легко удаляем все пробелы if ($key) { $results[@results]=$key } #Если что-то осталось, то добавляем в результаты } } close INPUT; return @results; }
<code>
и <file>
ни для каких других целей, кроме вышеобозначенных
Существует баг Firefox'а, связанный с тем, что элементы <file> и <code>, содержащие длинные строки, растягивают пространство статьи в горизонтальном направлении. Такой же эффект получается если добавить на страницу изображение большого размера. Т. к. текст масштабируется в зависимости от размеров страницы, такие статьи очень неудобно читать, особенно тем, у кого маленькие мониторы (например, пользователям нетбуков). Для того, чтобы растягивания не происходило, разбивайте такие строки на несколько строк. Например, команду
cat /home/user/folder1/folder2/folder3/folder4/folder5/folder6/folder7/folder8/folder9/folder10/folder11/folder12/folder13/folder14/folder15/some_file
можно записать:
cat /home/user/folder1/folder2/folder3/ \ folder4/folder5/folder6/folder7/folder8/ \ folder9/folder10/folder11/folder12/folder13/ \ folder14/folder15/some_file
И она, после копирования ее в терминал все равно будет работать, т. к. в конце каждой строки стоит символ \, экранирующий переход на новую строку. Аналогично можно поступать со скриптами, а в случае с листингом файлов или вывода результатов работы какой-либо программы можно просто разбивать строки. Например:
Это очень-очень-очень длинная строка, в которой написано что-то совсем не важное. Но мы то с вами знаем, что важна тут в первую очередь именно длина строки. А это короткая строка.
Может быть записано как:
Это очень-очень-очень длинная строка, в которой написано что-то совсем не важное. Но мы то с вами знаем, что важна тут в первую очередь именно длина строки. А это короткая строка.
Данное требование в оформлении не обязательное, но желательное, т. к. во-первых Firefox является в Ubuntu браузером по-умолчанию, а во-вторых далеко не у каждого посетителя ресурса есть возможность смотреть его с тем же разрешением, что и у вас.
Названия приложений
Запрещено транслитерировать английские имена. Если файловый менеджер называется Nautilus, то обзывать его Наутилусом не стоит. Фактически, нужно брать названия из меню Приложения или Система.
Кроме того, каждое слово в имени собственном приложения надо выводить с заглавной буквы, т.е. например нужно писать Synaptic и Cairo Dock, а не synaptic или Cairo dock, однако это не значит, что нужно писать Файловый Менеджер Nautilus, ибо именем собственым является только Nautilus. Кроме того, если название принято выводить в верхнем регистре, то этого правила тоже следует придерживаться, т.е. писать GNOME и KDE вместо Gnome и Kde.
Если вы пишите полное название приложения, то либо вы заключаете его в кавычки, начинаете с заглавной буквы и пишите курсивом, либо выделяете заглавными буквами только имена собственные в составе полного названия и пишите всё обычным шрифтом. Например:
- В файлом менеджере Nautilus можно выполнять различные операции с файлами.
- Откройте приложение «Файловый менеджер Nautilus» и зайдите в меню Правка→Параметры.
При этом курсивом надо выделять только содержимое, а не символы-кавычки.
Кроме того, не забывайте давать ссылки на статьи про упоминаемые приложения, как это сделано в предыдущем примере.
Имена пунктов меню в системе и приложениях
Имена любых пунктов меню необходимо писать курсивом. Кроме того, лучше не выделять их кавычками. Цепочки в любом случае в кавычки выделять нельзя. Например: Система→Параметры. А вот код, дающий такой результат:
//Система->Параметры//
Названия различных элементов на диалоговых окнах
Названия любых элементов необходимо выделять курсивом, и при необходимости заключать в кавычки.
Клавиатурные сочетания
При любом упоминании любой клавиши клавиатуры или любого клавиатурного сочетания необходимо использовать тег <key>:
<key>C-A-F1</key>
А выглядит это так: Ctrl+Alt+F1
Общая сводка стилей
Курсив
- Используется для названий пунктов меню и элементов диалоговых окон, а так же для названий приложений, заключённых в кавычки.
моноширинный шрифт
- Используется для названий пакетов в тексте (напр,
lm-sensors
)
моноширинный курсив
- Используется для названий консольных утилит в тексте, для выделения команд используйте <code>!
Полужирный шрифт
- Используется для логического выделения важных моментов в тексте, не используйте полужирный шрифт для выделения названий приложений, пакетов, пунктов меню и проч.
Ctrl+Alt+Del
- Используется для обозначения клавиатурных клавиш и сочетаний
Так выделяются консольные команды, которые должен ввести пользователь
Так выделяется содержимое текстовых файлов (не скриптов), а так же текстовый вывод команд (например, вывод команды ls)
#!/usr/bin/perl # Так выделяется содержимое скриптов и программный код print OUTFILE "Содержимое скриптов",$_[1];
rm
подобным предупреждением.