From BlenderWiki
Другие страницы посвященные редактированию Wiki:
Руководство редактора | Руководство по стилю оформления | Шаблоны | Заметки для переводчиков | Список задач (Руководство)
В целях обеспечения целостности всей документации Blender’a, потенциальным авторам настоятельно рекомендуется соблюдать настоящее Руководство по стилю оформления.
Люди совершенно не знакомые с синтаксисом MediaWiki могут также обратиться к официальной документации MediaWiki Docs.
[edit] Общие правила
Документация Blender’a должна быть написана понятным, лаконичным, идиоматическим и (во всех смыслах) грамотным языком. Она должна быть адекватно разделена на главы, разделы и подразделы.
Логическое деление Основной документации диктуется рабочей группой по документации (DocBoard). Никакие новые страницы не могут быть добавлены, иначе как, только после утверждения.
Логическое деление любого из добровольно внесенных Уроков, оставляется на усмотрение каждого автора.
Урок должен содержать резюме до 300 слов кратко излагающее тему урока, цели и содержание для быстрого просмотра.
Каждая страница должна иметь соответствующий шаблон на Первой строке, для отображения элементов навигации и версии Blender’a, которой соответствует изложенный материал. Что достигается благодаря использованию шаблона
{{UM/navigator|2.32}}
Где 2.32, разумеется, соответствует номеру версии.
Это отображается, как
0 %Кроме того, для длинных страниц представляющих несколько разделов, некоторые из которых относятся к разным версиям Blender’a, доступен другой шаблон:
{{Version|2.32}}
Он должен быть помещен сразу же после названия раздела/подраздела, как показано в следующем далее разделе.
В нижней части каждой страницы должен находиться следующий колонтитул для упрощения навигации:
{{UM/foot|Предыдущая страница|Следующая страница}}
Это отображается, как
Redirects to fix
- Meta → Meta:Contents
- Meta:FR/Style Guide → Meta:~FR/Guides/Style Guide
Предыдущая страница и Следующая страница, конечно же, должны быть действительными ссылками на правильные страницы!
[edit] Шаблоны
Существует ограниченный набор шаблонов определенных рабочей группой (DocBoard), в том числе примечания, шаблоны клавиш и многое другое. Убедительно просим Вас использовать их и только их.
| На самом деле ситуация несколько двоякая, ибо в оригинале множество шаблонов не имеют возможности локализации. При этом остается техническая возможность использовать свои локализованные версии. см. подробнее Прим. пер. |
Со списком шаблонов можно ознакомиться здесь: Шаблоны
Также настоятельно рекомендуется использовать {{Literal|}}, в качестве "обертки" для ссылок на пункты GUI (имя элемента управления, меню, ...).
[edit] Справочные Материалы
При написании справочных материалов, таких, как руководство пользователя, пожалуйста, используйте шаблон Template:RefBox совместно со связанной структурой подзаголовков. Это поможет сохранять руководство согласованным, когда общая информация расположена в четко определенных и легко узнаваемых местах, так что людям будет быстрее и проще находить требуемую информацию. Обратитесь к Принцип ReferenceBox для получения дополнительной информации, а также используйте как руководство по использованию этой структуры. Пример ReferenceBox приведен ниже:
Режим: Режим редактирования (Mesh)
Горячая клавиша: Ctrl R
Меню: Mesh → Edges → Loop Subdivide...
Если вы станете использовать эти шаблоны как можно чаще, вы тем самым сэкономите время и себе, и вашим читателям. Нет более необходимости объяснять, длинной прозой "Чтобы использовать этот инструмент, необходимо нажать клавишу X на вашей клавиатуре", если есть хорошее изображение клавиши в заголовке, в определенном месте, когда читатели знают, где быстро его найти. Руководство не является новеллой; ваши тексты должны быть лаконичны и точка!
[edit] Typography
Возможно, будет полезно добавить общие правила Английский типографии, и, возможно, ссылку на сайт, посвященный этой теме... Как я уже сделал во французской версии этой страницы. --Mont29 14:21, 18 February 2009 (UTC)
[edit] Принципы использования Изображений
Использование изображений в документации имеет важнейшее значение. Форматы JPG и PNG категорически предпочтительны. Тогда как GIF и другие несвободные форматы крайне не приветствуются. Несжатые форматы, такие как TGA также не приветствуются.
Чтобы загрузить изображения в Вики, воспользуйтесь соответствующей ссылкой http://mediawiki.blender.org/index.php/Special:Upload.
[edit] Плавающие изображения
Плавающие изображения должны иметь заголовок и ссылки в тексте. Пожалуйста, воздержитесь от использования формулировок типа "следующее изображение" или "на следующем рисунке". Используйте перекрестные ссылки, описанные здесь.
Не приветствуется использование изображений без ссылок на них. Если у вас есть изображение, как сослаться на которое вы не знаете, то либо изображение не является необходимым, либо тексту не хватает ясности.
Документация, как Основная, так и Уроки, должна сохранять целостность. Размеры изображений не должны превышать 800x600. Использование изображений более 800 пикселей настоятельно не рекомендуется, так как они слишком широки для комфортного чтения в Веб-браузере.
Наиболее характерной особенностью интерфейса Blender’a является то, что он полностью реализован средствами OpenGL и поэтому легко масштабируется. Это, правда здорово, однако, ведет ко все возрастающему нарушению единообразия, когда многие пользователи прибегают к снимкам экрана, чтобы показать различные типы настроек, такие как специфические настройки материалов, настройки текстур и т.п.
Для обеспечения, как четкости, так и единообразия следует задать размер для интерфейса так, чтобы красный ползунок в окне материалов был 18 пикселей в высоту. Это тот размер, который Blender задаст, если у вас "по умолчанию" используется разрешение экрана 1024x768, и вы нажмете кнопку ‘home’ -- в то время как курсор находится над окном кнопок -- установится размер кнопки по умолчанию.
Если вы используете большее разрешение, пожалуйста, снизьте его до 1024x768 для захвата экрана. Я надеюсь, что ни у кого не осталось экранов с меньшим разрешением! Одним из способов для захвата экрана в разрешении 1024x768, когда ваш дисплей использует более высокое разрешение -- является использование оконного режима из командной строки со следующими настройками:
./blender -w -p 0 0 1024 768
Это приведет к запуску Blender’a в окне с отображаемой областью ровно 1024x768 пикселей. Рамка приложения будет больше из-за вставок рабочего стола. Для захвата части рабочего стола занимаемой Blender’ом можно использовать GIMP с регионом выделения фиксированного размера (1024x768) и он будет автоматически захватывать область Blender’a минус обрамление окна, произведенное рабочим столом.
Снимки экрана должны быть в LOSSLESS формате, так что используйте PNG.
Если вам необходимо выделить определенный участок изображения (кнопку, значение, или группы кнопок и значений), пожалуйста, повсеместно используйте желтую (R=255, G=255, В=0) рамку 2 пикселя толщиной.
Используйте стиль UI Blender’a по умолчанию.
[edit] Изображения в строке
Изображения иконок Blender’a в строке приветствуются, ибо делают описания гораздо понятнее. Поскольку это СТАНДАРТНЫЕ изображения, пожалуйста, воздержитесь от создания ваших собственных. Используйте набор, любезно предоставленный рабочей группой (DocBoard).
[edit] Смайлики в тексте и т.п.
Официальная документация не является местом для смайликов. (Юмор это другой вопрос, конечно, вы можете использовать юмор там, где это уместно!)
[edit] Таблицы
Таблицы -- есть соответствующий способ для отображения больших объемов данных в четко структурированном виде. Они могут стать реальной альтернативой снимкам экрана для демонстрации различных настроек.
Таблицы, как и плавающие изображения, должны иметь заголовок и ссылки в тексте.
[edit] Код
Wiki имеет удобную среду для отображения кусков кода Python/C/любогодругогоязыка.
Куски кода, как и плавающие изображения, должны иметь заголовок и ссылки в тексте.
[edit] Стиль документирования на практике
В этой главе приводится подробный пример того, чего мы ожидаем от внешнего вида ваших Wiki страниц.
[edit] Примеры изображений
Здесь приведены примеры того, как можно вставлять изображения на ваши страницы, после того как они загружены на сервер:
[edit] Обычные изображения
Этот способ является самым простым способом поместить изображения в пределах вашего текста, и в то же время самым безопасным, поскольку вам не нужно беспокоиться об обтекании изображения текстом:
[[Image:DemoImage1.png|none|frame|Демо изображение №1]]
Этот код помещает изображение в начало новой строки, при этом весь текст переносится на следующую строку:
[edit] Плавающие изображения
Чтобы получить изображение с обтеканием текста слева, используйте следующий синтаксис:
[[Image:Dummy.jpg|right|thumb|200px|Dummy image]]
Поместите этот код в начало первой (той) строки, где вы хотите, чтобы изображение было.
Чтобы отсечь текст до конца изображения, используйте следующий синтаксис:
{{clr}}
[edit] Изображения в строке
Изображения в строке вроде 
получить еще проще:
[[Image:DemoImage2.png]]
[edit] Изображения в таблицах
Если у вас есть набор небольших изображений, которые имеют некоторое отношение друг к другу, вы можете поместить их в простую таблицу:
{|
|valign=top|[[Image:Manual-Part-III-materialRampsExample04.png|thumb|200px|none|No Ramp Shader.]]
|valign=top|[[Image:Manual-Part-III-materialRampsExample05.png|thumb|200px|none|Color Ramp.]]
|valign=top|[[Image:Manual-Part-III-materialRampsExample06.png|thumb|200px|none|Both Color and Specular Ramp.]]
|}
 |  |  |
[edit] Дополнительная справка по Изображениям
Обратившись к этой странице, вы найдете исчерпывающую информацию об использовании изображений: Изображения и другие загружаемые файлы
[edit] Таблицы
Таблицы могут быть написаны либо в HTML, либо с использованием значительно более простого Wiki синтаксиса:
{| border="1" cellpadding="2"
|+Таблица умножения
|-
! × !! 1 !! 2 !! 3
|-
! 1
| 1 || 2 || 3
|-
! 2
| 2 || 4 || 6
|-
! 3
| 3 || 6 || 9
|-
! 4
| 4 || 8 || 12
|-
! 5
| 5 || 10 || 15
|}
что создает
| × | 1 | 2 | 3 |
|---|---|---|---|
| 1 | 1 | 2 | 3 |
| 2 | 2 | 4 | 6 |
| 3 | 3 | 6 | 9 |
| 4 | 4 | 8 | 12 |
| 5 | 5 | 10 | 15 |
Для облегчения форматирования есть предопределенный шаблон 'UM/prettytable'
{| {{UM/prettytable|50%}}
|align=center | 1
|align=center | 2
|align=center | 3
|-
|align=center | 4
|align=center | 5
|align=center | 6
|}
произведет
| 1 | 2 | 3 |
| 4 | 5 | 6 |
[edit] О Синтаксисе таблиц более подробно
Обратившись к этой странице, вы найдете исчерпывающую информацию об использовании таблиц: Таблицы
[edit] Код
Все приведенные выше примеры Wiki кода были получены путем инкапсуляции их в пары <nowiki></nowiki>.
Поставив один или несколько пробелов в начале каждой строки, получим строки, которые отображаются как:
эта
Другим способом достичь того же (для больших кусков кода, например), является инкапсуляция их в пары <pre></pre>.
Кроме того, если вам нужен другой результат или вы хотите отобразить большой кусок кода, вы можете использовать <code></code>, что приведет к следующему:
Это пример
[edit] Перекрестные ссылки
Перекрестные ссылки делаются wiki способом, если в предыдущих версиях Документации мы использовали ярлыки для обозначения объектов. То Wiki использует имя объекта, поэтому необходима схема *уникального* именования изображений.
[edit] Имена файлов
Имена файлов достаточно деликатный вопрос, поскольку они должны быть уникальны в пределах всего проекта Документации Blender’a и должны быть самоочевидными для перекрестных ссылок с одной главы на другую и т.д.
Таким образом, настоятельно рекомендуется придерживаться такого стандарта:
Для Основной документации
Manual/self-explanatory-name
Для изображений в Основной документации схема именования является аналогичной. Но, к сожалению, '/' не принимается системой, так что используйте '-' вместо '/'. Например:
Manual-self-explanatory-name.ext
Определение имени целиком принадлежит автору, как и ответственность за сохранение уникальности имен.
![[]](/skins/blender/open.png)
