Difference between revisions of "Help:Style (Русский)"

From ArchWiki
Jump to: navigation, search
m (Правка ссылок на Help:Editing (Русский) в связи с его обновлением)
m (Fixed link from "Article Naming Guidelines" to "Article Naming Guidelines (Русский)")
Line 19: Line 19:
 
===Заголовок статьи===
 
===Заголовок статьи===
 
* Если предмет статьи имеет популярное краткое наименование (акроним) наряду с полным, используйте в качестве названия статьи полное, затем создайте страницу с кратким и поместите в ней [[Help:Editing (Русский)#Перенаправления|перенаправление]] на основную статью. '''Не используйте оба наименования в одном заголовке!'''
 
* Если предмет статьи имеет популярное краткое наименование (акроним) наряду с полным, используйте в качестве названия статьи полное, затем создайте страницу с кратким и поместите в ней [[Help:Editing (Русский)#Перенаправления|перенаправление]] на основную статью. '''Не используйте оба наименования в одном заголовке!'''
* См. также [[Article Naming Guidelines]].
+
* См. также [[Article Naming Guidelines (Русский)]].
  
 
===Структура===
 
===Структура===

Revision as of 13:21, 26 January 2013

Tango-preferences-desktop-locale.pngThis article or section needs to be translated.Tango-preferences-desktop-locale.png

Notes: please use the first argument of the template to provide more detailed indications. (Discuss in Help talk:Style (Русский)#)
Template:Article summary start

Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary end

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

Это краткое руководство по редактированию wiki страниц на Arch Linux Wiki. Для подробного изучения вопроса смотрите Help:Style.

Contents

Статьи

Заголовок статьи

  • Если предмет статьи имеет популярное краткое наименование (акроним) наряду с полным, используйте в качестве названия статьи полное, затем создайте страницу с кратким и поместите в ней перенаправление на основную статью. Не используйте оба наименования в одном заголовке!
  • См. также Article Naming Guidelines (Русский).

Структура

  • Используйте следующий порядок элементов:
  1. Категории
  2. Шаблон i18n
  3. Ссылки на иностранные Вики (необязательно)
  4. Шаблоны состояния (необязательно)
  5. Краткий обзор (необязательно)
  6. Вступление
  7. Содержание (генерируется автоматически, если есть достаточное количество разделов)
  8. Другие разделы, в зависимости от статьи

Категории

  • Каждая статья должна находиться хотя бы в одной категории.
  • Статья может быть отнесена к нескольким категориям, если они не являются родительскими друг для друга.
  • Категории должны быть перечислены вверху.
    Совет: Этим Arch Wiki отличается от других проектов на основе MediaWiki, таких как Википедия, содержащих категории в конце статьи.
  • Во избежание появления ненужных переносов строк вверху страницы, между категориями и шаблоном i18n не должно быть пустого места.
  • См. также Help:Category.

Шаблон i18n

  • Template:i18n нужно помещать в каждую переводимую и создаваемую страницу, если есть смысл её переводить.
  • См. также Help:i18n.

Ссылки на иностранные Вики

  • Не обращайте на них внимания и не вставляйте в свои статьи. Французский, немецкий и прочие "отщепенческие" вики-проекты не станут добавлять на свои страницы ссылки на русскоязычные статьи.
  • См. также Wikipedia:Википедия:Интервики.

Шаблоны состояния

  • Шаблоны состояния могут быть помещены после Template:i18n и над кратким обзором.
  • Также можно помечать шаблонами состояния отдельные секции.
  • Всегда сопровождайте шаблон состояния сообщением на странице обсуждения статьи. Вариант "я скопировал англоязычную статью, добавил плашку {{translateme}} и был таков" не катит!

Краткий обзор

  • Описывает предмет статьи и её цель.
  • Опционально расположен после Template:i18n и/или шаблонов состояния (если они есть).
  • См. также Writing Article Overviews.

Вступление

  • Вступление следует сразу за кратким обзором.
  • Скажите пару слов о предмете статьи, стараясь при возможности использовать авторское описание. Для примера см. MATE.
  • Не создавайте секций с названиями ==Вступление== или ==Краткое описание==: вступление должно следовать до первого раздела и автоматически генерируемого содержания.
  • См. также Writing Article Introductions.

Названия разделов

  • Должны начинаться с 2 (==) уровня, поскольку первй уровень (соответствующий тегу <h1>) зарезервирован для заголовков статей.
  • Не пропускайте уровни (Wiki Monkey вам в помощь).
  • Только первое слово с большой буквы (см. заголовок этого раздела).
  • Не используйте ссылок и форматирования в заголовке. Вместо этого используйте их в содержимом раздела.
  • См. также Effective Use of Headers.

Переносы линий

Шаблоны

  • Используйте шаблон Ic:
    {{ic|какой-то код}}
    для выделения коротких строк с кодом, файловых путей, имён команд, названий переменных и т. п. внутри абзаца.
  • Используйте шаблон Bc:
    {{bc|какой-то код}}
    для крупных фрагментов кода и содержимого файлов, отображаемых в отдельной рамке:
# iwconfig
lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0
#!/bin/sh

# Demo
echo "Hello World"
  • Для достаточно коротких случаев, когда вы уверены, что прокрутка в длину не понадобится (не забывайте, что не у всех широкоэкранные мониторы!)можно просто начать строку с пробела вместо испоользования {{bc|code}} (см. Editing).
  • Используйте шаблон Hc: {{hc|''команда''|''вывод команды''}}, для достижения следующего эффекта:
# iwconfig
lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0
  • Тем же способом можно отображать имя и содержимое файла: {{hc|имя|содеримое}}, например:
~/hello_world.sh
#!/bin/sh

# Demo
echo "Hello World"

Форматирование команд

  • Используйте знак $ в командах, выполняемых от имени обычного пользователя и # в командах, выполняемых суперпользователем.
    Note: Учтите, что # также нередко используется как символ комментария, так что старайтесь избегать неоднозначности толкования.
  • Команда всегда должна предваряться объяснением, заканчивающимяся двоеточием (:).
  • Используйте # command вместо $ sudo command, если только использование sudo не действительно необходимо.
  • Не предполагайте, что на машине пользователя есть sudo и подобные ему утилиты (gksu, kdesu и т. д.).
  • # sudo command — видите, где ошибка?
  • Не добавляйте комментарий в конце команды (e.g. # pacman -S foo #Install package foo)
  • Не используйте чрезмерно длинные команды: есть множество способов их разбиения.

Инструкции по модификации файлов

  • Не предполагайте использования конкретного редактора (nano, vim, emacs, ...), когда пишите инструкции по редактированию файлов.
  • По этой же причине не используйте команды неявного редактирования, такие как $ echo -e "clear\nreset" >> ~/.bash_logout, вместо этого пишите так:
Добавьте следующие строки к ~/.bash_logout:
clear
reset

Клавиатурные комбинации

Инструкции по операциям с пакетами

Официальные репозитории

  • For installation instructions of official packages, use a wording like this:
    Install package, available in the Official Repositories.
    The wiki code for this is [[pacman|Install]] {{Pkg|package}}, available in the [[Official Repositories]].
    The instructions for the installation of a list of packages should appear as:
    Install package1, package2 and package3, available in the Official Repositories.
    More basic phrasing examples may be:
    MyApplication can be installed with the package my-appplication, available in the Official Repositories.
    You can install MyApplication with the package my-appplication, available in the Official Repositories.
    You are granted the flexibility to adapt the wording to your specific article.
  • If the package is hosted in [core], [extra] or [community], do not make reference to the repository, thus facilitating maintenance since it is not uncommon for a package to be moved to a different repository. If however the package is hosted in an official repository which is not enabled by default ([multilib], [testing], etc.), mentioning it is required, using a wording like this:
    Install package, available in the Official Repositories. You must enable [multilib].
  • Giving an example of the pacman command needed for the installation is deprecated (except in the Beginners' Guide and its subpages), both for simplicity's sake (every Arch user should know pacman's article by memory) and to avoid errors such as pacman -Sy package or possibly never-ending discussions like the choice between pacman -S package and pacman -Syu package.
    All the more reason you should not suggest the use of pacman frontends or wrappers to install official packages.

Пакеты из AUR

  • For installation instructions of AUR packages use a wording like this:
    Install packageAUR, available in the Arch User Repository.
    The wiki code for this is Install {{AUR|package}}, available in the [[Arch User Repository]].
    You are granted the flexibility to adapt the wording to your specific article, although you should always make clear that the package is unofficial.
  • Do not give examples on how to install AUR packages, neither with the official method nor mentioning AUR helpers: every user who installs unofficial packages should have read the Arch User Repository article, and be aware of all the possible consequences on his system.

Управление модулями ядра

  • Giving examples of how to add modules to the MODULES array in /etc/rc.conf is deprecated: the standard phrasing is a simple list of the modules involved, possibly remarking dependencies or conflicts with other modules, and a link to Kernel modules.
  • Giving examples of how to load, remove, blacklist or perform any other basic operation with modules is deprecated: the standard phrasing is a description of the actions to be performed, and a link to Kernel modules.
  • The Beginners' Guide and its subpages are the only exceptions to the rules above.

Управление демонами

  • Giving examples of how to add daemons to the DAEMONS array in /etc/rc.conf is deprecated: the standard phrasing is a simple list of the daemons involved, possibly remarking dependencies or conflicts with other daemons, and a link to Daemon.
  • Giving examples of how to start, restart or stop daemons is deprecated: the standard phrasing is a description of the actions to be performed, and a link to Daemon.
    Nevertheless, if the requested action is not one of those, an example is acceptable, and it should make use of the rc.d command instead of using the full /etc/rc.d/daemon command path.
  • The Beginners' Guide and its subpages are the only exceptions to the rules above.

Заметки, Предупреждения, Советы

  • A Note should be used for information that somehow diverges from what the user would naturally expect at some point in the article. This includes also information that gives more in-depth knowledge on something in particular that otherwise would be considered a bit extraneous to the article. Another example is when needing to point out a temporary announcement like a change in the name of a package.
    A Note can also be used to highlight information that is important but easily overlooked by someone new to the subject area.
  • A Warning should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenarios as well as the conditions that could lead to or avoid such worst cases.
  • A Tip should indicate a method or procedure that could be useful and bring benefits to somebody, albeit not needed to complete the operation being dealt with, and therefore safely ignorable.
  • When two or more notes, warnings or tips have to appear one after each other at the same point of an article, prefer grouping their texts in a list inside a single template, avoiding stacking the templates unless they are completely unrelated. For example:
Tip:
  • Tip example #1.
  • Tip example #2.

Командные оболочки

  • Не предполагайте использования конкретной оболочки (т. е. bash), а если всё же делаете это, явным образом указывайте на используемую в скрипте оболочку.

Использование гипертекста

  • Try to interlink your article with as many others as you can, using the various keywords in the text.
  • For technical terms like system call not covered by an article in the ArchWiki, link to the relevant Wikipedia page.
  • When linking to other articles of the wiki do not use full URLs, but take advantage of the special syntax for interwiki links: [[Wiki Article]]. This will also let the wiki engine keep track of the internal links hence facilitating maintenance.
    See Help:Editing (Русский)#Ссылки for in-depth information and more advanced uses of interwiki links syntax.
  • Except in rare cases, you should not leave an article as a dead-end page (an article that does not link to any other) or an orphan page (an article that is not linked from any other).
  • Before writing a specific procedure in an article, or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
  • If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.

Раздел "Советы и рекоммендации"

  • Advanced tips or examples of using the software.
  • Standard title is Tips and tricks.
  • The various tips and tricks should be organized in subsections.

Раздел "Решение проблем"

  • Frequently asked questions regarding the software, or solutions to common problems (compare to #"Known issues" sections).
  • Standard title is Troubleshooting; Trouble shooting, Trouble-shooting, TroubleShooting are common mistake examples.
  • You can also report temporary workarounds for known bugs, but in this case it is very desirable that you provide a link to the bug report, and in case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
    There are great benefits in linking to a bug report both for readers and editors:
    • For readers, the Wiki does not become a stopping point: they can find more information close to the source that may have otherwise been missed by their search efforts.
    • For Wiki editors, it makes clean up easier by reducing the effort involved in researching whether the reported bug is still an issue; this can even lead to greater autonomy if the reader finds new information and comes back to edit the wiki.

Раздел "Известные ошибки"

  • Known bugs or usage problems which do not have a solution yet (compare to #"Troubleshooting" sections).
  • Standard title is Known issues.
  • If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.

Раздел "Смотрите также"

  • A list of links to references and sources of additional information.
  • This should be a list where each entry is started with *.
  • The standard title is See also, other similar titles like External links, More resources etc. should be avoided.

Недопустимое содержимое

  • Please do not sign articles, nor credit article authors: the ArchWiki is a work of the community, and the history of each article is enough for crediting its contributors.
    Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.
  • Uploading files is disabled for normal users, and including the existing images in articles is not allowed. As an alternative you can include links to external images or galleries, and if you need to draw simple diagrams you may use an ASCII editor like Asciiflow.

Языковые обороты

  • Предпочитайте формальный стиль, где это имеет смысл.
  • Не используйте сокращений таких как "уст-ка", "обновл-е" и так далее. Постарайтесь избегать типичных сокращений: "т.к.", "т.о." и им подобных – найдите другой способ сжимать ваши предложения (например, избавляя их от слов-паразитов).
  • Не используйте нетехнический сленг и оборотоы, не применяемых в литературной речи.
  • Не пишите от первого лица и не ссылайтесь, на свои мнение и опыт.

Страницы обсуждений

  • Add new discussions at the bottom of discussion pages and with a proper heading. You can also make use of the + tag at the top of each discussion page.
  • Indent your answers using colons at the beginning of new lines.
  • Do not edit your posts if somebody has already replied, otherwise you will break the flow of the discussion and make it difficult for others to further respond. Only striking (using <s> tags) words or sentences is allowed, but the related explanation should be given in a regular reply.
  • Always append a signature (~~~~) to your edits.
  • Discussion pages should not be categorized.
  • You should take care to strike the header of exhausted discussions using <s> tags.
    Exhausted discussions will be deleted a while after striking.
  • See also Help:Editing (Русский)#Страницы обсуждений пользователей.

Страницы категорий

  • Every category must be categorized under at least one parent category, except for root categories.
    Root categories are language categories, like Category:English and some other special categories: Category:DeveloperWiki, Category:Sandbox and Category:Template.
  • A category can be categorized under more than one category, provided one is not ancestor of the others.
  • Avoid circular relationships: two categories cannot be reciprocal ancestors.
  • Categories must be included at the top of the category page.
  • Categories should not redirect.

Перенаправления

  • Страницы с перенаправлениями не должны содержать больше ничего.

Страницы шаблонов

Пользовательские страницы

  • Не подлежат категоризации (проконсультируйтеь с администратором, если вам это очень необходимо).

Общие правила

Описание правок

  • The changes made daily to the articles are bravely checked by dedicated and voluntary patrollers, whom you must help by making sure that all your edits are accompanied by some explanation words in the "Summary" field of the editor page.
    • If the edit is minor, e.g. grammar or orthography corrections or the simple rewording of a sentence, a simple description of your edit is perfectly enough.
    • If you are performing a major change, e.g. adding, moving, modifying or removing content, besides summarizing your edit, you should make sure to explain the reason why you edited the article, even linking to a discussion on the wiki or the forums, if one exists at all.
    • An explanation is not mandatory in talk pages, where the why should be already evident.
      When deleting exhausted discussions, however, some explanation words are required (e.g. "closed discussion," "fixed," etc.) and including also the title of the discussion could help retrieving it in the history in case it needs to be reopened.
Tip: Take a look at the edit summaries in the Recent Changes to get an idea of what you should write in your summary, but be warned that unfortunately not all users respect these guidelines.
  • When performing major changes to articles, you should better try to split your work in multiple edits, based on the logical steps needed to complete the change.
    Especially when moving sections (both within the same article or between two articles), you should avoid also modifying their content in the same edit, otherwise it will be more difficult to check the consequent diff.

Теги HTML

  • Старайтесь не использовать теги HTML: предпочитайте шаблоны и другую вики-разметку (см. Help:Editing (Русский)).
  • When tempted to use <pre>code</pre>, always resort to {{bc|code}}. When tempted to use <tt>text</tt> or <code>text</code>, always resort to {{ic|text}}.
  • Especially avoid HTML comments (<!-- comment -->): it is likely that a note added in a HTML comment can be explicitly shown in the article's discussion page.
    You can add an appropriate Article status template in place of the comment.
  • Use <br> only when necessary: to start a new paragraph or break a line, put a blank line below it.
    Common exceptions to this rule are when it is necessary to break a line in a list item and you cannot use a sub-item, or inside a template and you cannot use a list.