Writing an Application Manual/uk: Difference between revisions

Latest revision as of 07:58, 26 August 2019

Other languages:

English
català
dansk
français
русский
українська

Нотатки

Підручники буде включено як підлеглі сторінки до основної сторінки програми. Нехай, основна сторінка програми має назву Appname. Тоді структура сторінок має бути десь такою:

Appname
- Appname/Hints and Tips
Appname/Manual # Сторінка змісту
- 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 # посилання на сторінку techbase тощо

Якщо деякі з розділів підручника стають занадто великими, ви можете розташувати підрозділи на окремих сторінка. Структура може бути такою:

Назва_програми/Manual # Сторінка змісту
- Назва_програми/Manual/An Introduction to Назва_програми
- Назва_програми/Manual/Configuration Choices
- Назва_програми/Manual/The First Time you use Назва_програми
- Назва_програми/Manual/розділ 1
  - Назва_програми/Manual/розділ 1/підрозділ 1
  - Назва_програми/Manual/розділ 1/підрозділ 2

тощо.

Інформація

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

).

Пам’ятайте!

Намагайтеся використовувати короткі назви і уникати надто довгих шляхів у назві. Надто довгі назви є важкими для запам’ятовування та введення, вони виглядають незграбно на сторінках вікі. Завжди пам’ятайте: назви сторінок та структура не впливають на завершений вигляд підручника! Він визначається лише заголовками у тексті.

Щоб у автоматично створеному підручнику у форматі Docbook був той самий зміст, що і на UserBase, а посилання у Docbook працювали, варто дотримуватися таких настанов:

У змісті підручника у форматі Docbook всі розділи і підрозділи буде показано незалежно від того, чи є у них власна сторінка. З іншого боку, підрозділи високого рівня вкладеності не буде показано, навіть якщо у цих підрозділів є власна сторінка.

На кожній сторінці розділу у верхній частині має бути заголовок, розділу (== ... ==), підрозділу (=== ... ===) або підпідрозділу (==== ... ====), інакше структура підручника у форматі Docbook відрізнятиметься від задуманої.

Заголовок розділу або підрозділу має точно збігатися з назвою сторінки, інакше посилання у Docbook працюватимуть не так, як це має бути.

Назви підрозділів має бути записано так: ===Назва===, навіть якщо цей розділ є розділом найвищого рівня на сторінці. Якщо не дотримуватися цього правила, структуру Docbook буде спотворено. Так само, якщо у вашому підручнику є дуже довгі підрозділи, які поділено на окремі сторінки, кожна з таких сторінок повинна мати власний заголовок у такому форматі: ====Назва====.

Підрозділи, які не має бути показано на сторінці змісту, і які не мають власної сторінки, у Docbook мають рівень 4 або нижче, тобто заголовок рівня ==== або нижче.

Посилання на сторінках підручника мають точно збігатися з назвами сторінок (тобто не повинно бути переспрямувань)

Якщо ви робите посилання на підрозділ сторінки, вам слід додати позначку на відповідному місці сторінки. Якщо ви цього не зробите, посилання у перекладах не працюватимуть.

Зауваження

У підручнику у форматі DocBook кожен підрозділ (===) матиме окрему сторінку, навіть якщо цей підрозділ є частиною довшої сторінки UserBase. Це означає, що розділ (==), який складається з декількох підрозділів, але не містить тексту перед першим підрозділом, матиме сторінку Docbook, на якій не буде нічого, окрім посилань на підрозділи.

Пам’ятайте!

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

Пам’ятайте!

Будь ласка, не використовуйте знаки пунктуації у назвах сторінок — знаки пунктуації, зокрема знаки запитання або крапки, є доволі серйозною проблемою для програмного забезпечення вікі, зокрема системи перекладу.

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

Початковий етап написання підручника

На початковому етапі створення вашого підручника краще тримати його окремо від решти даних UserBase. Можна редагувати чернетки основної та підлеглих сторінок на сторінці обговорення вашої сторінки користувача. З цією метою нами також передбачено особливий прострі назв Draft:.

Щоб створити сторінку змісту вашого підручника, просто вкажіть у полі адреси вашої програми для перегляду інтернету http://userbase.kde.org/Draft:Назва_програми/Назва_підручника або вставте посилання [[Draft:Appname/Manual]] на сторінку, збережіть його, а потім натисніть його. За обох варіантів дій буде відкрито сторінку з повідомленням про те, що сторінки не існує, але ви можете створити її натисканням посилання.

Зміст

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

Збирання підручника

Скористайтеся посиланнями червоного кольору для створення сторінок, створюючи розділи підручника один за одним.

Занотовуйте на сторінці обговорення всі потрібні згодом посилання, зокрема посилання, дані для яких ще не створено.

Пам’ятайте!

Під час написання підручника варто дотримуватися певних правил, які зроблять вашу роботу однорідною:

Слідкуйте за заголовками рівнів — починати слід завжди з другого рівня (у Mediawiki перший рівень використовується для назви сторінки), тобто слід використовувати ==

Зазирайте час від часу на сторінки завдань та інструментів та правил форматування.

Додавайте пробіл після символу вертикальної риски у таблицях. Це правило узгоджується з традиційним форматуванням вікі.

Використовуйте однорідну систему форматування для назв програм (використовуйте замість Amaroks формат Amarok's).

Намагайтеся використовувати зображення лише у форматі PNG (можна використовувати JPEG, але під час створення Docbook скрипт все одно перетворить їх на зображення у форматі PNG). Ви можете зекономити час, якщо зробите все правильно від початку .

Не використовуйте символи Unicode (не ASCII) у назвах зображень.

Правила форматування

Якщо ви маєте наміт перетворити підручник до придатного до перекладу формату Docbook, слід взяти до уваги деякі обмеження щодо форматування.

Нотатки і попередження у Docbook не можуть мати альтернативних назв. Не пишіть чогось подібного до
{{Remember|2=Don't Forget This!|1=You can use...}}
Частину 2=... у Docbook буде пропущено. Скрипт перетворення сторінки вікі у Docbook може не спрацювати як слід. Просто напишіть
{{Remember|1=You can use...}}

Вбудовування відео у поточній реалізації має певні обмеження: можна вбудовувати лише відео з YouTube та Vimeo і можна передавати лише один аргумент (ідентифікатор відео).

Пошук у вашому підручнику

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

<DPL>
  titlematch = %Appname/Manual%
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
  namespace = | Draft
  include = *
  includematch = /рядок, який слід знайти/
  includemaxlength = 0
  resultsheader = Manual Pages:
  format = ,\n* [[%PAGE%|%TITLE%]]\n,,
</DPL>

Інформація

Інші приклади використання DPL можна знайти на сторінці User:Claus_chr/DPL. Простішим способом пошуку рядків у підручнику є використання шаблону SearchPages: щоб виконати пошук рядка «timeline» у підручнику з Kdenlive, напишіть у коді сторінки {{SeatchPages|1=Kdenlive/Manual|2=[Tt]imeline}}.

Підказка для досвідчених: щоб побачити результати пошуку, вам не потрібно зберігати сторінку — достатньо попереднього перегляду. Коли список результатів буде виведено, ви можете просто скасувати результати редагування.

Зауваження

Якщо ви працюєте з підручником із Amarok, зважайте на те, що сторінки підручника названо не у повній відповідності із правилами. Можете скористатися

titlematch = %Amarok/QuickStartGuide%|%Amarok/Manual%.

(Зауваження: у взірці немає символів пробілів навколо |)

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

Кроки з редагування розмітки можна знайти на сторінці приготування сторінки до перекладу. Скористайтеся порадами з цієї сторінки, оскільки застарілі стилі розмітки можуть бути непридатними до використання.

Створення підручника у форматі DocBook

Щойно роботу над створеним вами підручником буде завершено, ви можете перетворити його на підручник у форматі DocBook, щоб ним можна було користуватися як звичайним підручником до програми KDE. Докладний опис перетворення можна знайти на цій сторінці.

@@ Line 2: / Line 2: @@
 ==Нотатки==
-Manuals will be included as sub-pages of the main application page.  For brevity, I will refer to that main page as ''Appname''.  The structure, therefore would be something like:
+Підручники буде включено як підлеглі сторінки до основної сторінки програми. Нехай, основна сторінка програми має назву ''Appname''. Тоді структура сторінок має бути десь такою:
 * Appname
 ** Appname/Hints and Tips
-* Appname/Manual # Your Contents page
+* Appname/Manual # Сторінка змісту
 ** Appname/Manual/An Introduction to Appname
 ** Appname/Manual/Configuration Choices
@@ Line 14: / Line 14: @@
 ** Appname/Manual/Hints and Tips
 ** Appname/Manual/Troubleshooting
-** Appname/Manual/Found a bug?
+** Appname/Manual//Bug reports
-** Appname/Manual/Get involved #link to techbase etc
+** Appname/Manual/Get involved # посилання на сторінку techbase тощо
-{{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.}}
+Якщо деякі з розділів підручника стають занадто великими, ви можете розташувати підрозділи на окремих сторінка. Структура може бути такою:
-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.
+* Назва_програми/Manual # Сторінка змісту
+** Назва_програми/Manual/An Introduction to Назва_програми
+** Назва_програми/Manual/Configuration Choices
+** Назва_програми/Manual/The First Time you use Назва_програми
+** Назва_програми/Manual/''розділ 1''
+*** Назва_програми/Manual/''розділ 1''/''підрозділ 1''
+*** Назва_програми/Manual/''розділ 1''/''підрозділ 2''
+тощо.
-==Contents==
+{{Info_(uk)|Назви сторінок не повинні точно відповідати структурі документа. У наведеному вище прикладі ви можете просто скористатися назвою Програма/Підручник/''підрозділ 2'' замість Програма/Підручник/''розділ 1''/''підрозділ 2''. Те саме стосується нижчих рівнів ієрархії (звичайно ж, якщо у процесі назви не дублюються {{Smiley}}).}}
-* 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_(uk)|Намагайтеся використовувати короткі назви і уникати надто довгих шляхів у назві. Надто довгі назви є важкими для запам’ятовування та введення, вони виглядають незграбно на сторінках вікі. Завжди пам’ятайте: назви сторінок та структура не впливають на завершений вигляд підручника! Він визначається лише заголовками у тексті.}}
-==Building your Manual==
+Щоб у автоматично створеному підручнику у форматі Docbook був той самий зміст, що і на UserBase, а посилання у Docbook працювали, варто дотримуватися таких настанов:
-* Use the red links to create the page, and write up a section at a time.
+* У змісті підручника у форматі Docbook всі розділи і підрозділи буде показано незалежно від того, чи є у них власна сторінка. З іншого боку, підрозділи високого рівня вкладеності не буде показано, навіть якщо у цих підрозділів є власна сторінка.
-* Note on the Discussion page anything you will need to refer to later, such as links that can't yet be created.
+* На кожній сторінці розділу у верхній частині має бути заголовок, розділу (== ... ==), підрозділу (=== ... ===) або підпідрозділу (==== ... ====), інакше структура підручника у форматі Docbook відрізнятиметься від задуманої.
-{{Remember|1=It's important to be consistent, particularly in Manuals, so here are some general rules:<!--}}-->
+* Заголовок розділу або підрозділу має точно збігатися з назвою сторінки, інакше посилання у Docbook працюватимуть не так, як це має бути.
-* Take care with heading levels - we start at second level (Mediawiki uses top level for page-name), using <nowiki>==</nowiki>
+* Назви підрозділів має бути записано так: <code>==='''''Назва'''''===</code>, навіть якщо цей розділ є розділом найвищого рівня на сторінці. Якщо не дотримуватися цього правила, структуру Docbook буде спотворено. Так само, якщо у вашому підручнику є дуже довгі підрозділи, які поділено на окремі сторінки, кожна з таких сторінок повинна мати власний заголовок у такому форматі: <code>===='''''Назва'''''====</code>.
-* 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]]
+* Підрозділи, які не має бути показано на сторінці змісту, і які не мають власної сторінки, у Docbook мають рівень 4 або нижче, тобто заголовок рівня ==== або нижче.
-* 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].
+* Посилання на сторінках підручника мають точно збігатися з назвами сторінок (тобто не повинно бути переспрямувань)
-* Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's''').
+* Якщо ви робите посилання на підрозділ сторінки, вам слід додати позначку на відповідному місці сторінки. Якщо ви цього не зробите, посилання у перекладах не працюватимуть.
-* Ensure that '''all''' images are in PNG format (you can use JPEG (.jpeg, not .jpg) as well, but in this case you should convert your images to PNG later.  Save work by converting them before you start [[Image:Smiley.png|16px]].
+{{Note_(uk)|1=У підручнику у форматі DocBook кожен підрозділ (===) матиме окрему сторінку, навіть якщо цей підрозділ є частиною довшої сторінки UserBase. Це означає, що розділ (==), який складається з декількох підрозділів, але не містить тексту перед першим підрозділом, матиме сторінку Docbook, на якій не буде нічого, окрім посилань на підрозділи.}}
-<!--{{-->* Remove all non-printable characters from image names.}}
+{{Remember_(uk)|1=Якщо вам захочеться змінити заголовок основного підрозділу сторінки (перший заголовок), важливо також змінити відповідним чином назву сторінки та всі посилання так, щоб вони збігалися з новою назвою.}}
-==Preparing the Manual for Translation==
+{{Remember_(uk)|1=<span  style="color:red;">Будь ласка, не використовуйте знаки пунктуації у назвах сторінок</span> — знаки пунктуації, зокрема знаки запитання або крапки, є доволі серйозною проблемою для програмного забезпечення вікі, зокрема системи перекладу.}}
-* 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.
+Вам знадобиться якась чернетка для експериментів з заголовками розділів та сторінками підручника. Ви можете скористатися або власною сторінкою обговорення, або сторінками з ділянки, над якою ви працюєте. Після завершення роботи варто вилучити всі зайві сторінки.
-[[Category:Contributing]]
+== Початковий етап написання підручника ==
+На початковому етапі створення вашого підручника краще тримати його окремо від решти даних UserBase. Можна редагувати чернетки основної та підлеглих сторінок на сторінці обговорення вашої сторінки користувача. З цією метою нами також передбачено особливий прострі назв <tt>Draft:</tt>.
+Щоб створити сторінку змісту вашого підручника, просто вкажіть у полі адреси вашої програми для перегляду інтернету <tt><nowiki>http://userbase.kde.org/Draft:</nowiki>'''''Назва_програми/Назва_підручника'''''</tt> або вставте посилання <nowiki>[[Draft:Appname/Manual]]</nowiki> на сторінку, збережіть його, а потім натисніть його. За обох варіантів дій буде відкрито сторінку з повідомленням про те, що сторінки не існує, але ви можете створити її натисканням посилання.
+===Зміст===
+* Коли всі рішення буде прийнято (процес складання плану може бути доволі тривалим), створіть відповідні посилання на сторінці змісту. Звичайно ж, якщо ви щось пропустили, пізніше можна буде додати відповідне посилання.
+===Збирання підручника===
+* Скористайтеся посиланнями червоного кольору для створення сторінок, створюючи розділи підручника один за одним.
+* Занотовуйте на сторінці обговорення всі потрібні згодом посилання, зокрема посилання, дані для яких ще не створено.
+{{Remember_(uk)|1=Під час написання підручника варто дотримуватися певних правил, які зроблять вашу роботу однорідною:<!--}}-->
+* Слідкуйте за заголовками рівнів — починати слід завжди з другого рівня (у Mediawiki перший рівень використовується для назви сторінки), тобто слід використовувати <nowiki>==</nowiki>
+* Зазирайте час від часу на сторінки [[Special:myLanguage/Tasks_and_Tools|завдань та інструментів]] та [[Special:myLanguage/Typographical_Guidelines|правил форматування]].
+* Додавайте пробіл після символу вертикальної риски у таблицях. Це правило узгоджується з [http://en.wikipedia.org/wiki/Help:Table традиційним форматуванням вікі].
+* Використовуйте однорідну систему форматування для назв програм (використовуйте замість '''Amarok'''s формат '''Amarok's''').
+* Намагайтеся використовувати зображення '''лише''' у форматі PNG (можна використовувати JPEG, але під час створення Docbook скрипт все одно перетворить їх на зображення у форматі PNG). Ви можете зекономити час, якщо зробите все правильно від початку [[Image:Smiley.png|16px]].
+<!--{{-->* Не використовуйте символи Unicode (не ASCII) у назвах зображень.}}
+==== Правила форматування ====
+Якщо ви маєте наміт перетворити підручник до придатного до перекладу формату Docbook, слід взяти до уваги деякі обмеження щодо форматування.
+* [[Special:myLanguage/Toolbox#Notes and Warnings|Нотатки і попередження]] у Docbook не можуть мати альтернативних назв. Не пишіть чогось подібного до <br /><code><nowiki>{{Remember|2=Don't Forget This!|1=You can use...}}</nowiki></code><br />Частину <code>2=...</code> у Docbook буде пропущено. Скрипт перетворення сторінки вікі у Docbook може не спрацювати як слід. Просто напишіть<br /><code><nowiki>{{Remember|1=You can use...}}</nowiki></code>
+* [[Special:myLanguage/Toolbox#Embed a Video|Вбудовування відео]] у поточній реалізації має певні обмеження: можна вбудовувати лише відео з YouTube та Vimeo і можна передавати лише один аргумент (ідентифікатор відео).
+=== Пошук у вашому підручнику ===
+У вас може виникнути потреба у пошуку чогось, що ви писали раніше, але не пам’ятаєте, де саме. Використання поля пошуку вікі може буде неідеальним, якщо ви не шукаєте щось дуже специфічне. Набагато кращі результати пошуку можна отримати за допомогою розширення DPL. Наприклад, щоб знайти сторінки підручника, які містять певний рядок, ви можете додати на будь-яку сторінку такий код і натиснути кнопку попереднього перегляду:
+{{Input|1=<nowiki>
+<DPL>
+  titlematch = %Appname/Manual%
+  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
+  namespace = | Draft
+  include = *
+  includematch = /рядок, який слід знайти/
+  includemaxlength = 0
+  resultsheader = Manual Pages:
+  format = ,\n* [[%PAGE%|%TITLE%]]\n,,
+</DPL>
+</nowiki>}}
+{{Info_(uk)|1=Інші приклади використання DPL можна знайти на сторінці [[User:Claus_chr/DPL]]. Простішим способом пошуку рядків у підручнику є використання шаблону SearchPages: щоб виконати пошук рядка «timeline» у підручнику з Kdenlive, напишіть у коді сторінки <code><nowiki>{{SeatchPages|1=Kdenlive/Manual|2=[Tt]imeline}}</nowiki></code>.<br /><br />Підказка для досвідчених: щоб побачити результати пошуку, вам не потрібно зберігати сторінку — достатньо попереднього перегляду. Коли список результатів буде виведено, ви можете просто скасувати результати редагування.}}
+{{Note_(uk)|1=Якщо ви працюєте з підручником із Amarok, зважайте на те, що сторінки підручника названо не у повній відповідності із правилами. Можете скористатися
+{{Input|1= titlematch = %Amarok/QuickStartGuide%{{!}}%Amarok/Manual%.}}
+(Зауваження: у взірці немає символів пробілів навколо {{!}})
+}}
+==Приготування підручника до перекладу==
+* Кроки з редагування розмітки можна знайти на сторінці [[Special:myLanguage/Edit Markup|приготування сторінки до перекладу]]. Скористайтеся порадами з цієї сторінки, оскільки застарілі стилі розмітки можуть бути непридатними до використання.
+== Створення підручника у форматі DocBook ==
+Щойно роботу над створеним вами підручником буде завершено, ви можете перетворити його на підручник у форматі DocBook, щоб ним можна було користуватися як звичайним підручником до програми KDE. Докладний опис перетворення можна знайти на [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook|цій сторінці]].
+[[Category:Власний внесок/uk]]