Writing an Application Manual/ru: Difference between revisions

From KDE UserBase Wiki
(Created page with "* Назва_програми/Manual # Страница содержания ** Назва_програми/Manual/An Introduction to Назва_програми ** Назва...")
(Updating to match new version of source page)
 
(51 intermediate revisions by 3 users not shown)
Line 2: Line 2:
==Заметки==
==Заметки==


Учебники будут включены как подчиненные страницы к основной странице программы. Для краткости я буду называть, что главную страницу, как''APPNAME'' . Тогда структура страниц должен быть примерно такой:
Учебники будут включены как подчиненные страницы к основной странице программы. Для краткости я буду называть, что главную страницу, как ''APPNAME'' . Тогда структура страниц должен быть примерно такой:


* Appname
* Appname
Line 19: Line 19:
Если некоторые из разделов учебника становятся слишком большими, вы можете разместить подразделения на отдельных страницах. Структура может быть такой:
Если некоторые из разделов учебника становятся слишком большими, вы можете разместить подразделения на отдельных страницах. Структура может быть такой:


* Назва_програми/Manual # Страница содержания
* Appname/Manual # Your Contents page
** Назва_програми/Manual/An Introduction to Назва_програми
** Appname/Manual/An Introduction to Appname
** Назва_програми/Manual/Configuration Choices
** Appname/Manual/Configuration Choices
** Назва_програми/Manual/The First Time you use Назва_програми
** Appname/Manual/The First Time you use Appname
** Назва_програми/Manual/"раздел 1"
** Appname/Manual/''section 1''
*** Назва_програми/Manual/"раздел 1"/"подраздел 1"
*** Appname/Manual/''section 1''/''subsection 1''
*** Назва_програми/Manual/"раздел 1"/"подраздел 2"
*** Appname/Manual/''section 1''/''subsection 2''
и т.д.
and so on.
 
{{Info/ru|Названия страниц не должны точно соответствовать структуре документа. В приведенном выше примере вы можете просто воспользоваться названием Программа/Учебник/"подраздел 2" вместо Программа/Учебник/"раздел 1"/"подраздел 2". То же касается низших уровней иерархии (конечно же, если в процессе названия не дублируются {{Smiley}}).}}
 
{{Remember/ru |Старайтесь использовать короткие названия и избегать слишком длинных путей в названии. Слишком длинные названия являются трудными для запоминания и введения, они выглядят неуклюже на страницах вики. Всегда помните: названия страниц и структура не влияют на завершенный вид учебника! Он определяется только заголовками в тексте.}}
 
Чтобы в автоматически созданном в учебнике в формате Docbook был тот же смысл, что и на UserBase, а ссылки в Docbook работали, следует придерживаться следующих установок:
 
* В содержании учебника в формате Docbook все разделы и подразделы будет показано независимо от того, есть ли у них своя страница. С другой стороны, подразделения высокого уровня вложенности не будет показано, даже если в этих подразделений является собственная страница.


{{Info|The page names do not have to follow the structure of the document closely! In the above example you could simply use Appname/Manual/''subsection 2'' instead of Appname/Manual/''section 1''/''subsection 2'' and similarly for sub-subsections (as long as this procedure does not produce duplicate names {{Smiley}}).}}
* На каждой странице раздела в верхней части должен быть заголовок раздела (== ... ==), подраздела (=== ... ===) или подподраздела(==== ... ====), иначе структура учебника в формате Docbook будет отличаться от задуманного.


{{Remember|Try to keep page names short and avoid long paths. Overly long page names are cumbersome to type when you link to them, and they don't look good on the wiki pages. And always remember: The page names and their structure have no influence on the finished handbook whatsoever! It is entirely determined by the headings in the actual text.}}
* Заголовок раздела или подраздела должно точно совпадать с названием страницы, иначе ссылки в Docbook будут работать не так, как это должно быть.


In order for the automatically generated Docbook to have the same contents page as the one you make on UserBase, and for links to work in the Docbook there are a couple or guidelines, that must be followed:
* Названия подразделений должно быть записано так: <code>==='''''Название'''''===</code>, даже если этот раздел является разделом наивысшего уровня на странице. Если не придерживаться этого правила, структуру Docbook будет искажено. Так же, если в вашем учебнике есть очень длинные подразделения, которые разделены на отдельные страницы, каждая из таких страниц должна иметь собственный заголовок в таком формате: <code>===='''''Название'''''====</code>.


* The Docbook Table of Contents will list all sections and subsections regardless of whether they have a page of their own. On the other hand, subsubsections won't be listed in the Docbook TOC even though they have a page of their own.
* Подразделения, которые не должно быть показано на странице содержания, и которые не имеют собственной страницы, в Docbook имеют уровень 4 или ниже, то есть заголовок уровня==== или ниже.


* All pages should have a heading at the very top, either a section (== ... ==), a subsection (=== ... ===), or a subsubsection (==== ... ====), otherwise the Docbook structure will be messed up.
* Ссылки на страницах учебника должны точно совпадать с названиями страниц (т.е. не должно быть переименований)


* The title of the section/subsection must exactly match the page name, otherwise Docbook links won't work.
* Если вы делаете ссылку на подраздел страницы, вам следует добавить отметку в соответствующем месте страницы. Если вы этого не сделаете, ссылки в переводах не будут работать.


* Subsection titles must be written like this: <code>==='''''title'''''===</code>, even if it is the top level on a page. Otherwise the Docbook structure will be messed up. Similarly, if you have a very long subsection with subsubsections on pages of their own, these pages must have their titles written like this: <code>===='''''title'''''====</code>.
{{Note/ru|1=В учебнике в формате DocBook каждое подразделение (===) будет иметь отдельную страницу, даже если это подразделение является частью более длинной страницы UserBase. Это означает, что раздел (==), который состоит из нескольких подразделений, но не содержит текста перед первым подразделением, будет иметь страницу Docbook, на которой не будет ничего, кроме ссылок на подразделы.}}


* Subsubsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.
{{Remember/ru |1=Если вам захочется изменить заголовок основного подразделения страницы (первый заголовок), важно также изменить соответствующим образом название страницы и все ссылки так, чтобы они совпадали с новым названием.}}


* Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)
{{Remember/ru |1=<span style="color:red;">пожалуйста, не используйте знаки препинания в названиях страниц</span> - знаки препинания, в частности знаки вопроса или точки, является достаточно серьезной проблемой для программного обеспечения вики, в частности системы перевода.}}


* If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.
Вам понадобится некий черновик для экспериментов с заголовками разделов и страниц учебника. Вы можете воспользоваться или собственной страницей обсуждения, или страницами из участка, над которой вы работаете. После завершения работы следует удалить все лишние страницы.


{{Note|1=Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.}}
== Начальный этап написания учебника ==


{{Remember|1=If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.}}
На начальном этапе создания вашего учебника лучше держать его отдельно от остальных данных UserBase. Можно редактировать черновики основной и подчиненных страниц на странице обсуждения вашей страницы пользователя. С этой целью нами также предусмотрен особое наименование <tt>Draft:</tt>.


{{Remember|1=<span  style="color:red;">Please do not use any kind of punctuation in your page names</span> &mdash; punctuation like question marks or periods creates serious problems for the wiki software, in particular for the translation system.}}
Чтобы создать страницу содержания вашего учебника, просто укажите в поле адреса вашей программы для просмотра интернет <tt><nowiki>http://userbase.kde.org/Draft:</nowiki>'''''Appname/Manual'''''</tt> или вставьте ссылку <nowiki>[[Draft:Appname/Manual]]</nowiki> на страницу, сохраните его, а затем нажмите его. В обоих вариантах действий будет открыта страница с сообщением о том, что страницы не существует, но вы можете создать ее нажатием ссылки.


You will need a scratchpad to experiment with section headings/pages.  You can use either your UserTalk page, or the discussion pages attached to the area where you are working.  It's helpful if you remove anything no longer required, once the job is completed.
===Содержание===


== Developing a Manual ==
* Когда все решение будет принято (процесс составления плана может быть довольно длительным), создайте соответствующие ссылки на страницы содержания. Конечно же, если вы пропустили нечто, позже можно будет добавить соответствующую ссылку.


While developing your manual it is usually best to keep it separate from the regular UserBase content. Some prefer to edit their drafts as subpages of their Talk: page. We also have a special <tt>Draft:</tt> namespace for this purpose.
===Сборка учебника===


To create the content page of your manual, simply write <tt><nowiki>http://userbase.kde.org/Draft:</nowiki>'''''Appname/Manual'''''</tt> in the address line of your browser, or place the <nowiki>[[Draft:Appname/Manual]]</nowiki> link in a page and then click it. Either way you will be taken to a page telling you that the page does not exist, but that you can create it clicking a link.
* Воспользуйтесь ссылками красного цвета для создания страниц, создавая разделы учебника один за одним.


===Contents===
* Записывайте на странице обсуждения все нужные впоследствии ссылки, в частности ссылки, данные для которых еще не создано.


* Once you have made the decisions (that can be a lengthy procedure), create appropriate links on the Contents page.    It is, of course, possible to insert a section later if you find you've missed something.
{{Remember/ru |1=Во время написания учебника следует придерживаться определенных правил, которые сделают вашу работу однородной:<!--}}-->


===Building your Manual===
* Следите за заголовками уровней - начинать всегда следует с второго уровня (в Mediawiki первый уровень используется для названия страницы), то есть следует использовать <nowiki>==</nowiki>


* Use the red links to create the page, and write up a section at a time.
* Заглядывайте время от времени на страницы [[Special:myLanguage/Tasks_and_Tools|задачи и инструменты]] и [[Special:myLanguage/Typographical_Guidelines|правила форматирования]].


* Note on the Discussion page anything you will need to refer to later, such as links that can't yet be created.
* Добавляйте пробел после символа вертикальной черты в таблицах. Это правило согласуется с [http://en.wikipedia.org/wiki/Help:Table традиционным форматированием вики].


{{Remember|1=It's important to be consistent, particularly in Manuals, so here are some general rules:<!--}}-->
* Используйте однородную систему форматирования для названий программ (используйте вместо '''Amarok'''s формат '''Amarok's''').


* Take care with heading levels - we start at second level (Mediawiki uses top level for page-name), using <nowiki>==</nowiki>
* Старайтесь использовать изображения  в формате '''PNG''' (можно использовать JPEG, но во время создания Docbook скрипт все равно преобразует изображения в формат PNG). Вы можете сэкономить время, если сделаете все правильно от начала [[Image:Smiley.png|16px]].


* Make sure you refer frequently to this page, to [[Special:myLanguage/Tasks_and_Tools|Tasks and Tools]] and to [[Special:myLanguage/Typographical_Guidelines|Typographical Guidelines]]
<!--{{-->* Не используйте символы Unicode (не ASCII) в названиях изображений.}}


* Check if all table cells have space after the pipe character. This rule conforms with [http://en.wikipedia.org/wiki/Help:Table traditional wiki formatting].
==== Formatting considerations ====


* Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's''').
In order for your manual to be translatable into Docbook format there are some restrictions on formatting that should be observed.  


* Ensure that '''all''' images are in PNG format (you can use JPEG as well, but in this case they should be converted to PNG by the script). Save work by converting them before you start [[Image:Smiley.png|16px]].
* [[Special:myLanguage/Toolbox#Notes and Warnings|Notes and Warnings]] do not support alternative titles in Docbook. Don't write something like <br /><code><nowiki>{{Remember|2=Don't Forget This!|1=You can use...}}</nowiki></code><br />The <code>2=...</code> part has no meaning in Docbook and the program transforming the wiki page to Docbook might get very confused. Just write<br /><code><nowiki>{{Remember|1=You can use...}}</nowiki></code>


<!--{{-->* Remove all non-printable characters from image names.}}
* [[Special:myLanguage/Toolbox#Embed a Video|Embed a Video]] has some limitations in its current implementation: Only YouTube and Vimeo are supported and only one value (the id of the video) can be passed as argument.


=== Searching your manual ===
=== Поиск в вашем учебнике ===


At some point, you may need to find something that you wrote earlier, but can't remember where. Using the wiki search box may not be ideal unless the string you search for is very specific. You can get much better control over searches using the DPL extension. For example, to find the pages in your manual containing a certain string, you can add the following to any page:
У вас может возникнуть потребность в поиске того, что вы писали раньше, но не помните, где именно. Использование поля поиска вики может будет неидеальным, если вы не ищете нечто очень специфическое. Гораздо лучшие результаты поиска можно получить с помощью расширения DPL. Например, чтобы найти страницы учебника, которые содержат определенную строку, вы можете добавить на любую страницу следующий код и нажать кнопку предварительного просмотра:


{{Input|1=<nowiki>
{{Input|1=<nowiki>
<DPL>
<DPL>
   titlematch = %Appname/Manual%
   titlematch = %Appname/Manual%
   namespace = Draft
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
   namespace = | Draft
   include = *
   include = *
   includematch = /string to search for/
   includematch = /string to search for/
  includemaxlength = 0
   resultsheader = Manual Pages:
   resultsheader = Manual Pages:
   format = ,\n* [[%PAGE%|%TITLE%]]\n,,
   format = ,\n* [[%PAGE%|%TITLE%]]\n,,
Line 101: Line 111:
</nowiki>}}
</nowiki>}}


You can find more examples on using DPL on [[User:Claus_chr/DPL]].
Другие примеры использования DPL можно найти на странице [[User:Claus_chr/DPL]].
 
{{Note|1=If You are working on the Amarok manual be aware that some of the pages deviate from the normal naming convention. To find matches on all Amarok manual pages use
{{Input|1=titlematch = %Amarok/QuickStartGuide%{{!}}%Amarok/Manual%}}
(Note that there can be no space characters on either side of the '{{!}}' character)
}}
 
==Приготовления учебника к переводу==
 
* Шаги по редактированию разметки можно найти на странице [[Special:myLanguage/Edit Markup|приготовления страницы к переводу]]. Воспользуйтесь советами  этой страницы, поскольку устаревшие стили разметки могут быть непригодными к использованию.


==Preparing the Manual for Translation==
== Создание руководства в DocBook ==


* The steps for markup editing can be found on [[Special:myLanguage/Edit Markup|Preparing a Page for Translation]].  Please adhere to that guide, since old markup styles may not still be relevant.
Как только ваше руководство написано, вы можете иметь его конвертировать его в руководство DocBook, так, что ваша работа может быть использован как обычное руководство KDE. Эта процедура описана на  [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook|этой странице]].  


[[Category:Contributing]]
[[Category:Contributing]]

Latest revision as of 13:40, 29 August 2018

Other languages:

Заметки

Учебники будут включены как подчиненные страницы к основной странице программы. Для краткости я буду называть, что главную страницу, как APPNAME . Тогда структура страниц должен быть примерно такой:

  • Appname
    • Appname/Hints and Tips
  • Appname/Manual # Your Contents page
    • Appname/Manual/An Introduction to Appname
    • Appname/Manual/Configuration Choices
    • Appname/Manual/The First Time you use Appname
    • Appname/Manual/section 1
    • Appname/Manual/section xxx
    • Appname/Manual/Hints and Tips
    • Appname/Manual/Troubleshooting
    • Appname/Manual/Bug reports
    • Appname/Manual/Get involved #link to techbase etc

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

  • Appname/Manual # Your Contents page
    • Appname/Manual/An Introduction to Appname
    • Appname/Manual/Configuration Choices
    • Appname/Manual/The First Time you use Appname
    • Appname/Manual/section 1
      • Appname/Manual/section 1/subsection 1
      • Appname/Manual/section 1/subsection 2

and so on.

Информация

Названия страниц не должны точно соответствовать структуре документа. В приведенном выше примере вы можете просто воспользоваться названием Программа/Учебник/"подраздел 2" вместо Программа/Учебник/"раздел 1"/"подраздел 2". То же касается низших уровней иерархии (конечно же, если в процессе названия не дублируются ).


Напоминание

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


Чтобы в автоматически созданном в учебнике в формате Docbook был тот же смысл, что и на UserBase, а ссылки в Docbook работали, следует придерживаться следующих установок:

  • В содержании учебника в формате Docbook все разделы и подразделы будет показано независимо от того, есть ли у них своя страница. С другой стороны, подразделения высокого уровня вложенности не будет показано, даже если в этих подразделений является собственная страница.
  • На каждой странице раздела в верхней части должен быть заголовок раздела (== ... ==), подраздела (=== ... ===) или подподраздела(==== ... ====), иначе структура учебника в формате Docbook будет отличаться от задуманного.
  • Заголовок раздела или подраздела должно точно совпадать с названием страницы, иначе ссылки в Docbook будут работать не так, как это должно быть.
  • Названия подразделений должно быть записано так: ===Название===, даже если этот раздел является разделом наивысшего уровня на странице. Если не придерживаться этого правила, структуру Docbook будет искажено. Так же, если в вашем учебнике есть очень длинные подразделения, которые разделены на отдельные страницы, каждая из таких страниц должна иметь собственный заголовок в таком формате: ====Название====.
  • Подразделения, которые не должно быть показано на странице содержания, и которые не имеют собственной страницы, в Docbook имеют уровень 4 или ниже, то есть заголовок уровня==== или ниже.
  • Ссылки на страницах учебника должны точно совпадать с названиями страниц (т.е. не должно быть переименований)
  • Если вы делаете ссылку на подраздел страницы, вам следует добавить отметку в соответствующем месте страницы. Если вы этого не сделаете, ссылки в переводах не будут работать.

Примечание

В учебнике в формате DocBook каждое подразделение (===) будет иметь отдельную страницу, даже если это подразделение является частью более длинной страницы UserBase. Это означает, что раздел (==), который состоит из нескольких подразделений, но не содержит текста перед первым подразделением, будет иметь страницу Docbook, на которой не будет ничего, кроме ссылок на подразделы.


Напоминание

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


Напоминание

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


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

Начальный этап написания учебника

На начальном этапе создания вашего учебника лучше держать его отдельно от остальных данных UserBase. Можно редактировать черновики основной и подчиненных страниц на странице обсуждения вашей страницы пользователя. С этой целью нами также предусмотрен особое наименование Draft:.

Чтобы создать страницу содержания вашего учебника, просто укажите в поле адреса вашей программы для просмотра интернет http://userbase.kde.org/Draft:Appname/Manual или вставьте ссылку [[Draft:Appname/Manual]] на страницу, сохраните его, а затем нажмите его. В обоих вариантах действий будет открыта страница с сообщением о том, что страницы не существует, но вы можете создать ее нажатием ссылки.

Содержание

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

Сборка учебника

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

Напоминание

Во время написания учебника следует придерживаться определенных правил, которые сделают вашу работу однородной:
  • Следите за заголовками уровней - начинать всегда следует с второго уровня (в Mediawiki первый уровень используется для названия страницы), то есть следует использовать ==
  • Используйте однородную систему форматирования для названий программ (используйте вместо Amaroks формат Amarok's).
  • Старайтесь использовать изображения в формате PNG (можно использовать JPEG, но во время создания Docbook скрипт все равно преобразует изображения в формат PNG). Вы можете сэкономить время, если сделаете все правильно от начала .
  • Не используйте символы Unicode (не ASCII) в названиях изображений.


Formatting considerations

In order for your manual to be translatable into Docbook format there are some restrictions on formatting that should be observed.

  • Notes and Warnings do not support alternative titles in Docbook. Don't write something like
    {{Remember|2=Don't Forget This!|1=You can use...}}
    The 2=... part has no meaning in Docbook and the program transforming the wiki page to Docbook might get very confused. Just write
    {{Remember|1=You can use...}}
  • Embed a Video has some limitations in its current implementation: Only YouTube and Vimeo are supported and only one value (the id of the video) can be passed as argument.

Поиск в вашем учебнике

У вас может возникнуть потребность в поиске того, что вы писали раньше, но не помните, где именно. Использование поля поиска вики может будет неидеальным, если вы не ищете нечто очень специфическое. Гораздо лучшие результаты поиска можно получить с помощью расширения DPL. Например, чтобы найти страницы учебника, которые содержат определенную строку, вы можете добавить на любую страницу следующий код и нажать кнопку предварительного просмотра: 

<DPL>
  titlematch = %Appname/Manual%
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
  namespace = | Draft
  include = *
  includematch = /string to search for/
  includemaxlength = 0
  resultsheader = Manual Pages:
  format = ,\n* [[%PAGE%|%TITLE%]]\n,,
</DPL>

Другие примеры использования DPL можно найти на странице User:Claus_chr/DPL.

Note

If You are working on the Amarok manual be aware that some of the pages deviate from the normal naming convention. To find matches on all Amarok manual pages use 
titlematch = %Amarok/QuickStartGuide%|%Amarok/Manual%
(Note that there can be no space characters on either side of the '|' character)


Приготовления учебника к переводу

  • Шаги по редактированию разметки можно найти на странице приготовления страницы к переводу. Воспользуйтесь советами этой страницы, поскольку устаревшие стили разметки могут быть непригодными к использованию.

Создание руководства в DocBook

Как только ваше руководство написано, вы можете иметь его конвертировать его в руководство DocBook, так, что ваша работа может быть использован как обычное руководство KDE. Эта процедура описана на этой странице.

Retrieved from "https://userbase.kde.org/index.php?title=Writing_an_Application_Manual/ru&oldid=399374"