Дисциплина оформления иллюстраций

Глобальное-генеричное или предисловие

На данный момент для иллюстрирования лекций используются сущности нескольких видов:

• Логи работы с командной строкой («тайпскрипты»)
• Схемы
• Скриншоты

Иллюстрации прикрепляются к странице лекции, которой они соответствуют (например, если иллюстрация соответствует лекции в рамках проекта документирвания ПСПО от 22 июля, то она должна быть прикреплена к странице PspoClasses/080722).

В случае, если иллюстрация соответствует нескольким лекциям, то она должна быть прикреплена ко всем страницам лекций, которым она соответствует.

На случай упущения важных деталей человеком, подготавливающим иллюстрации на основании сырых материалов, к странице лекции также рекомендуется прикреплять архив с оригинальными материалами (например, PspoClasses/080805/080805.tar.bz2).

Общие слова об именовании

• Из имени должно следовать, что содержится в иллюстрации, что она иллюстрирует (например, из имени kde_menu_others_internet_konqueror.png (PspoClasses/080805/kde_menu_others_internet_konqueror.png) следует, что на иллюстрации изображено меню KDE с открытыми подменю прочие-интернет и выбранным пунктом Konqueror)

• Имена пишутся латинскими буквами. В качестве разделителей используются символы подчёркивания (underscore)
• Использование заглавных букв в начале имени файла или каждого слова не требуется. Наоборот, использование строчных букв является предпочтительным (C-style variable naming convention)
• Рекомендуется, чтобы структура имён образовывала иерархию неймспейсов в рамках страницы при необходимости (если в лекции рассматриваются DNS, SSH и DHCP, то иллюстрации, к ним относящиеся, предпочтительно именовать с префиксами «dns_», «ssh_» и «dhcp_» соответственно; если, например, в рамках SSH рассматривают sshd, scp, sftp и ssh-agent, то можно использовать как префиксы «ssh_sshd_», «ssh_scp_», «ssh_sftp_», «ssh_ssh_agent_», так и «sshd_», «scp_», «sftp_», «ssh_agent_», но при этом надо учитывать, что, во-первых, первый вариант предпочтительнее (кроме случая, если лекция только про SSH — в этом случае как раз предпочтителен второй вариант), во-вторых, использовать оба способа именования одновременно в рамках одной лекции крайне не рекомендуется)

Ссылки и включение

Для ссылания/включения иллюстраций в содержимое фрагментов лекций используются entities [[attachment:]] и {{attachment:}} соответственно. При этом настоятельно рекомендуется использовать относительный путь к иллюстрации (например, {{attachment:../attachment_name.ext}}).

Окружение

Так как лекции читались в различных местах и с раздличным окружением, то и некие сущности в процессе иллюстрирования отличались. Решено не приводить всё к единому окружению, а задокументировать его.

В случае же, если иллюстрация не попадает ни под один из вариантов, рекомендуется выбрать подходящий по контексту (то есть тот, который использовался в аналогичных лекциях), и привести к нему.

Типоспецифичное

Скриншоты

Скриншот есть сохранённое изображение экрана или его части, опционально видоизменённое для выделения иллюстрируемой части.

• Предпочтительный формат скриншотов — PNG
• Ряд разрозненных conventions по офомлению скриншотов:
  • Мышиный курсор на скринршотах крайне нежелателен
  • Если объектом иллюстрирования является окно, то оно должно быть изображено вместе с декорациями по умолчанию, и больше ничего скриншот включать не должен (достигается путём применения crop и erase ненужных пикселов. Для удаления угловых пикселов у изображения окна с декорациями по умолчанию можно использовать следующий shell-скрипт:

for i in "$@"
do
  W=`identify -format "%w" $i`
  H=`identify -format "%h" $i`
  
  convert $i -background none -size ${W}x${H} xc:white -fill black \
    -draw "point 0,0" \
    -draw "point 0,1" \
    -draw "point 1,0" \
    -draw "point $((W-2)),0" \
    -draw "point $((W-1)),0" \
    -draw "point $((W-1)),1" \
    -draw "point 0,$((H-1))" \
    -draw "point $((W-1)),$((H-1))" \
    -transparent black -compose Copy_Opacity -composite $i
done

• , использующий ImageMagick)

• В случае, если объектом иллюстрирования является элемент интерфейса, то не относящиеся к нему пикселы либо делаются полностью прозрачными (пример: PspoClasses/080805/konqueror_close_tab_tip.png, PspoClasses/080805/system_menu.png), либо, в отсутствие чёткой границы, окрестность можно плавно увести к прозрачной (примеры: PspoClasses/080805/kde_menu_tip.png, PspoClasses/080805/panel_drive_unmounted_tip.png, PspoClasses/080805/thunderbird_tip.png). При этом величину fade'а рекомендуется делать равной 20 пикселам

• В случае, если объектом иллюстрирования является меню, то не относящиеся к нему пикселы удаляются. В случае присутствия элемента, породившего меню (пункт главного меню, иконка, элемент списка), он также изображается на иллюстрации (примеры: PspoClasses/080805/panel_quickrun_menu.png, PspoClasses/080805/konqueror_tab_detach.png, PspoClasses/080805/konqueror_settings_menu.png, PspoClasses/080805/konqueror_open_in_new_tab_dir.png). По возможности, фон элемента, породившего меню, желательно удалять (примеры: PspoClasses/080805/konqueror_panel_profiles.png, PspoClasses/080805/konqueror_open_in_new_tab_img.png), но не это не является жёстким требованием (примеры: PspoClasses/080805/konqueror_open_in_new_tab_zip.png)

Схемы

Схемы рекомендуется делать векторными (предпочтительный формат — SVG). При этом желательно прикреплять следующие файлы:

• Схема в рабочем формате
• Схема, экспортированная в PNG

Некоторые гайдлайны:

• Фон схемы настоятельно рекомендуется иметь прозрачным
• Фон блоков рекомендуется иметь непрозрачным
• Желательна минимизация использования цвета, за исключением случаев, когда он несёт явную. семантику или выразительных средств серой палитры недостаточно

• Рекомендуемый шрифт — DejaVu Sans Condensed

Логи

Гайдлайны:

• Приглашение для пользователя — $, для суперпользователя — #

CategoryPolicy