diff options
Diffstat (limited to 'ru_RU.KOI8-R/books/fdp-primer/writing-style/chapter.sgml')
| -rw-r--r-- | ru_RU.KOI8-R/books/fdp-primer/writing-style/chapter.sgml | 497 |
1 files changed, 497 insertions, 0 deletions
diff --git a/ru_RU.KOI8-R/books/fdp-primer/writing-style/chapter.sgml b/ru_RU.KOI8-R/books/fdp-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..d2453ad864 --- /dev/null +++ b/ru_RU.KOI8-R/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,497 @@ +<!-- + The FreeBSD Russian Documentation Project + + $FreeBSD$ + $FreeBSDru: frdp/doc/ru_RU.KOI8-R/books/fdp-primer/writing-style/chapter.sgml,v 1.7 2005/06/14 13:02:03 andy Exp $ + + Original revision: 1.46 +--> + +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. +--> + +<chapter id="writing-style"> + <title>Стиль написания</title> + + <para>Для того, чтобы соблюсти общность между множеством авторов документации + FreeBSD, для них были написаны некоторые руководящие указания, которым они + должны следовать.</para> + + <variablelist> + <varlistentry> + <term>Используйте Американский вариант английского языка</term> + + <listitem> + <para>Существует несколько вариантов английского языка, с + отличающимися вариантами записи одинаковых слов. В случае, + если написания отличаются - используйте американский вариант. + <quote>color</quote>, а не <quote>colour</quote>, + <quote>rationalize</quote>, а не <quote>rationalise</quote>, и так + далее.</para> + + <note> + <para>Использование британского английского может быть принято при + предоставлении статей, но написание должно быть одинаковым во всём + документе. Другие документы, такие как книги, страницы Web-сайта, + справочные страницы и так далее, должны использовать американский + английский.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>Не используйте сокращений</term> + + <listitem> + <para>Не используйте кратких форм в английском тексте. Всегда пишите + фразу полностью. Будет неправильно написать <quote>Don't use + contractions</quote>.</para> + + <para>Избежание кратких форм позволяет выдерживать более формальный + тон, фраза более точна и ее гораздо легче перевести на другой + язык.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Используйте несколько запятых</term> + + <listitem> + <para>В списке объектов внутри параграфа отделяйте каждый пункт от + другого при помощи запятых. В английском тексте отделяйте последний + пункт от других при помощи запятой и слова <quote>and</quote>.</para> + + <para>К примеру, рассмотрим следующее:</para> + + <blockquote> + <para>This is a list of one, two and three items.</para> + </blockquote> + + <para>Это список из трех объектов <quote>one</quote>, + <quote>two</quote> и <quote>three</quote>, или список из двух пунктов + <quote>one</quote> и <quote>two and three</quote>?</para> + + <para>Лучше быть точным и включить запятую:</para> + + <blockquote> + <para>This is a list of one, two, and three items.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term>Избегайте лишних фраз</term> + + <listitem> + <para>Попытайтесь не использовать ненужных фраз. В частности, + <quote>the command</quote>, <quote>the file</quote> и <quote>man + command</quote>, наверное, излишни.</para> + + <para>Эти два примера показывают это для команд. Второй вариант + предпочтителен.</para> + + <informalexample> + <para>Use the command <command>cvsup</command> to update your + sources</para> + </informalexample> + + <informalexample> + <para>Use <command>cvsup</command> to update your sources</para> + </informalexample> + + <para>Эти два примера показывают это для имен файлов. Предпочтителен + второй вариант.</para> + + <informalexample> + <para>… in the filename + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para>… in + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para>Эти два примера показывают это для ссылок на справочную систему. + Предпочтителен второй вариант (второй вариант использует + <sgmltag>citerefentry</sgmltag>).</para> + + <informalexample> + <para>See <command>man csh</command> for more + information.</para> + </informalexample> + + <informalexample> + <para>See &man.csh.1;</para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry> + <term>Два пробела в конце предложений</term> + + <listitem> + <para>Всегда используйте два пробела в конце предложений, так как это + усиливает читабельность, и облегчает использование таких + инструментов, как <application>Emacs</application>.</para> + + <para>Хотя могут быть возражения, что заглавная буква, которая следует + за точкой, обозначает новое предложение, это не тот случай, особенно + при использовании имен. <quote>Jordan K. Hubbard</quote> является + хорошим примером; в этом имени есть заглавная <literal>H</literal>, + которая следует за точкой и пробелом, но это не новое + предложение.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Более подробную информацию о стиле написания можно найти в работе + Уильяма Странка <ulink url="http://www.bartleby.com/141/">Elements of + Style</ulink>.</para> + + <sect1 id="writing-style-guide"> + <title>Руководство по стилю</title> + + <para>Для того, чтобы исходный текст Руководства был выполнен в одном + стиле, когда много разных людей его редактируют, пожалуйста, следуйте + следующим соглашениям о стиле.</para> + + <sect2> + <title>Регистр букв</title> + + <para>Метки вводятся в нижнем регистре, <literal><para></literal>, + а <emphasis>не</emphasis> <literal><PARA></literal>.</para> + + <para>Текст, который появится в контексте SGML, обычно пишется в верхнем + регистре, <literal><!ENTITY…></literal> и + <literal><!DOCTYPE…></literal>, но <emphasis>не</emphasis> + <literal><!entity…></literal> и + <literal><!doctype…></literal>.</para> + </sect2> + + <sect2> + <title>Акронимы</title> + + <para>Акронимы обычно должны расшифровываться при первом появлении + в книге, например: "Network Time Protocol (<acronym + role="Network Time Protocol">NTP</acronym>)." После + определения акронима, обычно используется только он, + (а не термин целиком, если только в данном случае + использование полного термина не предпочтительнее). Обычно + акронимы определяются только один раз во всей книге. Но + если желаете, вы можете определять их в каждой главе.</para> + + <para>Первые три раза акроним должен помещаться внутри тегов + <acronym>, с атрибутом <literal>role</literal>, + где определен полный термин. Это позволяет создавать ссылку + на глоссарий, и выводить полное описание при наведении на + термин курсора мыши.</para> + </sect2> + + <sect2> + <title>Отступы</title> + + <para>Каждый файл начинается с отступа в колонке 0, + <emphasis>независимо</emphasis> от отступа файла, который может + включать этот файл.</para> + + <para>Открывающие метки увеличивают отступ на 2 пробела. Закрывающие + метки в свою очередь уменьшают отступ на 2 пробела. Заменяйте начальные + пробелы символами табуляции, насколько это возможно. Не используйте + пробелы перед символами табуляции, и не добавляйте дополнительных + пробелов в конце строки. Содержимое элементов должно иметь отступ в + два пробела, если содержимое превышает по размеру одну строку.</para> + + <para>Например, исходный код этого раздела выглядит примерно так:</para> + + <programlisting><![ CDATA [+--- This is column 0 +V +<chapter> + <title>...</title> + + <sect1> + <title>...</title> + + <sect2> + <title>Отступы</title> + + <para>Каждый файл начинается с отступа в колонке 0, + <emphasis>независимо</emphasis> от отступа файла, который может + включать этот файл.</para> + + <para>Каждая открывающая метка увеличивает отступ на 2 пробела, а каждая + закрывающая метка уменьшает его на 2 пробела. Заменяйте начальные + пробелы символами табуляции, насколько это возможно. Не используйте + пробелы перед символами табуляции, и не добавляйте дополнительных + пробелов в конце строки. Содержимое элементов должно иметь отступ в + два пробела, если содержимое превышает по размеру одну строку.</para> + + ... + </sect2> + </sect1> +</chapter>]]></programlisting> + + <para>Если для редактирования файлов вы используете + <application>Emacs</application> или <application>XEmacs</application>, + то должен быть автоматически загружен <literal>sgml-mode</literal>, а + локальные переменные <application>Emacs</application> в конце + каждого файла должны заставить включить эти стили.</para> + + <para>Пользователи <application>Vim</application> могут использовать + следующие команды для конфигурации: + + <programlisting>augroup sgmledit + autocmd FileType sgml set formatoptions=cq2l " Special formatting options + autocmd FileType sgml set textwidth=70 " Wrap lines at 70 columns + autocmd FileType sgml set shiftwidth=2 " Automatically indent + autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces + autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab + autocmd FileType sgml set autoindent " Automatic indentation +augroup END</programlisting> + + </sect2> + + <sect2> + <title>Стиль меток</title> + + <sect3> + <title>Отделение меток</title> + + <para>Метки, которые находятся на том же уровне, что и предыдущая + метка, должны отделяться пустой строкой, а те, что не находятся на + той же самой позиции, что и предыдущая метка, не должны:</para> + + <informalexample> + <programlisting><![ CDATA [<article> + <articleinfo> + <title>NIS</title> + + <pubdate>Октябрь 1999</pubdate> + + <abstract> + <para>... + ... + ...</para> + </abstract> + </articleinfo> + + <sect1> + <title>...</title> + + <para>...</para> + </sect1> + + <sect1> + <title>...</title> + + <para>...</para> + </sect1> +</article>]]></programlisting> + </informalexample> + </sect3> + + <sect3> + <title>Отделение меток</title> + + <para>Такие метки, как <sgmltag>itemizedlist</sgmltag>, которые всегда + будут иметь метки внутри них, и на самом деле сами в себе текстовых + данных не содержат, всегда располагаются на одном уровне.</para> + + <para>Таким меткам, как <sgmltag>para</sgmltag> и + <sgmltag>term</sgmltag>, не нужны другие метки для обычных символьных + данных, а их содержимое начинается сразу же после метки, <emphasis>на + той же самой строке</emphasis>.</para> + + <para>То же самое относится к закрытию этих двух типов меток.</para> + + <para>Это приводит к очевидной проблеме при смешивании этих + меток.</para> + + <para>В случае, когда начальная метка, которая не может содержать + символьных данных, непосредственно следует за меткой типа, требующего + других меток внутри нее для использования символьных данных, они + располагаются на отдельных строках. Вторая метка должна быть + размещена с отступом.</para> + + <para>Когда метка, которая может содержать символьные данные, + закрывается сразу после закрывающей метки, которая не может содержать + символьных данных, то они располагаются на одной и той же + строке.</para> + </sect3> + </sect2> + + <sect2> + <title>Изменения, затрагивающие только количество пробелов</title> + + <para>При коммите изменений <emphasis>не вносите изменения в содержимое + одновременно с изменениями в форматировании</emphasis>.</para> + + <para>Это нужно, потому что команды, которые переводят Руководство на + другие языки, могут быстро увидеть, как изменилось содержимое с вашим + коммитом без раздумий над тем, изменилась ли строка из-за содержания + или из-за другого расположения пробелов.</para> + + <para>К примеру, если вы добавили два предложения в абзац, и при этом + длины строк в абзаце теперь превысила 80 символов, сначала выполните + коммит ваших изменений с длинными строками. Затем измените перенос + строк и закоммитьте второе изменение. В сообщении, описывающем коммит + по второму изменению, обязательно укажите, что это несущественное + изменение, и что команды переводчиков могут его игнорировать.</para> + </sect2> + + <sect2> + <title>Непрерываемые пробелы</title> + + <para>Старайтесь избегать переводов строк там, где они могут выглядеть + некрасиво или делают неудобным отслеживание смысла фразы. Переводы + строк зависят от ширины выбранного формата вывода. В частности, + чтение HTML документации в текстовом навигаторе может привести к + появлению плохо сформатированных абзацев, как например:</para> + + <literallayout class="monospaced">Data capacity ranges from 40 MB to 15GB. Hardware compression …</literallayout> + + <para>Общая сущность <literal>&nbsp;</literal> запрещает перенос + строки между частями относящимися друг к другу. Используйте + прерываемые пробелы в подобных случаях:</para> + + <itemizedlist> + <listitem> + <para>между цифрами и величинами:</para> + <programlisting><![ CDATA [57600 bps]]></programlisting> + </listitem> + + <listitem> + <para>между названием программы и номером версии:</para> + <programlisting><![ CDATA [FreeBSD 4.7]]></programlisting> + </listitem> + + <listitem> + <para>между многословными названиями (используйте осторожно, когда + применяете это правило к фразам содержащим 3-4 и более слов. + Например: <quote>The FreeBSD Brazilian + Portuguese Documentation Project</quote>):</para> + <programlisting><![ CDATA [Sun Microsystems]]></programlisting> + </listitem> + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="writing-style-word-list"> + <title>Словарь</title> + + <para>Далее следует краткий список слов, написание которых дано в виде, + который должен использоваться в Проекте Документирования FreeBSD. Если + в этом списке нет слова, которое вы ищете, то обратитесь к <ulink + url="http://www.oreilly.com/oreilly/author/stylesheet.html">словарю + O'Reilly</ulink>.</para> + + <itemizedlist> + <listitem> + <para>2.2.X</para> + </listitem> + + <listitem> + <para>4.X-STABLE</para> + </listitem> + + <listitem> + <para>CD-ROM</para> + </listitem> + + <listitem> + <para>DoS <emphasis>(Denial of Service)</emphasis> </para> + </listitem> + + <listitem> + <para>Ports Collection</para> + </listitem> + + <listitem> + <para>IPsec</para> + </listitem> + + <listitem> + <para>Internet</para> + </listitem> + + <listitem> + <para>MHz</para> + </listitem> + + <listitem> + <para>Soft Updates</para> + </listitem> + + <listitem> + <para>Unix</para> + </listitem> + + <listitem> + <para>disk label</para> + </listitem> + + <listitem> + <para>email</para> + </listitem> + + <listitem> + <para>file system</para> + </listitem> + + <listitem> + <para>manual page</para> + </listitem> + + <listitem> + <para>mail server</para> + </listitem> + + <listitem> + <para>name server</para> + </listitem> + + <listitem> + <para>web server</para> + </listitem> + </itemizedlist> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> |