Различия
Здесь показаны различия между выбранной ревизией и текущей версией данной страницы.
— |
wiki:articles-rules [2016/02/26 17:42] (текущий) |
||
---|---|---|---|
Строка 1: | Строка 1: | ||
+ | ======Правила оформления статей====== | ||
+ | В данной заметке описаны правила, которых следует придерживаться при написании (корректировке) статей в данной вики. | ||
+ | |||
+ | |||
+ | =====Техника оформления===== | ||
+ | |||
+ | Здесь описаны правила "внутреннего" построения статей. | ||
+ | |||
+ | Сначала стоит упомянуть о нюансе, который бывает нужен почти всегда при редактировании, если у вас есть желание сделать всё красиво. Это перенос строк. Чтобы перенести строку (аналогично нажатию клавиши <key>Enter</key> в Word), надо воспользоваться следующим синтаксисом (с пробелом слева), если вы хотите перенести строку текста: | ||
+ | <file> \\</file> | ||
+ | Если вы хотите сделать отступ в виде пустой строки, тогда конструкция следующая (опять же с пробелом слева): | ||
+ | <file> \\ \\</file> | ||
+ | Действует точно также, как тег BR в HTML. | ||
+ | |||
+ | В создаваемой статье обязательно должны присутствовать оценка актуальности (таблица) и [[team:tags_list|список тегов]]. Ставится этот блок в конце статьи. | ||
+ | |||
+ | <file> | ||
+ | {{tag>новичок info Puppy}} | ||
+ | |||
+ | =====Состояние статьи===== | ||
+ | ^ качество |среднее| | ||
+ | ^ актуальность |устарело| | ||
+ | ^ приоритет |не срочно| | ||
+ | ^ меры по улучшению |дополнить| | ||
+ | ^ ::: |...| | ||
+ | </file> | ||
+ | |||
+ | ====Заголовок==== | ||
+ | |||
+ | Первый на странице заголовок так же является //названием статьи// (в отличии, например, от mediaWiki). | ||
+ | |||
+ | //Название веб-страницы// видно в адресной строке браузера и в исходном вики-тексте страницы. | ||
+ | |||
+ | //Название статьи// видно в заголовке браузера и в ссылках на эту страницу. | ||
+ | |||
+ | Желательно придерживаться следующего: | ||
+ | |||
+ | * В начале страницы писать недлинный заголовок, отражающий в сжатом виде смысл статьи; | ||
+ | * Саму страницу называть с применением символов латинского алфавита, цифр и некоторых знаков. | ||
+ | |||
+ | Если название страницы будет составлено из русских букв, то, при определенной длине этого названия, могут возникнуть сбои в работе вики (страница не будет сохранена, или будет не найдена). Также, с русскими названиями страниц плохо "дружит" средство для переноса и переименования страниц. | ||
+ | |||
+ | Как реализовать правильный подход, объясним на примере. | ||
+ | |||
+ | - Редактируем существующую статью, добавляем в неё ссылку: <file>[[bash-trick]]</file> | ||
+ | - Сохраняем страницу. | ||
+ | - Переходим по созданной ссылке. | ||
+ | - Нажимаем <key>Создать страницу</key>. | ||
+ | - В начале страницы пишем первый заголовок: <file>======Секреты BASH======</file> | ||
+ | - Содержимое статьи также подчиняется определенным правилам, но о них позже. | ||
+ | - Сохраняем статью. | ||
+ | - Возвращаемся на ту страницу, где мы вначале создавали ссылку. | ||
+ | - Мы видим, что ссылка, ранее бывшая красной ([[bash-trick]]) заменилась на симпатичную зеленую ([[#Заголовок|Секреты BASH]]). | ||
+ | - В дальнейшем, при изменении первого заголовка на странице, названия ссылок будут меняться автоматически. | ||
+ | |||
+ | |||
+ | ====Уровни заголовков==== | ||
+ | |||
+ | Заголовки относятся к логической разметке. Поэтому, вполне логично, что в статье должен быть только один заголовок первого уровня. Он выражает основную мысль статьи. | ||
+ | |||
+ | Статья разбивается на обособленные подразделы, для которых также выбираются заголовки. Это будут заголовки второго уровня. Большие подразделы желательно также разбить на более мелкие. Для них применимы заголовки третьего уровня. И так далее. | ||
+ | |||
+ | Нельзя устанавливать уровень заголовка, основываясь на его внешнем виде на странице. Нельзя, например, начинать статью заголовком третьего уровня, говоря, что заголовок первого уровня слишком крупно выглядит. При этом нарушается логика. | ||
+ | |||
+ | Для подтверждения того, что уровни заголовков имеют вложенную структуру, они так и отображаются в вики. | ||
+ | |||
+ | Вот простой пример расстановки уровня заголовков. | ||
+ | |||
+ | * Человек (1-й уровень) | ||
+ | * голова (2-й уровень) | ||
+ | * конечности (2-й уровень) | ||
+ | * руки (3-й уровень) | ||
+ | * левая рука (4-й уровень) | ||
+ | * правая рука (4-й уровень) | ||
+ | * ноги (3-й уровень) | ||
+ | * левая нога (4-й уровень) | ||
+ | * правая нога (4-й уровень) | ||
+ | * туловище (2-й уровень) | ||
+ | |||
+ | Кроме того, заголовки одного уровня сопоставимы по своему логическому "весу". | ||
+ | |||
+ | |||
+ | ====Аннотация==== | ||
+ | |||
+ | После первого заголовка рекомендуется поместить аннотацию --- краткое описание статьи. Аннотация помещается автоматически в список статей, генерируемый плагином pagelist. Как это выглядит, можно посмотреть в разделах данной вики. | ||
+ | |||
+ | Человек сможет, не читая статью, по аннотации составить о ней впечатление, понять, о чём в ней говорится. | ||
+ | |||
+ | Поведение этого плагина немного непредсказуемо. Поэтому рекомендуется после составления аннотации вернуться в список статей и посмотреть, что получится и, при необходимости, подкорректировать. | ||
+ | |||
+ | Технически, плагин берёт не более 500 первых символов текста после заголовка. Для русских символов (в принятой кодировке UTF-8) это число меньше. Кроме того плагин игнорирует разметку, цитирование, не заменяет «%%---%%» на «—», возможно, что-то еще. Поэтому лучший результат даст простой абзац текста. А символ тире (<key>A-0151</key> на цифровой клавиатуре в windows) можно вставить при помощи таблицы символов на панели редактирования вики. | ||
+ | |||
+ | |||
+ | ====Теги (ярлыки)==== | ||
+ | |||
+ | К статье нужно добавить теги --- список ключевых слов. На главной странице вики имеется "облако тегов", которое помогает найти статьи сходной тематики. Кроме того, теги показываются на самой странице и в списке статей в разделах. | ||
+ | |||
+ | Пользоваться тегами очень просто. Например, нажав на тег "bash", получим список статей, в которых затрагивается вопрос bash. | ||
+ | |||
+ | Маркировка статей тегами является альтернативой поиску (поле ввода в верхней правой части страницы). Каждый может выбрать более удобный для себя инструмент для поиска нужной информации. | ||
+ | |||
+ | Ярлыки навешиваются на статью при помощи конструкции <file>{{tag>ярлык второй из_трёх_слов}}</file> Ярлыки разделяются пробелами (причем, перед первым ярлыком пробела быть не должно), а для ярлыков из нескольких слов нужно применять символ подчеркивания (_). | ||
+ | |||
+ | Технически, на странице мы получаем пунктирную горизонтальную линию на всю ширину страницы и список ярлыков справа под ней. Такая конструкция совершенно "не смотрится" в начале статьи, поэтому ее место --- в конце. Если в конце статьи есть несколько коротких строк (указание оригинала статьи, автора, переводчика и т.п), то список тегов лучше поместить после статьи, перед этими короткими строками. | ||
+ | |||
+ | ====Иллюстрации==== | ||
+ | |||
+ | Иллюстрации добавляются при помощи конструкции <file>{{:place:image.jpg|}}</file> После вертикальной черты добавляется описание картинки <file>{{:place:image.jpg|описание картинки}}</file> Все изображения можно снабдить миниатюрами, то есть ограничить размер изображения на странице.<file>{{:place:image.jpg?400|описание картинки}}</file> Расположить изображение по центру можно путем добавления пары пробелов сразу после фигурных скобок и после размера миниатюры. <file>{{ :place:image.jpg?400 |описание картинки}}</file> | ||
+ | |||
+ | |||
+ | ====Видео==== | ||
+ | |||
+ | Есть возможнось добавлять на страницу видео при помощи специального плеера, но только в крайних случаях. Все же бывают ситуации, когда проще один раз увидеть. Код выглядит следующим образом: <file><flashplayer width="400" height="300">file=/_media/team/video.flv</flashplayer></file>Данный плеер добавляет на страницу ролики формата FLV. Для добавления видео в формате SWF используется следующая конструкция:<file>{{wink>/team/video,800,620}}</file>Обратите внимание, расширение файла (.swf) при этом не указывается, только имя (video). Немного по-другому (без /_media) указывается и путь к файлу. | ||
+ | |||
+ | =====Стиль оформления===== | ||
+ | |||
+ | |||
+ | ====Русский язык==== | ||
+ | |||
+ | Да, русский язык //великий и могучий//, но не стоит снимать кальки с устоявшихся английских терминов. Так, не стоит писать **СД** вместо **CD**, **Пуппи** (**Паппи**, **Паппик**) вместо **Puppy**... | ||
+ | |||
+ | |||
+ | ====Пунктуация==== | ||
+ | |||
+ | * Точка, запятая, двоеточие, многоточие, точка с запятой пишутся слитно с предшествующим текстом. | ||
+ | * Кавычки, скобки пишутся слитно с текстом, который они окружают. | ||
+ | * Дефис (-) используется в составных словах (//пример//: жёлто-красный) и при переносе слов по слогам. | ||
+ | * Среднее тире (–) используется между числами (//пример//: 1943–1945 гг.). | ||
+ | * Длинное (оно же обычное) тире используется во всех остальных случаях (//пример//: Он для меня --- это всё). При этом слева и справа тире отделяется пробелом от окружающего текста. Система заменяет три дефиса (''%%---%%'') на тире. | ||
+ | * Тире в начале строки применяется только в диалогах. | ||
+ | * В конце заголовка не ставится точка. | ||
+ | |||
+ | ====Выделения==== | ||
+ | |||
+ | Простой текст гораздо лучше смотрится, если некоторые места в нём выделить особым образом. В некоторых случаях это позволяет устранить двойное толкование и заменяет собой пояснительный текст, призванный устранить неправильное толкование. В любом случае, выделения призваны улучшить восприятие текста. | ||
+ | |||
+ | |||
+ | ===Выделения текста в абзаце=== | ||
+ | |||
+ | Наиболее применимыми способами выделения текста в абзаце являются //слабое выделение// (при помощи курсивного или наклонного начертания) и **сильное выделение** (при помощи полужирного начертания). | ||
+ | |||
+ | В некоторых случаях уместно __выделение подчеркиванием__. | ||
+ | |||
+ | В экзотических случаях может понадобиться <color green>выделение</color> <color skyblue>цветом</color>. | ||
+ | Для оформления текста цветом нет специальной кнопки на панели. Для этого применяется следующий синтаксис: | ||
+ | <code><color red>выделение</color></code> | ||
+ | Все цвета указываются словами, какое слово какому цвету соответствует, можно посмотреть в статье [[wpru>Цвета_HTML#.D0.9D.D0.B0.D0.B7.D0.B2.D0.B0.D0.BD.D0.B8.D1.8F_.D1.86.D0.B2.D0.B5.D1.82.D0.BE.D0.B2_.D0.B2_X11 | Цвета HTML]]. | ||
+ | |||
+ | Очень редко применяется <del>зачеркивание текста</del> (для того, чтобы видеть изменения). | ||
+ | |||
+ | Совсем не рекомендуется ВЫДЕЛЯТЬ БОЛЕЕ ОДНОГО-ДВУХ СЛОВ ЗАГЛАВНЫМИ БУКВАМИ (это выглядит кричаще) или р а з р е ж и в а т ь с л о в а п р о б е л а м и (при этом слова превращаются в набор букв). | ||
+ | |||
+ | Часто "неявные места", такие как названия программ или путь в файловой системе лучше дать ''моноширинным шрифтом'' (он обычно более "читабелен"). Сравните: lOI01 и ''lOI01''. | ||
+ | |||
+ | Кнопки на клавиатуре (<key>Ctrl</key>) или в диалоге (<key>OK</key>) удобно маркировать с помощью клавиатурного плагина (кнопка с изображением клавиатуры на панели). | ||
+ | |||
+ | |||
+ | ===Выделения блоков текста=== | ||
+ | |||
+ | Следует пользоваться //нумерованными списками// для перечисления какой-либо последовательности и //маркированными списками// для перечисления каких-либо равнозначных пунктов. Для перечисления терминов и их определений удобно пользоваться списком определений (имеются ограничения на длину термина) или простой таблицей с заголовками. | ||
+ | |||
+ | <note important>Важные места в тексте должны выделяться с помощью плагина note.</note> | ||
+ | |||
+ | <blockquote>Заимствованный текст должен быть оформлен как цитата.<cite>lexeii</cite></blockquote> | ||
+ | |||
+ | ====Оформление иллюстраций==== | ||
+ | |||
+ | Все изображения должны быть отцентрованы, подписаны и приведены визуально к одному размеру (миниатюры 400px). Само загружаемое изображение не должно превышать в ширину 900 пикселей. Соотношение размер-качество играет большую роль. Поскольку графики достаточно много, надо ориентироваться на размер (вес) графики в пределах 20-60 Kb/изображение. Если использовать для сохранения формат PNG-8 (плагин GIMP "Save for web") и поэкспериментировать с количеством цветов при сохранении файла, можно вполне добиться размера 5-30Kb/изображение. Скриншоты старайтесь делать в PNG, т.к. JPG при каждом редактировании теряет качество, а BMP много весит. Имена файлов должны соответствовать их содержанию. | ||
+ | |||
+ | {{ mechta_1.png?400 |Мечтать не вредно...}} | ||
+ | |||
+ | {{ mechta_2.jpg?400 |Мечтать не вредно...}} | ||
+ | |||
+ | ====Оформление видео==== | ||
+ | |||
+ | Поскольку плеер в состоянии корректно масштабировать изображение, ширина выставляется 400 пикселей (также, как и у миниатюр картинок). Под размер подгонять высотой. Формат видео - FLV. | ||
+ | |||
+ | <flashplayer width="400" height="344">file=/_media/team/preview.flv</flashplayer> | ||
+ | |||
+ | Плеер SWF не имеет полноэкранного режима и не маштабирует видео. Поэтому в настройках плеера выставляются реальные значения ширины и высоты. Ролик при этом не должен превышать в ширину 800 пикселей. | ||
+ | |||
+ | =====Приступая к работе===== | ||
+ | |||
+ | Теперь, когда все рекомендации прочитаны и приняты к сведению, можно и поэкспериментировать. Для экспериментов на начальных этапах обучения работе с wiki существует отдельная страница. Это тестовая страничка называется [[playground:playground|"Песочница"]]. Там можно практически применить прочитанную тут информацию, так сказать набить руку. | ||
+ | |||
+ | Для того, чтобы приступить к редактированию, нужно сделать следующее: | ||
+ | * Зайти на нужную страницу и нажать кнопку редактирования. {{ redact_01.png?400 |приступая к работе}} | ||
+ | * Появится интерфейс, схожий с тем, что у нас на форуме. В wiki синтаксис уже другой и кнопки на панели форматируют текст уже не при помощи BB-кода. Но принцип схож и интуитивно понятен. Если внимательно читали то, что выше --- разберетесь без проблем. {{ redact_02.png?400 |приступая к работе}} | ||
+ | * После редактирования не лишним будет предварительно просмотреть результаты. Для этого воспользуйтесь кнопкой <key>Просмотр</key>. Если всё в порядке --- сохраняйте результаты. {{ redact_09.png?400 |приступая к работе}} | ||
+ | * Объясню (на всякий случай) на простом примере. Вам нужно добавить в статью ссылку на внутренние ресурсы wiki (например, на другую страницу). Для внутренних ссылок существует отдельная кнопка. Выделяете мышью текст, который планируете сделать ссылкой и нажимаете кнопку. {{ redact_03.png?400 |приступая к работе}} | ||
+ | * Wiki предложит вам выбрать раздел, на который будет указывать будущая ссылка. Название раздела можно посмотреть в адресной строке обозревателя (ссылка на страницу). {{ redact_04.png?400 |приступая к работе}} | ||
+ | * После выбора раздела система предложит выбрать одну из страниц, находящихся в нём. Выбирайте нужную страницу. {{ redact_05.png?400 |приступая к работе}} | ||
+ | * В окне редактирования выделенный вами текст оформится синтаксически в виде внутренней ссылки. Жмём кнопку <key>Сохранить</key>. После загрузки страницы проверьте ссылку на работоспособность (на всякий пожарный), перейдя по ней. {{ redact_06.png?400 |приступая к работе}} | ||
+ | * Обратите внимание на часто встречающуюся маленькую кнопку <key>Править</key>. С помощью неё можно открывать для редактирования не всю страницу целиком а только интересующую вас часть. Помогает не запутаться в коде при большом объеме страниц. {{ redact_10.png?400 |приступая к работе}} | ||
+ | |||
+ | =====Загрузка файлов для статей===== | ||
+ | |||
+ | * Wiki --- система самодостаточная. Для того, чтобы размещать файлы в статьях, не нужно пользоваться сторонними ресурсами. Файлы следует закачивать прямо в Wiki. Для этого существует кнопка на панели редактирования. {{ redact_07.png?400 |приступая к работе}} | ||
+ | * После нажатия на неё, появится интерфейс добавления файлов. Там всё просто и интуитивно понятно. Интерфейс содержит ряд инструментов для более удобной и простой работы: | ||
+ | - имя загружаемого файла (можно изменить). | ||
+ | - отметка перезапишет файл при совпадении имени (полезно при обновлении статей). | ||
+ | - инструмент для закачки группы файлов (выполнен на флеше). | ||
+ | - ниже список уже закаченных в данный раздел файлов. При помощи этих кнопок можно быстро просмотреть или удалить файл. | ||
+ | {{ redact_08.png?400 |приступая к работе}} | ||
+ | |||
+ | Стоит отметить, что в wiki нельзя запихнуть что попало. Разрешены только некоторые расширения файлов. Среди них расширения пакетов программ и модулей **.pet** и **.sfs**. Все пакеты и другие доп. материалы (скрипты, исходники) надо закачивать в строго отведённое пространство имен (каталог). Это каталог **pet_sfs_src**. | ||
+ | |||
+ | - Выбрать в менеджере загрузки пространство имен **pet_sfs_src**. | ||
+ | - Дождаться загрузки раздела в менеджер. | ||
+ | - Загрузить пакет (отредактировать имя при необходимости). | ||
+ | |||
+ | {{ wiki_pet.png?400 |сохранение файлов пакетов}} | ||
+ | |||
+ | =====Комментарии===== | ||
+ | |||
+ | После создания и правки страниц информация об этом появляется в разделе [[team:contribution|Вклад участников]]. Было бы полезно для всех редакторов, если бы наряду с информацией об изменениях оставлялись бы комментарии о характере изменений. Для комментирования следует заполнить поле **Сводка изменений** (под кнопкой <key>Сохранить</key>). | ||
+ | |||
+ | {{ comment.png?400 |комментарии}} | ||
+ | |||
+ | Чтобы комментарий отображался на странице, отметку **Небольшие изменения** ставить не нужно. | ||
+ | |||
+ | {{ comment2.png?400 |комментарии}} \\ \\ | ||
+ | |||
+ | <note tip> | ||
+ | Это, однако, только общая информация, знание которой позволит вам проводить несложное редактирование. При создании документов со сложным форматированием (и для повышения квалификации вообще) стоит ознакомиться с более подробной документацией: \\ \\ | ||
+ | - [[wiki:syntax-main|Синтаксисом оформления статей]]. | ||
+ | - [[wiki:syntax-plugins|Дополнениями к синтаксису]]. | ||
+ | Поскольку статьи про синтаксис очень объёмные, читать и усваивать всё сразу голова опухнет. Поэтому с ними лучше поверхностно ознакомиться, чтобы представлять --- какая информация там есть, а впоследствии уже возвращаться к ним как к справочникам. | ||
+ | </note> | ||
+ | |||
+ | {{tag>Wiki}} | ||
+ | //Автор: lexeii, RulllJazzz// | ||
+ | key |