Krita マニュアルの作成者用ガイド

新しいドキュメントへようこそ!

私たちはサイトを userbase.kde.org から docs.krita.org に移動し、システムを Mediawiki から Sphinx に移動しました。後者の変更は、Sphinx が mediawiki よりもはるかに優れた翻訳処理を可能にするためです。

マニュアルには次の内容が含まれます:

Krita のリファレンスマニュアル

これはおそらく docs.krita.org にアクセスする誰もが期待しているものです。「このボタンは何をするのか」という類の簡潔で基本的な情報を表示します。

チュートリアルの全体的なコンセプト

過去2年間から、特定のタイプのユーザに対しては、たとえいくつかの例があったとしても、リファレンスマニュアルでは不十分なことがわかりました。マニュアルには短く簡潔な説明と、ウェブ用のイメージを準備するための基本的な手順を記載する必要があります。

また、Krita では色管理やレイヤー処理などの特定の概念が、一般的なアーティストが使用するものよりもはるかに先進的であることも分かりました。Krita は誰でも使用可能ですから、Krita ユーザの多くはデジタルアートワークの正式なトレーニングを受けていません。そのため、アーティスト向けの色管理やフィルターレイヤの使用方法に関する基礎知識が既存のものは用意されていません。

さらに、ブラシシステム、変形マスク、アルファ値継承、パース補助など、Krita 独自のシステムもあります。最後に、標準的なペイントワークフローにも慣れておらず、Sai や Photoshop のチュートリアルを Krita に通用させるやり方を十分に理解していないユーザもいます。

チュートリアルおよびチュートリアル映像の一覧

見たところ、Krita 開発チームの素晴らしい点の一つはアーティストとの関わりにおいて、彼らの素晴らしい仕事を認めていることです。チュートリアルとして有用な、特に Krita の使い方や、優れた絵画へのアプローチなどの知識を、ユーザーが共有することを勧めています。

作成者用マニュアル

Krita は(フリーの)オープンソースソフトウェアであり、実質的なコミュニティプロジェクトとして、その改善のために数十人のボランティアが参加しています。当然ながら、マニュアルや開発方法は新しいボランティアの人が参加するために更新し続ける必要があります。この作業を私たちが行ってきた場所はかなり分散しており、多くの場合、維持管理されていません。この参加者用のマニュアルは、すべての情報を結束させる試みです。よって、項目によっては非常に技術的な内容になっています。

krita.org チュートリアル

krita.org と krita-foundation.tumblr.com にはたくさんのチュートリアルがあり、前者は新機能の使い方を説明することに焦点を当てており、後者はユーザのリクエストに応えたものです。

FAQ

これは公開されていた、私たちが持っていたさまざまな FAQ を統合したものです。既に翻訳中のため、これを基点に更新していきたいと思っています。

初めての方へ

Mediawiki とは異なり、Sphinx は Krita のソースコードを書くような形で動作します。

まず最初に私たちと話したいですよね! このためには krita.org の IRC (freenode.org の #krita) にアクセスするか、もっと良いのは identity.kde.org にアカウントを作成することです。作成したアカウントはフォーラムへのアクセスだけではなく、Krita 開発を管理する phabricator へのアクセスにも使えます。

何から始めたらよいかわからない場合は、KDE のアカウントを作り、フォーラム に書き込みを行ってください。

Sphinx は reStructuredText マークアップを含む単純なテキストファイルを作成することで動作し、そのテキストファイルを取り込んでマニュアルに変換します。私たちはマニュアルの変更を、Git と呼ばれるバージョン管理システムで管理しています。

変更を行う

私たちは Git というバージョン管理システムを使用していますが、Git 上でファイルを変更できる権限を持つ人は数人しかいません。何かを変更したい場合は、変更点を Git に反映する前に評価(レビュー)することが必要です。

Edit mode を使用してマージリクエストを作成する

注釈

This method is only suitable if you have no push access to KDE repositories. Otherwise it would commit your changes directly to the repository, which is against the current guidelines.

技術的な知識のないユーザにお勧めします。

一度に複数のファイルを変更する場合はお勧めしません(より多くのファイルを変更したい場合、または単にマージリクエストごとに1つだけファイルを編集したい場合は WebIDE を使用してマージリクエストを作成する または コマンドラインを使用してマージリクエストを作成する を参照してください)。

多くの変更を加える場合は、次の手順に従うことをお勧めします。

  1. KDE アカウントを取得します。

  2. KDE_gitlab にログインします。

  3. repository にアクセスして fork をクリックします。

  4. あなたのフォークリポジトリの場所にリダイレクトされるはずです。通常は invent.kde.org/YOUR_KDE_LOGIN_NAME/docs-krita-org です。

  5. Come back to the official repository. Make sure you're browsing Documentation > Krita.org Documentation, not your own fork. Otherwise this method won't work correctly.

  1. Gitlab にはファイルを編集する機能があります。Repository ‣ Files から行います。

  2. At the top of the page you should see a dropbox with master as a chosen item.

  3. 編集したいファイルを見つけて開き、Edit をクリックします。

  4. 変更を行います(注:このモードでは、一度に1つのファイルしか編集できません)。

  5. 小さなテキストボックス欄に変更内容を含む小粋なメッセージをコミットメッセージ項目に書き込みます。完了したら Commit changes をクリックします。これでマージリクエストが提出されますので、次で説明するように全項目を入力してください: 新しいマージリクエスト提出のガイドライン

    悪い面は、この方法を使用してマークアップでエラーが発生したかどうかを判断する方法が現在ないことです。Online Sphinx Editor で変更を確認してください(編集中のファイル全体をコピーして貼り付けてください)。

注意

EditWebIDE は別々の項目です! Edit を必ず選択してください。

../_images/screenshot_editmode.png

WebIDE を使用してマージリクエストを作成する

複数のファイルを一度に編集したい、Git について多少の知識があるユーザにお勧めします。

ブランチが何であるかが分からない場合はお勧めしません(Edit mode を使用してマージリクエストを作成する を代わりに参照してください)。

  1. 上記の指示に従って KDE_gitlab にログインし、フォークリポジトリを作成します。

  2. あなたのフォークリポジトリに移動します(コンテンツ URL とユーザ名が正しいか確認してください)。

  3. Make sure you're on the master branch.

  4. WebIDE をクリックします。これにより、左側にファイルのリストがあり、右側にファイル内容のための大きな空きスペースがあるページが表示されます。

  5. 編集したいファイルを開き、変更を行います。

  6. Commit... をクリックします。Unstaged の全ファイルをダブルクリックして Staged changes に移動します。

  7. Commit... を再度クリックすると、コミットメッセージ作成用のテキストボックスが現れます。変更内容と変更の理由をコミットメッセージとして入力します。

  8. 正しく設定されていることを確認してください。次のいずれかを選択する必要があります。 ・ Create a new branch (ブランチの名前は [ユーザ名]/[変更箇所の簡単な概要] としてください)。変更が完了したら、 Start a new merge request がチェックされていることを確認します。 ・それ以外の場合は、後で新しいマージリクエストを作成する必要があります。

  9. Stage & Commit をクリックします。

  10. すべての項目を入力してください: 新しいマージリクエスト提出のガイドライン を参照してください。

  11. 新しいマージリクエストを手動で作成するには、 Krita マニュアルの公式リポジトリにアクセスし( URL にあなたのユーザ名が含まれて"いない"ことを確認してください)、 Create a new merge request (左側にある緑色のボタン)をクリックします。あなたのフォークリポジトリを選択し、 WebIDE で作成したブランチを選択します。

注釈

If you don't have a push access to the official repository, gitlab won't allow you to save your changes if you were editing the official repository by mistake (and Create a merge request won't help with that: you still need to commit your changes to your branch, but if you don't have push access, you can't do it). It will just show the message: An error occurred whilst committing your changes. Please try again.

この場合は、変更したすべてのファイルの内容をコピーし、フォークリポジトリに移動して WebIDE に貼り付けます。

コマンドラインを使用してマージリクエストを作成する

Git の動作やコマンドラインの使い方を知っているユーザにお勧めします。

ブランチが何であるかが分からない場合はお勧めしません(Edit mode を使用してマージリクエストを作成する を代わりに参照してください)。

  1. 上記の指示に従って KDE_gitlab にログインし、フォークリポジトリを作成します。

  2. git clone で Git リポジトリをローカルリポジトリに複製します。リポジトリのページには git clone を実行できる URL があり、フォークした自分のローカルリポジトリから変更をプッシュすることもできます。この方法の利点は、コンピュータ上のすべてのツールを使用してこれらのファイルを編集したり、エラーをチェックするためのマニュアルをローカル上に作成したりできることです(この手順は最初の1回だけ実行します)。

    # for ssh access
    git clone git@invent.kde.org:<username>/docs-krita-org.git
    git remote add upstream git@invent.kde.org:documentation/docs-krita-org.git
    
    # for https access
    git clone https://invent.kde.org/<username>/docs-krita-org.git
    git remote add upstream https://invent.kde.org/documentation/docs-krita-org.git
    
  3. 新しい変更を行う前に、必ず公式リポジトリから pull することを忘れないでください。

    git pull upstream master
    
  4. Make sure you create a new branch for your changes, since september 2019, all changes should be branched from master.

    git checkout master
    
    # and then:
    git checkout -b "<username>/<description of the new feature>"
    
  5. 変更後、それらをコミットしてあなたのフォークブランチにプッシュします。このワークフローで Git をターミナルで使用する方法の詳細については、Forking on Gitlab を参照してください。

    # install the python3-sphinx package for your system. For example for Ubuntu:
    sudo apt install python3-sphinx
    # make sure everything is correct
    make html
    git status
    git diff
    # add all of the files
    git add .
    # commit your changes
    git commit
    # submit your changes to your fork
    git push
    
  6. Finally, go to the website of the original repository, and then to Merge Requests. Select your fork and the correct branch and create a new merge request. For instruction on how to fill the fields, see 新しいマージリクエスト提出のガイドライン.

新しいマージリクエスト提出のガイドライン

  1. コミットメッセージは、次に説明する標準に従ってください: How to Write a Git Commit Message

  2. TitleDescription はコミットメッセージのように、あなたが行った変更とその理由を説明すべきですので、上記リンクのガイドラインに従ってください。

  3. Target should point to master.

  4. マージリクエストの内容が、後で変更を必要とすることが確実な場合は、マージリクエストのメッセージタイトルを [WIP] で始めます。

  5. Allow commits from members who can merge to the target branch. (対象ブランチにマージできるメンバからのコミットを許可する)をチェックしたことを確認してください。これはマージリクエストが master ブランチに基づいて再作成されるため、マージリクエスト自体がシステム的に変更されますが、実際のファイル変更内容は変わりません。これを Rebase と言いますが、これは作成ユーザまたはレビュー担当者が行うことができます。後で面倒なことになりたくない場合は、このチェックボックスをオンにして、レビュー担当者が Rebase を行えるようにしてください。

  6. 多くの場合、Delete source branch when merge request is accepted をチェックしても大丈夫です。

  7. レビュー担当者から特に指示がなければ Squash commits when merge request is accepted をチェックしてください。コミットメッセージの最初の行はあなたのマージリクエストの Title から文章がコピーされ、残りはマージリクエストの Description からコピーされます。

  8. マージリクエストの作成が完了したら IRC にアクセスして、プッシュ権限を持つユーザに「Needs Review(レビューが必要)」というラベルをマージリクエストに追加するように依頼します。

  9. マージリクエストに誤りがある場合は、フィードバックを受けることがあります。以下のいずれかの方法で、あなたのブランチの誤りを修正してください。

    • If you want to use Edit mode, just go to Changes section of the merge request and click on the pencil icon (with a tooltip that says Edit) to use the Edit mode again.

    • WebIDE モードを使用したい場合は、あなたのフォークリポジトリに移動し、変更したブランチを選択して WebIDE を選択します。

    • パソコン上のファイルを編集してコマンドラインで Git 操作する場合は、正しいブランチにいることを確認して、変更をリポジトリにプッシュしてください。Gitlab は公式リポジトリへのマージリクエストを自動的に更新します。

    変更後はラベルをもう一度「Needs Review」(レビューが必要)に変更するように依頼してください。

詳細については、技術編である Forking on Gitlab を確認してください。

注釈

このガイドの執筆時点でマージリクエストにラベルを設定できるのは、公式リポジトリへの書き込み権を持つコントリビュータだけです。この意味がわからない場合は、基本的にラベルを設定できるユーザーではありません。そのため、マージリクエストを作成または変更するときには、 IRC( Krita コミュニティ を参照)にアクセスして、誰かにラベルを付けてもらう必要があります。

全体的な指針

これは適切な文体を決定するためのものです。文体は実用的なものであれ嗜好的なものであれ、通常は目標や一般的な哲学によって支えられています。マニュアルで何を達成したいのでしょうか、誰を対象としているのでしょうか。

人口構成と対象読者

「Krita のユーザは全員55歳の男性であることを知っています」というような形で、人口統計について話すことはできません。Krita は非常に多くの人に使われていますが、私たちはユーザ層が多様であることを誇りに思っています。

それにも関わらず、私たちはユーザについていくつかのことを知っています。

  • 彼らはアーティストです。これは対象とするユーザの明確な特徴です。

    • アーティストですから、きれいな画像を好みます。

    • They are visual.

    • 彼らはきれいな絵を表現したいと思っています。

したがって、各ページの暗黙の目標はきれいな画像に使用される機能を知ってもらうことです。

それ以外に、次のようなグループが見られました:

  • 学生がイラスト作成ソフトを試している。彼らは通常「Painttool SAI」や「Photoshop」のようなソフトの使用経験がありますから、Krita が持つ有用性を紹介する必要があるでしょう。このグループの強みは、使用のヒントやコツ、チュートリアルなど、多くの情報を互いに共有することです。

  • ペイントソフトを用いて収入を得ているプロ。このグループの強みは、プログラムを改善するために提供する方法や意思が様々にあることです。次の2パターンがあります:

    • 一般の専門家。これらの人々は、ソフトウェア工学を把握していませんが、長年にわたってしっかりとしたワークフローを作り上げ、磨き上げられたセンスをもって、ソフトウェアでの作業を行っています。これらはイラストレーター、画家、印刷職の関係者であることが多いです。

    • 技術者。手段の1つとして Krita を使用し、間違いのない計算とピクセルの配置に注意を払う人々です。ゲームや VFX の業界で働く人が多いですが、科学者もいます。

  • Adult and elderly hobbyists. This group doesn't know much about computers, and they always seem to get snagged on that one little step missing from a tutorial. Their strength as a group is that they adapt unconventional workflows from real life that the student wouldn't know about and the professional has no time for and create cool stuff with that, as well as that they have a tempering effect on the first group in the larger community.

これら4つのグループから...

  • 技術的なことが分かるのは1グループだけです。そのため、マニュアルテキストを作成する上で根幹をなすコンセプトページが必要です。

  • そのうち3人は、以前に他のソフトウェアの使用経験があって、そこからの移行方法を必要としています。

  • そのうち2人は、Krita と他のソフトウェアを連携させる方法を知る必要があります。

  • そのうちの2人は自分が何をしているのかまったく分かっておらず、最も基本的な手順を示す必要があるかもしれません。

そこで次のようなルールとなります:

全体的な記述

可能であれば、アメリカ英語( American English )を使用してください。

Krita の UI がデフォルトでアメリカ英語( American English )になっているので、マニュアルではアメリカ英語を使用しています。

言葉遣いは丁寧にしてください。ただし学術用語は使わないでください。

As a community, we want to be welcoming to the users, so we try to avoid language that is unwelcoming. Swearing is already not condoned by KDE, but going to the far other end, an academic style where neither writer nor reader is acknowledged might give the idea that the text is far more complex than necessary, and thus scare away users.

Avoid using GIFs (open for debate)

The reason is that people with epilepsy may be affected by fast moving images. Similarly, GIFs can sometimes carry too much of the burden of explanation. If you can't help but use GIFs, at the least notify the reader of this in the introduction of the page.

翻訳との互換性を保つ

This consists of using SVG for infographics, and using the appropriate markup for a given text.

写真とイラストについて

  • 私は写真やよく知られた絵画などをマニュアルに掲載するのは、その作品が Krita のコンセプトを説明していないのであれば、やめてほしいと思っています。 Krita で作成された現代的な作品がたくさんあるのに、 Rembrandt の作品を Krita の GUI の中に表示するのは、とてもくだらなくて少し不誠実な行いだからです。 Pepper&carrot のアートワークはすべて Krita で作られており、ファイルデータも用意されているので、説明に適した画像が手元にない場合はそのデータを使用してください。 Krita は基本、絵を描くソフトなので、写真も避けるべきです。写真ばかりだと、 Krita はフォトレタッチの手段を提供することに集中している印象を与えてしまいます。

  • もちろん、光沢のつけ方やライティング( lighting )など、写真やマスター・ペインティングの中にある種の概念を示したいと思っています。この場合は、絵や画家の名前、または写真であることを示す見出しを追加します。

  • Photobashing を使用してもよいですが、 Photobashing の話題に限ります。(訳注: Photobashing :写真をイラストのように編集した作品のこと

画像全般について

  • 画像内へのテキスト挿入は避け、代わりに見出しを使用します。これを行うには figure コマンドを使用します。

  • テキストを使用する必要がある場合は、テキストデータを簡単に差し替えできるように SVG で挿入するか、最小限のテキストを使用します

  • 高品質で魅力的な画像を作ってみましょう。みんなに Krita でお絵描きをする発想を与えましょう!

  • マニュアルは GDPL1.3 の下でライセンスされているので、提出された画像はそのライセンスが適用されることを覚えておいてください。「CC-By-Sa/CC-By」の場合は、ファイルにライセンス表示が適切に行われているか確認してください。もちろん、どちらのライセンスでも使用できない画像は提出しないでください。

規約

よって、ここで退屈なワークフローをすべて説明します。

タグ(tag)とブランチ(branch)

テキストの追加と削除は「draft」ブランチで行います。

古いページの見直しはバグ修正と見なされるため、「master」ブランチに取り込まれ、必要に応じて「draft」ブランチにマージされます。

「draft」ブランチをマージする前に、次の操作を行います:

  • master ブランチに古いバージョンのタグが付けられます。

  • draft ブランチは初めにバージョン番号が更新されたことと、epub cover が更新されたことをチェックします。

「draft」ブランチは、リリースの前日までマージされず、元のページを長く保ちます。

Each release will have a version of the epub uploaded as part of the release process. .. Where do we get the POT files from? Even the translated versions?

ページを削除

特定のバージョンで機能が削除された場合、対応するページについて:

  1. 最初に非推奨とマークされます。

    これは次のように実行できます:

    .. deprecated:: version number
    
        Text to indicate what the user should do without this feature.
    
  2. 'deprecated'というページにリンクされます

  3. 次のバージョンに移行すると、非推奨項目としてリンクされているすべてのページが削除されます。

ページ追加

  1. 正しい位置であることを確認します。

  2. Krita マニュアルのマークアップ規約 に従って、ページが正しく構成されていることを確認してください。

  3. 目次へページを追加します。

  4. 新機能は versionadded:: で追加します

    .. versionadded:: version number
    
        optional something or the other.
    

画像の場合と同様に、許可のないテキストは追加しないでください。つまり、テキストは自分が作成したものか、テキスト作成者の許可が必要です。マニュアルは GDPL1.3+ ライセンスなので、追加されたテキストは再ライセンスされます。

ページの変更

ページを校正するのではなく、完全に書き直した場合は、ウェブサイトのページ表示を確認する必要があります。

機能が変更されたときに、ページを変更してコミットする場合は、レビューなしで変更をプッシュできますが(レビューがないと不安な場合は除きます)、 add:: を使用するべきです。

.. versionchanged:: version number

    This and that changed.

いずれの場合も、上部の metadata の項目で著者として自分を追加するかどうかを確認します。

(非推奨の方法です)バージョン番号として versionadded と versionchanged を使用すると、マニュアル内で grep を使って次の用語を簡単に検索できます:

grep -d recurse versionadded * --exclude-dir={_build,locale}

不完全なページ

ページが抜け落ちた場合...

校正

必要な校正には2種類あります。

最も重要なのは、”人が行った変更をレビューすること”です。これを KDE_gitlab で行うには2つの方法があります:

  1. マージリクエストをレビュー

    マージリクエストを確認できます。リクエストのレビューは通常、プログラマーがお互いのソースコードの間違いを見つけるために行いますが、コードは普通のテキストファイルと同様にテキスト形式なので、タイプミスをチェックすることもできます。

    マージ(merge)は、文書内で行われた変更(追加、削除)をデバイスが読み取り可能なファイルにまとめます。誰かがレビューリクエスト(Gitlab や Github のようなシステム上では"Merge Request"や"Pull Request"と表記)を提出した場合、元のファイルの管理者はそれらを確認し、変更が必要な点についてコメントする必要があります。これにより、タイプミスや複雑になりすぎている書き方のようなものだけでなく、間違っている点についてもコメントできます。リクエストが受け入れられると、文書変更が反映されます。

  2. マニュアルへの変更に対してコメントする。

    コメントの変更は fact の後に行われます。変更にコメントするには、 commit message に移動します(リポジトリページから history に移動し、コメントしたい項目をクリック)。このページでは、行った変更にコメントすることができます。

どちらの場合も、画面には、左側に古いバージョン、右側に新しいバージョンの差異が表示されます。追加された行は緑色で表示され、削除された行は赤色で表示されます。吹き出しアイコンをクリックすると、インラインコメントを追加できます。

The second major way the manual needs to be proofread is over the whole file. Many of the pages have only been checked for correctness but not for style and grammar.

変更を行う に従って、ページのアクセス権を得て編集できるようにします。

翻訳する

マニュアルの翻訳は KDE localization community で行われています。翻訳作業に参加するには、翻訳者用サイトにアクセスし、translation teams のリストから翻訳したい言語を選択し、表示されたページの指示に従って他の翻訳者と連絡を取ります。

翻訳チームは、このマニュアルの PO ファイルにアクセスできます。 PO ファイルは、 POEdit や Lokalize などの翻訳用ツールで使用されるファイル形式です。翻訳チームは協力してこれらのファイルを翻訳し、翻訳用 SVN にアップロードすることができます。そこから特殊なスクリプトが SVN から翻訳を受け取り、マニュアルデータの配置場所に持ってきて、毎日反映させます。

翻訳チームが画像も翻訳で差し替えたい場合は、独自の画像を使用できます。デフォルトでは、画像フォルダ内のすべてのイメージが「en」になります。特定の画像を翻訳する場合は、画像フォルダの場所に移動し、言語コード(訳注:日本なら「ja」)を名前に含むフォルダを追加して、翻訳バージョンの画像を追加します。例として、Sphinxは次のように画像ファイルのオランダ語版を検索します /images/Pixels-brushstroke.png/images/nl/Pixels-brushstroke.png または、 /images/dockers/Krita-tutorial2-I.1-2.png/images/dockers/nl/Krita-tutorial2-I.1-2.png

完成した翻訳ファイルをウェブサイトに反映させるには、 ウェブサイトの更新手順にファイルが追加される必要があります。翻訳の状態に自信のある翻訳チームは、 kimageshop のメーリングリスト( kimageshop@kde.org )または foundation@krita.org を通じて主要な Krita 開発チームに連絡し、翻訳を完了する必要があります。

その他

For restructured text conventions, check Krita マニュアルのマークアップ規約.