Правила оформления статей

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

Здесь описаны правила «внутреннего» построения статей.

Сначала стоит упомянуть о нюансе, который бывает нужен почти всегда при редактировании, если у вас есть желание сделать всё красиво. Это перенос строк. Чтобы перенести строку (аналогично нажатию клавиши Enter в Word), надо воспользоваться следующим синтаксисом (с пробелом слева), если вы хотите перенести строку текста:

 \\

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

 \\ \\

Действует точно также, как тег BR в HTML.

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

{{tag>новичок info Puppy}}

=====Состояние статьи=====
^  качество  |среднее|
^  актуальность  |устарело|
^  приоритет  |не срочно|
^ меры по улучшению |дополнить|
^ ::: |...|

Первый на странице заголовок так же является названием статьи (в отличии, например, от mediaWiki).

Название веб-страницы видно в адресной строке браузера и в исходном вики-тексте страницы.

Название статьи видно в заголовке браузера и в ссылках на эту страницу.

Желательно придерживаться следующего:

• В начале страницы писать недлинный заголовок, отражающий в сжатом виде смысл статьи;
• Саму страницу называть с применением символов латинского алфавита, цифр и некоторых знаков.

Если название страницы будет составлено из русских букв, то, при определенной длине этого названия, могут возникнуть сбои в работе вики (страница не будет сохранена, или будет не найдена). Также, с русскими названиями страниц плохо «дружит» средство для переноса и переименования страниц.

Как реализовать правильный подход, объясним на примере.

1. Редактируем существующую статью, добавляем в неё ссылку:

   [[bash-trick]]

2. Сохраняем страницу.
3. Переходим по созданной ссылке.
4. Нажимаем Создать страницу.
5. В начале страницы пишем первый заголовок:

   ======Секреты BASH======

6. Содержимое статьи также подчиняется определенным правилам, но о них позже.
7. Сохраняем статью.
8. Возвращаемся на ту страницу, где мы вначале создавали ссылку.
9. Мы видим, что ссылка, ранее бывшая красной (bash-trick) заменилась на симпатичную зеленую (Секреты BASH).
10. В дальнейшем, при изменении первого заголовка на странице, названия ссылок будут меняться автоматически.

Заголовки относятся к логической разметке. Поэтому, вполне логично, что в статье должен быть только один заголовок первого уровня. Он выражает основную мысль статьи.

Статья разбивается на обособленные подразделы, для которых также выбираются заголовки. Это будут заголовки второго уровня. Большие подразделы желательно также разбить на более мелкие. Для них применимы заголовки третьего уровня. И так далее.

Нельзя устанавливать уровень заголовка, основываясь на его внешнем виде на странице. Нельзя, например, начинать статью заголовком третьего уровня, говоря, что заголовок первого уровня слишком крупно выглядит. При этом нарушается логика.

Для подтверждения того, что уровни заголовков имеют вложенную структуру, они так и отображаются в вики.

Вот простой пример расстановки уровня заголовков.

• Человек (1-й уровень)
  • голова (2-й уровень)
  • конечности (2-й уровень)
    • руки (3-й уровень)
      • левая рука (4-й уровень)
      • правая рука (4-й уровень)
    • ноги (3-й уровень)
      • левая нога (4-й уровень)
      • правая нога (4-й уровень)
  • туловище (2-й уровень)

Кроме того, заголовки одного уровня сопоставимы по своему логическому «весу».

После первого заголовка рекомендуется поместить аннотацию — краткое описание статьи. Аннотация помещается автоматически в список статей, генерируемый плагином pagelist. Как это выглядит, можно посмотреть в разделах данной вики.

Человек сможет, не читая статью, по аннотации составить о ней впечатление, понять, о чём в ней говорится.

Поведение этого плагина немного непредсказуемо. Поэтому рекомендуется после составления аннотации вернуться в список статей и посмотреть, что получится и, при необходимости, подкорректировать.

Технически, плагин берёт не более 500 первых символов текста после заголовка. Для русских символов (в принятой кодировке UTF-8) это число меньше. Кроме того плагин игнорирует разметку, цитирование, не заменяет «---» на «—», возможно, что-то еще. Поэтому лучший результат даст простой абзац текста. А символ тире (Alt+0151 на цифровой клавиатуре в windows) можно вставить при помощи таблицы символов на панели редактирования вики.

К статье нужно добавить теги — список ключевых слов. На главной странице вики имеется «облако тегов», которое помогает найти статьи сходной тематики. Кроме того, теги показываются на самой странице и в списке статей в разделах.

Пользоваться тегами очень просто. Например, нажав на тег «bash», получим список статей, в которых затрагивается вопрос bash.

Маркировка статей тегами является альтернативой поиску (поле ввода в верхней правой части страницы). Каждый может выбрать более удобный для себя инструмент для поиска нужной информации.

Ярлыки навешиваются на статью при помощи конструкции

{{tag>ярлык второй из_трёх_слов}}

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

Технически, на странице мы получаем пунктирную горизонтальную линию на всю ширину страницы и список ярлыков справа под ней. Такая конструкция совершенно «не смотрится» в начале статьи, поэтому ее место — в конце. Если в конце статьи есть несколько коротких строк (указание оригинала статьи, автора, переводчика и т.п), то список тегов лучше поместить после статьи, перед этими короткими строками.

Иллюстрации добавляются при помощи конструкции

{{:place:image.jpg|}}

После вертикальной черты добавляется описание картинки

{{:place:image.jpg|описание картинки}}

Все изображения можно снабдить миниатюрами, то есть ограничить размер изображения на странице.

{{:place:image.jpg?400|описание картинки}}

Расположить изображение по центру можно путем добавления пары пробелов сразу после фигурных скобок и после размера миниатюры.

{{  :place:image.jpg?400 |описание картинки}}

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

<flashplayer width="400" height="300">file=/_media/team/video.flv</flashplayer>

Данный плеер добавляет на страницу ролики формата FLV. Для добавления видео в формате SWF используется следующая конструкция:

{{wink>/team/video,800,620}}

Обратите внимание, расширение файла (.swf) при этом не указывается, только имя (video). Немного по-другому (без /_media) указывается и путь к файлу.

Да, русский язык великий и могучий, но не стоит снимать кальки с устоявшихся английских терминов. Так, не стоит писать СД вместо CD, Пуппи (Паппи, Паппик) вместо Puppy…

• Точка, запятая, двоеточие, многоточие, точка с запятой пишутся слитно с предшествующим текстом.
• Кавычки, скобки пишутся слитно с текстом, который они окружают.
• Дефис (-) используется в составных словах (пример: жёлто-красный) и при переносе слов по слогам.
• Среднее тире (–) используется между числами (пример: 1943–1945 гг.).
• Длинное (оно же обычное) тире используется во всех остальных случаях (пример: Он для меня — это всё). При этом слева и справа тире отделяется пробелом от окружающего текста. Система заменяет три дефиса (---) на тире.
• Тире в начале строки применяется только в диалогах.
• В конце заголовка не ставится точка.

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

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

В некоторых случаях уместно выделение подчеркиванием.

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

<color red>выделение</color>

Все цвета указываются словами, какое слово какому цвету соответствует, можно посмотреть в статье Цвета HTML.

Очень редко применяется зачеркивание текста (для того, чтобы видеть изменения).

Совсем не рекомендуется ВЫДЕЛЯТЬ БОЛЕЕ ОДНОГО-ДВУХ СЛОВ ЗАГЛАВНЫМИ БУКВАМИ (это выглядит кричаще) или р а з р е ж и в а т ь с л о в а п р о б е л а м и (при этом слова превращаются в набор букв).

Часто «неявные места», такие как названия программ или путь в файловой системе лучше дать моноширинным шрифтом (он обычно более «читабелен»). Сравните: lOI01 и lOI01.

Кнопки на клавиатуре (Ctrl) или в диалоге (OK) удобно маркировать с помощью клавиатурного плагина (кнопка с изображением клавиатуры на панели).

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

Заимствованный текст должен быть оформлен как цитата.

lexeii

Все изображения должны быть отцентрованы, подписаны и приведены визуально к одному размеру (миниатюры 400px). Само загружаемое изображение не должно превышать в ширину 900 пикселей. Соотношение размер-качество играет большую роль. Поскольку графики достаточно много, надо ориентироваться на размер (вес) графики в пределах 20-60 Kb/изображение. Если использовать для сохранения формат PNG-8 (плагин GIMP «Save for web») и поэкспериментировать с количеством цветов при сохранении файла, можно вполне добиться размера 5-30Kb/изображение. Скриншоты старайтесь делать в PNG, т.к. JPG при каждом редактировании теряет качество, а BMP много весит. Имена файлов должны соответствовать их содержанию.

Поскольку плеер в состоянии корректно масштабировать изображение, ширина выставляется 400 пикселей (также, как и у миниатюр картинок). Под размер подгонять высотой. Формат видео - FLV.

Плеер SWF не имеет полноэкранного режима и не маштабирует видео. Поэтому в настройках плеера выставляются реальные значения ширины и высоты. Ролик при этом не должен превышать в ширину 800 пикселей.

Теперь, когда все рекомендации прочитаны и приняты к сведению, можно и поэкспериментировать. Для экспериментов на начальных этапах обучения работе с wiki существует отдельная страница. Это тестовая страничка называется "Песочница". Там можно практически применить прочитанную тут информацию, так сказать набить руку.

Для того, чтобы приступить к редактированию, нужно сделать следующее:

• Зайти на нужную страницу и нажать кнопку редактирования.
• Появится интерфейс, схожий с тем, что у нас на форуме. В wiki синтаксис уже другой и кнопки на панели форматируют текст уже не при помощи BB-кода. Но принцип схож и интуитивно понятен. Если внимательно читали то, что выше — разберетесь без проблем.
• После редактирования не лишним будет предварительно просмотреть результаты. Для этого воспользуйтесь кнопкой Просмотр. Если всё в порядке — сохраняйте результаты.
• Объясню (на всякий случай) на простом примере. Вам нужно добавить в статью ссылку на внутренние ресурсы wiki (например, на другую страницу). Для внутренних ссылок существует отдельная кнопка. Выделяете мышью текст, который планируете сделать ссылкой и нажимаете кнопку.
• Wiki предложит вам выбрать раздел, на который будет указывать будущая ссылка. Название раздела можно посмотреть в адресной строке обозревателя (ссылка на страницу).
• После выбора раздела система предложит выбрать одну из страниц, находящихся в нём. Выбирайте нужную страницу.
• В окне редактирования выделенный вами текст оформится синтаксически в виде внутренней ссылки. Жмём кнопку Сохранить. После загрузки страницы проверьте ссылку на работоспособность (на всякий пожарный), перейдя по ней.
• Обратите внимание на часто встречающуюся маленькую кнопку Править. С помощью неё можно открывать для редактирования не всю страницу целиком а только интересующую вас часть. Помогает не запутаться в коде при большом объеме страниц.

• Wiki — система самодостаточная. Для того, чтобы размещать файлы в статьях, не нужно пользоваться сторонними ресурсами. Файлы следует закачивать прямо в Wiki. Для этого существует кнопка на панели редактирования.
• После нажатия на неё, появится интерфейс добавления файлов. Там всё просто и интуитивно понятно. Интерфейс содержит ряд инструментов для более удобной и простой работы:
  1. имя загружаемого файла (можно изменить).
  2. отметка перезапишет файл при совпадении имени (полезно при обновлении статей).
  3. инструмент для закачки группы файлов (выполнен на флеше).
  4. ниже список уже закаченных в данный раздел файлов. При помощи этих кнопок можно быстро просмотреть или удалить файл.

Стоит отметить, что в wiki нельзя запихнуть что попало. Разрешены только некоторые расширения файлов. Среди них расширения пакетов программ и модулей .pet и .sfs. Все пакеты и другие доп. материалы (скрипты, исходники) надо закачивать в строго отведённое пространство имен (каталог). Это каталог pet_sfs_src.

1. Выбрать в менеджере загрузки пространство имен pet_sfs_src.
2. Дождаться загрузки раздела в менеджер.
3. Загрузить пакет (отредактировать имя при необходимости).

После создания и правки страниц информация об этом появляется в разделе Вклад участников. Было бы полезно для всех редакторов, если бы наряду с информацией об изменениях оставлялись бы комментарии о характере изменений. Для комментирования следует заполнить поле Сводка изменений (под кнопкой Сохранить).

Чтобы комментарий отображался на странице, отметку Небольшие изменения ставить не нужно.

Автор: lexeii, RulllJazzz key