diff --git a/contributors_manual/community.rst b/contributors_manual/community.rst index def5859c2..93ccd09e4 100644 --- a/contributors_manual/community.rst +++ b/contributors_manual/community.rst @@ -1,92 +1,93 @@ .. meta:: :description: Guide to the Krita community .. metadata-placeholder :authors: - Boudewijn Rempt :license: GNU free documentation license 1.3 or later. .. index:: community, communication .. _the_krita_community: + =================== The Krita Community =================== Get in touch! Apart from the website at https://www.krita.org, the Krita project has three main communication channels: * Internet Relay Chat (IRC) * The mailing list * Phabricator While Krita developers and users are present on social media such as Twitter, Mastodon, Reddit, Google+, Tumblr or Facebook, those are not the place where we discuss new features, bugs, development or where we make plans for the future. There are also the: * bug tracker * development sprints You’ll find that there are a number of people are almost always around: the core team. * Boudewijn (irc: boud): project maintainer, lead developer. Works full-time on Krita. Manages the Krita Foundation, triages bugs, does social media and admin stuff. * Dmitry (irc: dmitryk_log): lead developer. Works full-time on Krita. * Wolthera (irc: wolthera_laptop): developer, writes the manual and tutorials, triages bugs, helps people out * Scott Petrovic (irc: scottyp): UX designer, developer, webmaster * David Revoy (irc: deevad): expert user, creates Pepper & Carrot, maintains the preset bundle. * Alvin Wong (irc: windragon): windows guru * Ben Cooksley (irc: bcooksley): KDE system administrator. Krita’s team spans the globe, but most development happens in Europe and Russia. Krita is part of the larger KDE community. The KDE® Community is a free software community dedicated to creating an open and user-friendly computing experience, offering an advanced graphical desktop, a wide variety of applications for communication, work, education and entertainment and a platform to easily build new applications upon. The KDE contributors guide is relevant for Krita contributors, too, and can be found here: http://archive.flossmanuals.net/kde-guide/ . The Krita Foundation was created to support development of Krita. The Krita Foundation has sponsored Dmitry’s work on Krita since 2013. Internet Relay Chat ------------------- IRC is the main communication channel. There are IRC clients for every operating system out there, as well as a web client on the krita website. * Joining IRC: connect to irc.freenode.net, select a unique nickname and join the #krita and ##krita-chat channels. #krita is for on-topic talk, ##krita-chat for off-topic chat. * Don’t ask to ask: if you’ve got a question, just ask it . * Don’t panic if several discussions happen at the same time. That’s normal in a busy channel. * Talk to an individual by typing their nick and a colon. -* Almost every Monday, at 14:00 CET or CEST, we have -a meeting where we discuss what happened in the past week, what we’re doing, and everything that’s relevant for the project. r The meeting notes are kept in google docs. +* Almost every Monday, at 14:00 CET or CEST, we have a meeting where we discuss what happened in the past week, what we’re doing, and everything that’s relevant for the project. The meeting notes are kept in google docs. * Activity is highest in CET or CEST daytime and evenings. US daytime and evenings are most quiet. * **IRC is not logged. If you close the channel, you will not be gone, and you will not be able to read what happened when you join the channel again. If you ask a question, you have to stay around!** * It is really irritating for other users and disrupting to conversations if you keep connecting and disconnecting. Mailing List ------------ The mailing list is used for announcements and sparingly for discussions. Everyone who wants to work on Krita one way or another should be subscribed to the mailing list. -* https://mail.kde.org/mailman/listinfo/kimageshop -The mailing list is called “kimageshop: because that is the name under which the Krita project was started. Legal issues (surprise!) led to two renames, once to Krayon, then to Krita. +`Mailing List Archives `_ + +The mailing list is called "kimageshop", because that is the name under which the Krita project was started. Legal issues (surprise!) led to two renames, once to Krayon, then to Krita. Phabricator ----------- Phabricator serves the following purposes for the Krita team: * Track what we are working on: https://phabricator.kde.org/maniphest/ This includes development tasks, designing new features and UX design, as well as tasks related to the website. * Review code submissions: https://phabricator.kde.org/differential/ * Host the git repository: https://phabricator.kde.org/source/krita/ . Note that while there is a mirror of our git repository on Github, we do not use Github for Krita’s development. **Do not** report bugs as tasks on Phabricator. Phabricator is where we organize our work. **Do** put all your code submissions (patches) on Phabricator. **Do not** attach patches to bugs in the bug tracker. Bugzilla: the Bug Tracker ------------------------- Krita shares the bug tracker with the rest of the KDE community. Krita bugs are found under the Krita product. There are two kinds of reports in the bug tracker: bugs and wishes. See the chapters on Bug Reporting and Bug Triaging on how to handle bugs. Wishes are feature requests. Do not report feature requests in bugzilla unless a developer has asked you to. See the chapter on Feature Requests for what is needed to create a good feature request. Sprints ------- Sometimes, core Krita developers and users come together, most often in Deventer, the Netherlands, to work together on our code design, UX design, the website or whatever needs real, face-to-face contact. Travel to sprints is usually funded by KDE e.V., while accommodation is funded by the Krita Foundation. diff --git a/contributors_manual/krita_manual_conventions.rst b/contributors_manual/krita_manual_conventions.rst index 3aeca5805..36bb2120d 100644 --- a/contributors_manual/krita_manual_conventions.rst +++ b/contributors_manual/krita_manual_conventions.rst @@ -1,548 +1,549 @@ .. meta:: :description: reStructuredText conventions for the Krita Manual .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier :license: GNU free documentation license 1.3 or later. + .. _krita_markup_conventions: ======================================== Mark-up conventions for the Krita Manual ======================================== This details the style conventions for using restructured text for the Krita Manual. It's recommended to look over the `official specification `_ for reStructuredText, and given it lives on sourceforge, to save a copy to your harddrive (sourceforge has, at this time of writing, some issues with server uptime): User Manual: * `Primer `_ * `Quick Ref `_ * `Text Cheatsheet `_ Reference Documentation: * `Introduction `_ * `Markup `_ * `Directives `_ * `Roles `_ Sphinx specific docs: * `Sphinx' page on restrucutred text `_ -- This is useful for the specific sphinx directives and roles it uses to generate for example table of contents. There's between the official reStructuredText and the sphinx docs multiple ways to do things. This document specifies the suggested conventions to go with. .. contents:: Meta data --------- Each page should start with the following three things: 1. A meta description This is a general description of the page. It will be converted to a html meta tag which will be used by search engines:: .. meta:: :description: Description. 2. A list of authors and a license. This is just to keep track of who edited the page and to give credit. It should be in a comment so that it will not end up being easily readable by machines. The license of the whole manual is GDL 1.3 and should also be mentioned here:: .. metadata-placeholder :authors: - Author 1 - Author 2 :license: GNU free documentation license 1.3 or later. 3. Indexing terms. These are comma-seperated terms under which the page will be indexed in :ref:`genindex`. The generated index is quite useful for both pdf as well as people who are not sure what the exact name is of the term they are looking for. They are defined as following:: .. index:: Keyword, Keyword with Spaces, ! Main Definition Keyword 4. A label. This is so we can easily link to the page using ``:ref:`label_name```. Try to make this a nice variable name:: .. _label_name: After the label you will need to add a heading, as ``:ref:`label_name``` will refer to the heading to fill out it's link-text. Headings -------- Headings will be done in the following order:: ############ Part/Section ############ For pages that have a lot of subpages. ========= Heading 1 ========= Start most manual pages with this. Heading 2 --------- Heading 3 ~~~~~~~~~ Heading 4 ^^^^^^^^^ Heading 5 ''''''''' Heading 6 """"""""" These conventions were more or less decided by pandoc's mediawiki to reStructuredText conversion. If you need more than 4 headings, ask yourself first if the page hasn't gotten too complicated and needs splitting up. Sometimes you need to link to a subsection of a page, add a label above the heading in that case. Headers should not end with punctuation, as the header will be used as the link name when linking to a label. Linking ------- Linking is done with ``:ref:`label_name```. When you need an alternative link text, you use ``:ref:`actual text shown ```. Linking to external pages is done with ```url`_`` and ```link name `_``, which'll become `link name `_. Pandoc likes to turn these into ```link name`__`` and then add `` .. __ :url `` at the end of the document. This is a so-called 'anonymous hyperlink', meaning that depending on the order of the links appearing in the text the order of the links at the end of the text are associated to one another. If this sounds confusing and difficult, it is because it is. That is also the exact reason why we'd like to avoid links like these. Footnotes and further reading ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Footnotes can be made in 3 ways, the most common one is with autonumbering, as per reference: [#]_ is a reference to footnote 1, and [#]_ is a reference to footnote 2. .. [#] This is footnote 1. .. [#] This is footnote 2. .. [#] This is footnote 3. [#]_ is a reference to footnote 3. -Here is a citation reference: [CIT2002]_. +Here is a citation reference: [CIT2002]_ . .. [CIT2002] This is the citation. It's just like a footnote, except the label is textual. Citaton can also be referenced with `citation `_ We don't actually use footnotes in the manual due to the fact that it is a little bit too academical for our readers. However, we do collect documents and links that give a little bit more information on a topic at the end of a page. Sphinx has the ``.. seealso::`` directive for linking to external links, while reStructuredText suggests to use ``.. rubic:: Footnotes`` for specifically collecting footnotes as that plays nice with LaTeX. Images ------ Use the image directive for images without captions:: .. image:: /images/en/sample.png :width: 800 :align: center :alt: an image. And figure directives for images with captions:: .. figure:: /images/en/sample.png :figwidth: 800 :align: center :alt: an image. A caption -- notice how the first letter is aligned with the :figwidth: option. The latter gives: .. figure:: /images/en/sample.png :figwidth: 800 :align: center :alt: an image. A caption -- notice how the first letter of the caption in the directive is aligned with the :figwidth: option. Images should go into the ``/images/en`` folder. By using ``/images`` instead of ``images``, sphinx will know the filepath isn't relative. In-text Markup -------------- You can make text *emphasized* and **strong** with a single asterisk and double respectively:: *emphasize* **strong** You cannot do both ***emphasized and strong***, so take a pick. You can :sub:`subscript text` and :sup:`superscript text` by using ``:sub:`text``` and ``:sup:`text``` However, use these super-sparingly! It is preffered to use the existing semantic markup in sphinx in any case, because that makes it easier for translators to make decisions about the nature of the text:: :menuselection:`settings --> configure Krita` :guilabel:`File` :kbd:`Ctrl + Z` :program:`Krita` Avoid randomly bolding words. It does *not* make the text easier or friendlier to read. Substitution References ----------------------- You can create a sort of shorthand for a piece of text or an image by doing:: .. |shorthand| replace:: something or the other. which means that if you use ``|shorthand|``, in the text, it'll be replaced with 'something or the other'. This is useful for, images and text that needs to be formatted in a complicated way, like in the case of "LaTeX". The krita documentation has ``|mouseleft|``, ``|mousemiddle|``, ``|mousescroll|`` and ``|mouseright|``, which'll turn into |mouseleft|, |mousemiddle|, |mousescroll| and |mouseright| respectively. These are defined in the sphinx conf.py, and are appended to each rst file. For links, if you reuse the same link over and over, you can write something like the following at the end of the file:: .. _bugzilla: https://bugs.kde.org/ .. _Krita Manual: https://docs.krita.org/ Then, when typing a link, you can just use ```bugzilla`_`` to link to bugzilla with "bugzilla" used as the text of the link. ```Krita Manual`_`` will in turn link to docs.krita.org with the text "Krita Manual". Lists ----- Ordinated lists ~~~~~~~~~~~~~~~ 1. Apple 2. Pear 3. Banana Or... A. Table B. Chair C. Wardrobe. I. Augustus #. Nero #. Caligula #. Trajan They can be defined as follows:: 1. Apple 2. Pear 3. Banana #. Apple #. Pear #. Banana A. Table B. Chair C. Wardrobe A. Table #. Chair #. Wardrobe I. Augustus #. Nero #. Caligula #. Trajan Unordered lists ~~~~~~~~~~~~~~~ - red - yellow - green - seagreen - verdigris - teal - veridian - emerald - dark emerald - light emerald - very light emerald. - blue Defined as such:: - red - yellow - green - seagreen - verdigris - teal - veridian - emerald - dark emerald - light emerald - very light emerald. - blue Definition Lists ~~~~~~~~~~~~~~~~ A favourite! Definition lists are especially useful when dealing with ennumerating all the options in a docker and trying to add a simple explaination behind them. Definition explaination. Another option Explaination. To make them. You can make them like this:: Definition explaination. Another option Explaination. Tables ------ ================== ============ Purpose Table type ================== ============ listing shortcuts Simple table lots of colspans Grid table Simple but long List Table ================== ============ Done as follows:: ================== ============ Purpose Table type ================== ============ listing shortcuts Simple table lots of colspans Grid table Simple but long List Table ================== ============ +-----------------+------------+ |Purpose |Table Type | +=================+============+ |listing shortcuts|Simple table| +-----------------+------------+ |lots of colspans |Grid table | +-----------------+------------+ |Simple but long |List table | +-----------------+------------+ .. list-table:: :header-rows: 1 - * Purpose * Table Type - * listing shortcuts * simple table - * lots of colspans * grid table - * simple but long * list table Full grid tables are best for when you need all features like complex column and row spans, but they're tricky to make. For that reason, small tables are best off being done with the simple syntax, while really long tables are best done with a list directive because that is just much easier to write and maintain. Admonishments and asides. ------------------------- .. note:: Admonishments are sort of like a seperate section that the reader needs to pay attention to. Admonishments that can be used are the following(in order of seriousness): .. hint:: Hints are useful to give a little bit more information on a topic than is useful in the main text. Like, hint: these packages are named differently in openSuse versus Debian. .. tip:: Extra information on how to do something, like, "you can make a template of your favourite document setup", or "use m to mirror the canvas and see errors more easily in your drawing". .. important:: Something that is important to note, but is not necessarily negative. .. warning:: This is in general when something is negative. .. attention:: General attention grabber. Use this when the subject is more important than warning, but not as important that is could get a dataloss. .. caution:: This is for things that could cause dataloss, like forgetting to save, or that python currently has no undo functionality. .. danger:: This should be for things that are dangerous for the computer in general, this includes things that can cause out of memory style freezes. .. error:: This one is probably not relevant for a manual. Sphinx can create these manually given some situations, but our configuration does not do so by default. .. admonition:: generic admonition that can have any text. This looks like the following:: .. admonition:: generic admonition that can have any text. Text Sphinx also adds:: .. seealso:: Which is useful to collect external links and references. .. Topic:: Horizontal Rulers Horizontal rulers are usually used when the topic switches rather directly. This is very common in more narrative based writing, such as history or fiction. The Krita manual is more instruction and reference style writing, that is to say, we don't usually tell a long story to indicate how different elements come together, but rather long stories are there to motivate why certain steps are taken in a certain manner. Topic changes then usually happen because we go into a new section, rather then switching to a related section. It is therefore better to use headings or the ``.. Topic::`` directive. Headings also make it easier to read. ---------------- That said, horizontal rulers can be made with ``----``. .. rubric:: The rubric directive. The rubric directive is a heading directive that at first glance looks like "topic", but where topic is over several paragraphs, rubric itself only deals with the header, like so:: .. rubric:: The rubric directive. .. rubric:: So, when to use these? Only use them when you think the subject is too minor to have a proper heading. Topic When the text is seperated from the flow, so it goes into a different subject than the text itself is naturally going to. Rubric When the text isn't seperated from the flow, but it does not need a header either. Admonishments Only when they fit semantically. This is especially necessary for the danger and warning admonishments, as seeing them too often can make users blind to them. Code Snippets: -------------- ``Inline code snippets`` are done with ````backticks````. Multi-line code snippets are done by ending the previous section with ``::``, which'll look like this:: This is a paragraph, and we define a preformated snippet like so:: Be sure to add a white space and a tab afterwards befor starting the snippet. You can also use the ``.. code::`` directive. If you add the language name after it, it'll do the appropriate syntax highlighting:: .. code:: python def my_function(): # comment alist = [] alist.append(1) string = "hello world" Becomes .. code:: python def my_function(): # comment alist = [] alist.append(1) string = "hello world" some more... .. code:: c++ int myFunction(int i) { i += 1; // Check if more than 12 if (i>12) { i = 0; } return i; } .. code:: css body { margin: 0 auto; /* is 800 still sensible? */ max-width:800px; font-size:16px; color:#333; background-color: #eee; padding:1em; font-family:serif; line-height: 1.4; } .. code:: html

this is a paragraph.

Other preformatted text. ------------------------ | One can | preformat | text by | prepending | each line | with a pipe | symbol Like so:: | One can | preformat | text by | prepending | each line | with a pipe | symbol We don't actually use this anywhere in the manual. Glossaries, Terms and Index --------------------------- These are sphinx features. Index is used in the top section, right now only single index entries are used. Glossaries are used for some of the menu entry sections, but not all of them. Quotes ------ Quotes are done like this:: I am not sure why you'd need quotes in a user manual... -- Wolthera This becomes a blockquote. I am not sure why you'd need quotes in a user manual... -- Wolthera We do actually use quotes in some places. Try to add a link to the name to define where it came from. diff --git a/contributors_manual/krita_manual_readme.rst b/contributors_manual/krita_manual_readme.rst index 71b590707..0580dc472 100644 --- a/contributors_manual/krita_manual_readme.rst +++ b/contributors_manual/krita_manual_readme.rst @@ -1,292 +1,293 @@ .. meta:: :description: Contributor's Readme for the Krita Manual .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Micheal Abrahams :license: GNU free documentation license 1.3 or later. + +.. Website shorthands. Sphinx/reStructuredText prefers it if you use shorthands when repeating websites. + +.. _phabricator : https://phabricator.kde.org +.. _Manual Project Workboard : https://phabricator.kde.org/project/view/135/ +.. _repository : https://phabricator.kde.org/source/websites-docs-krita-org/ +.. _bugzilla : https://bugs.kde.org/ + .. _krita_manual_contributors_guide: =============================== Krita Manual Contribution Guide =============================== Welcome to our new documentation! We've moved from userbase.kde.org to docs.krita.org, then we moved from Mediawiki to Sphinx. This latter change is because Sphinx allows us to handle translations much better than mediawiki can. The manual will include: A reference manual for Krita This one is probably what everyone is expecting when they type in docs.krita.org. Dry, basic, 'what does this button do' type of information. General concept tutorials. We've found over the past two years that for certain types of users, a reference manual, even with some examples, just isn't enough. The manual should also provide fast and concise explanations for things, and provide a basic workflow for preparing an image for the web. We also have found that certain concepts, such as color management and layer handling are far more advanced in Krita than the average artist is used to. Krita is free and many of its users will not have formal training in digital artwork. So there is no pre-existing artist-focused knowledge on how to use color management or filter layers. In addition there are systems that are unique to Krita, for example the brush system, the transform masks, the alpha inheritance and the perspective assistants. Finally, there are users who aren't familiar with even standard painting workflows, and are not flexible enough to understand how to port a tutorial for Sai or Photoshop to Krita. A list of known tutorials and video tutorials Apparently, one of the great things about Krita's team is how we connect with artists and acknowledge that they're doing cool stuff. The same should count for tutorials, especially because there are ways of using Krita and ways of approaching painting that are unique and we should encourage people to share their knowledge. Contributor's Manual Krita is (free) open source software, which makes us effectively a community project, with dozens of volunteers pitching in to make it better. This, of course, requires we keep track of manuals and howto's for new volunteers to come in and help us. The various places we've done this have been rather spread out, and are often under maintained. The contributor's manual is an attempt to solidify all the information. It is therefore very technical in places. krita.org tutorials There have been a bunch of tutorials on the krita.org and the krita-foundation.tumblr.com, the former focusing on explaining how to use a new feature and the later stimulated by user request. FAQ This one is already online and a merger of the different FAQs that we had. It's currently being translated and we hope to keep this one the primary one to update. For first timers ---------------- Unlike Mediawiki, Sphinx works more like how we write code for Krita. First things first, you will want to talk to us! For this you can either go to the `IRC on krita.org (#krita on freenode.org) `_, or, more importantly, make an account at `identity.kde.org `_. The account you make at identity can be used to both access the forum as well as the `phabricator`_, where we organise Krita development. If you have no idea where to begin, make a Kde identity account and make a post on `the forum `_. Sphinx works by writing simple text files with reStructuredText mark up, and then it takes those text files and turns them into the manual. We keep track of changes in the manual by putting them into a version control system called :program:`Git`. .. _making_changes_sphinx: Making changes ~~~~~~~~~~~~~~ Because we use Git, there's only a few people who can put things into the version control system, so if you want to make changes you will need to put it up for review. If you are not familiar with Git ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Get the source text from the `repository`_. Save a copy of the text as it existed originally. 2. Modify it. 3. Tools to check whether your modifications work. You can use the `Online Sphinx Editor `_ to check if your changes don't break 4. Bundle up the items into a zip. Put all the files you changed into a zip file. This also includes the images if you're changing them. Try to keep the filenames the same, that's easier for us to copy over. 5. Upload the zip on phabricator. 1. First, go to phabricator.kde.org and log in with you identity account. 2. Go to the `Manual Project Workboard`_ and there create a new task. 3. Explain what you did and use drag and drop to move the zip file to the input textbox. That should upload it. We will also need the email address you associate with your kde identity account. 4. Then, if the changes are accepted, someone with commit access will unpack those files into the manual folder and push the differences using the mail address. If you are familiar with Git ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Get the source from the `repository`_ using :program:`Git` clone 2. Make changes 3. Build locally (optional) 4. Generate a git diff. Go to the source directory in your terminal and write ``git diff > ../mydiff.diff`` this will make a diff file in the folder above. 5. Create a review request on phabricator 1. Login into `phabricator`_ with your identity account. 2. Go to differential. 3. Upper-right --> "Star" menu --> Create Review Request. 4. Upload the diff you made, select the correct repository(``websites-docs-krita-org``, easier to find with ``Krita.org Documentation Website``, *make sure you do not select docs-kde-org!*). 5. Confirm the file is correct. 6. Then in the next screen: 1. Add in Title/Short Summary. 2. Tell us what you changed in the summary. 3. (Optional) put your email in the comment if you want attribution. 4. Phabricator has a system that automatically tags the review request with the Krita Manual team. General philosophy ------------------ This is for determining what is an appropriate writing style. A writing style, whether we consider its practical or aesthetic qualities, is usually underpinned by a goal or general philosophy. What do we want to achieve with the manual, and for whom is the manual meant? Demographics and target audience(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We cannot talk about a demographic in the sense that we know all Krita users are 55 year old men. Krita is used by a hugely different amount of people, and we are actually kind of proud that we have such a varied userbase. Despite that, we know a couple of things about our users: * They are artists. This is explicitly the type of users that we target. * Therefore, we know they prefer pretty pictures. * They are visual. * They are trying to achieve pretty pictures. Therefore, the implicit goal of each page would be to get the feature used for pretty pictures. Other than that, we've observed the following groups: * High-school and college students trying out drawing software for illustrations. These usually have some previous experience with drawing software, like Painttool Sai or Photoshop, but need to be introduced to possibilities in :program:`Krita`. This group's strength is that they share a lot of information with each other like tips and tricks and tutorials. * Professionals, people who earn their money with digital drawing software. The strength of this group is that they have a lot of know-how and are willing to donate to improve the program. These come in two types: * Non technical professionals. These are people who do not really grasp the more mathematical bits of a piece of software, but have developed solid workflows over the years and work with software using their finely honed instincts. These tend to be illustrators, painters and people working with print. * Technical professionals. These are people who use :program:`Krita` as part of a pipeline, and care about the precise maths and pixel pushing. These tend to be people working in the games and VFX industry, but occasionally there's a scientist in there as well. * 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. From these four groups... * there's only one that is technical. Which is why we need the concept pages, so that we can create a solid base to write our manual texts on top of. * three of them likely have previous experience with software and may need migration guides and be told how. * two of them need to know how to get Krita to cooperate with other software. * two of them have no clue what they are doing and may need to be guided through the most basic of steps. From that we can get the following rules: General Writing ~~~~~~~~~~~~~~~ Use American English if possible. We use American English in the manual, in accordance to Krita's UI being American English by default. Keep the language polite, but do not use academic language. 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. Keep it translation compatible This consists of using svg for infographics, and using the appropriate markup for given text. Regarding photos and paintings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * I would like to discourage photos and traditional paintings in the manual if they are not illustrating a concept. The reason is that it is very silly and a little dishonest to show Rembrand's work inside the Krita GUI, when we have so many modern works that were made in Krita. All of the pepper&carrot artwork was made in Krita and the original files are available, so when you do not have an image handy, start there. Photos should be avoided because Krita is a painting program. Too many photos can give the impression Krita is trying to be a solution for photo retouching, which really isn't the focus. * Of course, we still want to show certain concepts in play in photos and master paintings, such as glossing or indirect light. In this case, add a caption that mentions the name of the painting or the painter, or mention it's a photograph. * Photos can still be used for photobashing and the like, but only if it's obviously used in the context of photobashing. Regarding images in general ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Avoid text in the images and use the caption instead. You can do this with the figure directive. * If you do need to use text, make either an SVG, so the text inside can be manipulated easier, or try to minimize the amount of text. * Try to make your images high quality/cute. Let's give people the idea that they are using a program for drawing! * Remember that the manual is licensed under GDPL 1.3, so images submitted will be licensed under that. In the case of CC-By-Sa/CC-By ensure that the file gets attributed appropriately through a figure caption. Needless to say, don't submit images that cannot be licensed under either license. Protocol -------- So here we line out all the boring workflows. Tagging and Branches ~~~~~~~~~~~~~~~~~~~~ Adding and removing text will be done in the ``draft`` branch. Proofreading results for old pages will be considered as bugfixes and thus will go into the ``master`` branch and merged into the ``draft`` branch as necessary. Before the ``draft`` branch is merged for a given release: * the master branch will be tagged with the old version. * The draft branch is first double checked that it has updated version number and updated epub cover. The ``draft`` branch will not be merged until the day before a release to keep the pages in tact for long enough. 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? Removing Pages ~~~~~~~~~~~~~~ If a feature is removed in a certain version, the corresponding pages. 1. Will first be marked deprecated. This can be done as so:: .. deprecated:: version number Text to indicate what the user should do without this feature. 2. Will be linked on a page called 'deprecated' 3. If the next version rolls around all the pages linked in the deprecated section will be removed. Adding Pages ~~~~~~~~~~~~ 1. Ensure that it is located in the right place. 2. Follow the :ref:`krita_markup_conventions` to ensure the page is formatted correctly. 3. Add the page to the TOC. 4. If the feature is new, add in versionadded:: .. versionadded:: version number optional something or the other. As with images, don't add text that you do not have permission to add. This means that text is either written by you, or you have permission to port it from the original author. The manual is GDPL 1.3+ so the text will be relicensed under that. Changing Pages ~~~~~~~~~~~~~~ If you fully rewrite a page, as opossed to proofreading it, the resulting page should be reviewed. If you change a page because a feature has changed, and you have commit access, the change can be pushed without review(unless you feel more comfortable with a review), but you should add:: .. versionchanged:: version number This and that changed. In all cases, check if you want to add yourself to the author field in the metadata section on top. Using deprecated, versionadded and versionchanged with the version number allows us to easily search the manual for these terms with grep: .. code:: bash grep -d recurse versionadded * --exclude-dir={_build,locale} Faulty pages ~~~~~~~~~~~~ If a page slips through the cracks, either... * Make a review request per the :ref:`making_changes_sphinx` section. * Make a task at the `Manual Project Workboard`_. * Make a bug at `bugzilla`_ under the project Krita in the section 'documentation'. Proofreading ~~~~~~~~~~~~ There's two types of proofreading that needs to be done. The most important one is **reviewing changes people make**. You can do this on phabricator in two ways: 1. Reviewing patches in differential. Reviewing patches is done in differential. Patch reviewing is usually done by programmers to find mistakes in each other's code, but because programming code is text based just like regular text, we can use patch reviewing to check against typos as well! A patch, or diff, is an amount of changes done in a document(added, removed) put into a machine readable file. When someone submits a review request(on system like gitlab or github this is a merge or pull request), people who maintain the original files will have to look them over and can make comments about things needing to change. This allows them to comment on things like typos, over-complicated writing but also things that are incorrect. After a patch has been accepted it can be pushed into the version control system. 2. Auditing changes in the manual. Auditing changes happens after the fact. You can audit a change by going to the commit message (from the repository page, go to history and then click on an entry), where you will be able to make comments on the changes made. In both cases, the interface consists of the difference being shown, with on the left the old version, and on the right the new version. Lines that have been added will be marked in green while lines that have been removed will be marked with red. You can click a line to add an 'inline' comment. Usually, when reviewing you go over the whole set of changes making comments where needed. To submit the inline comments, go to the bottom here you can add a general comment. When you submit the general comment all the inline comments will be submitted along side of it. 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. For this you will need to follow the :ref:`making_changes_sphinx` section, so that you can have full access to the pages and edit them. Translating ~~~~~~~~~~~ We are still trying to hash out a translation workflow. Please bear with us. .. Things that need to be decided: where do the POT files go, how do we decide which pages should not be translated, etc. Other ----- -For restructured text conventions, check :ref:`krita_markup_conventions`. - -.. Website shorthands. Sphinx/reStructuredText prefers it if you use shorthands when repeating websites. - -.. _phabricator : https://phabricator.kde.org -.. _Manual Project Workboard : https://phabricator.kde.org/project/view/135/ -.. _repository : https://phabricator.kde.org/source/websites-docs-krita-org/ -.. _bugzilla : https://bugs.kde.org/ +For restructured text conventions, check :ref:`krita_markup_conventions` . diff --git a/contributors_manual/untranslatable_pages/triaging_bugs.rst b/contributors_manual/untranslatable_pages/triaging_bugs.rst index 5e5efb3a3..0f8b71fd2 100644 --- a/contributors_manual/untranslatable_pages/triaging_bugs.rst +++ b/contributors_manual/untranslatable_pages/triaging_bugs.rst @@ -1,194 +1,203 @@ +.. meta:: + :description: + Guide to bugtriaging. +.. metadata-placeholder + + :authors: - Boudewijn Rempt + :license: GNU free documentation license 1.3 or later. + +.. _triaging_bugs: ============= Triaging Bugs ============= There are over 1000 bugs and 350 wishes reported against Krita per year, and that number is rising. The Krita developers cannot handle that stream on their own! Please consider helping out by triaging bugs. This document gives some simple guidelines to get started, and some common cases that can often be answered with a standard text. For more details, see also https://community.kde.org/Guidelines_and_HOWTOs/Bug_triaging .. contents:: Status flow ----------- A bug begins as ``UNCONFIRMED``. When triaging, only ``UNCONFIRMED`` bugs are still relevant. Platform ~~~~~~~~ If the user has not entered the Platform correctly (i.e., it is "unspecified/Linux"), then ask which platform they are using. Mark the bug as ``NEEDDINFO/WAITINFORINFO``. .. admonition:: Tell the user: Please indicate your operating system correctly. For Linux, select the distribution, appimage or compiled from sources and Linux, for Windows, select MS Windows/MS Windows, for OS X or macOS, select macports, disk images or homebrew and OS X. If the user has selected Windows CE for platform, set it to MS Windows without asking them. Version ~~~~~~~ If the user has not entered the version (i.e., the version is unspecified), ask them for the version and mark the bug as ``NEEDDINFO/WAITINFORINFO``. .. admonition:: Tell the user: Please select the version of Krita you are using. You can find the version in Help/About Krita. Can Reproduce ~~~~~~~~~~~~~ * If you can reproduce the bug, add a comment indicating you can reproduce it, maybe with clearer steps to reproduce and anything pertinent that you observed. If you have a backtrace, also add it. Set the bug status to ``CONFIRMED`` and add the ``triaged`` keyword to the keywords. * If you can reproduce the bug, and want to go the extra mile, use an older version of Krita to see whether you could reproduce it there as well. If you couldn't, it's a *regression*, so add the regression keyword to the keywords and mark which version of Krita the latest was that did not have the bug. Cannot Reproduce ~~~~~~~~~~~~~~~~ * If you cannot reproduce, the user either has not given enough information or the bug is specific to their system. * If there is not enough information, ask for more information. Depending on the report, the steps to reproduce might need to be described more clearly and/or a screenshot, a screen recording or the original files might be necessary. Set text (ask for what you think is needed): .. admonition:: Ask the user: I am sorry, I cannot reproduce your issue. Could you specify the steps to reproduce more clearly, and maybe add a screen recording/screenshot/original file * Mark the bug as ``NEEDINFO/WAITINGFORINFO``. * If the issue seems to be specific to the user's system, ask for the output of help/System information for bug reports as well. Set text: .. admonition:: Tell the user: I am sorry, but I cannot reproduce the bug on my system. Please add the output of help/System Information for Bug reports as well. * Mark the bug as ``NEEDINFO/WAITINGFORINFO``. Importance ~~~~~~~~~~ Importance is a tool for developers, not for bug reports. It's developers and triagers who decide what the importance is. If a bug reporter complains about a change in importance, use this text: .. admonition:: Tell the user: I am sorry, but the importance field is a tool for the developers to work with. Please do not change the importance back. There are the following Importances: Critical: the bug leads to immediate dataloss. Example: a saved file cannot be opened in Krita Grave: shouldn't be used, it doesn't mean a thing Major: it's a bug, but it's kinda important. Crash: the bug is about a crash or an assert [1]_ Normal: it's a bug Minor: it's a bug, but it's kinda unimportant Wish: it's a feature request Task: not used. The main difference is between Wish and the rest: Wishes are feature requests, and don't need immediate triaging. A wish bug is a bug that asks whether some functionality can be added to Krita, or complains that some functionality is missing. The rest are bugs, that is, problems in Krita that can be fixed by changing Krita's code. However, we also get many reports that are not bugs and not wishes: reports that are basically users asking for help because they do not understand Krita or their computer, or what a file is, or that Krita isn't the same application as Photoshop. Those reports need to be weeded out, and the status set to ``INVALID``. Guidance for using Importance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * If you encounter a bug that reports dataloss when loading a saved file, set it to critical. * If you encounter a bug that reports a crash or an assert but is not set to crash, set it to crash. * If you encounter a report that asks for functionality that is not currently present, set it to wish. * If you encounter a report that is a user request, check whether you can reply with a link to the faq (https://docs.krita.org/en/KritaFAQ.html), and maybe a canned answer, and change the status of the bug to ``INVALID``. Asserts and Crashes ~~~~~~~~~~~~~~~~~~~ .. [1] **Crash or assert.** These are different things. A crash happens when Krita spontaneously stops working *or* hangs. An assert happens when Krita stops working because we, developers, have added some code to detect an invalid state. Asserts are printed to the terminal or shown in a popup window. You can identify an assert by asking for terminal output, debugview output or by checking the backtrace, if there is one. If the backtrace contains a line like:: > SAFE ASSERT (krita): "!sanityCheckPointer.isValid()" in file /tmp/nix-build-krita-4.0.0-pre2c.drv-0/krita-1b1695a/libs/ui/KisDocument.cpp, line 490 Or another mention of assert, Q_ASSERT or similar, it's an assert, not a crash. Canned Answers and Recognizing Common Reports --------------------------------------------- We get a lot of duplicate bug reports. Sometimes it's clear that it's a duplicate, and you can mark it a such. In all cases, we want to give the reporter useful information so they can solve their problems. Of course, (almost) all solutions are also in the FAQ, but just pointing people to the FAQ is often considered impolite. So, do never reply to a bug report with: "Just read the FAQ." It takes a bit of experience to recognize a bug from an often incomplete description. Here are a couple of common cases: Cannot Save ~~~~~~~~~~~ For instance: "I cannot save/my file doesn't get saved/it says it cannot copy the file" This happens most often on Windows, if the user has got any security software installed that doesn't come with Windows. Examples are Sandboxie, Totaldefender, or others. Mark the bug as ``NEEDSINFO/WAITINGFORINFO`` and add this text: .. admonition:: Ask the user: Are you using Windows? If so, do you have any non-standard security software installed such as Total Defender, Sandboxie or XXX? Please make an exception for Krita in the settings, or uninstall this software. Since Windows 10, it is no longer necessary to have any security software installed other than what comes with Windows. If the user replies that they are using extra security software, close the bug as ``RESOLVED/INVALID``. Broken Canvas ~~~~~~~~~~~~~ This happens on Windows. Symptoms will be: the canvas is black, the canvas stays blank, the canvas only updates when the user clicks outside the canvas. Mark the bug as a duplicate of https://bugs.kde.org/show_bug.cgi?id=360601, and add the following text: .. admonition:: Tell the user: You probably are using a Windows system with an Intel display chip. Please update to Krita 3.3.3, which enables the Direct3D (Angle) renderer by default. If you do not want to update, check https://docs.krita.org/en/KritaFAQ.html#krita-starts-with-an-empty-canvas-and-nothing-changes-when-you-try-to-draw-or-krita-shows-a-black-or-blank-screen-or-krita-crashes-when-creating-a-document-or-krita-s-menubar-is-hidden-on-a-windows-system-with-an-intel-gpu My stylus has an offset ~~~~~~~~~~~~~~~~~~~~~~~ This happens on Windows. Symptoms will be: the user reports that the stylus cursor has an offset or moves the cursor on another screen. Usually, the user will have a misconfigured multi-monitor system. Mark the bug as ``NEEDSINFO/WAITINGFORINFO`` and ask the user: .. admonition:: Ask the user: Do you have a multi-monitor setup? If so, this is a configuration issue. Please reset your tablet driver's configuration and Krita's configuration (https://docs.krita.org/en/KritaFAQ.html#resetting-krita-configuration). If you have a single-monitor setup, then please calibrate your tablet. If the user checks back and tells us the problems are solved, mark the bug as ``RESOLVED/UPSTREAM``. Other tablet issues ~~~~~~~~~~~~~~~~~~~ Often, the user will tell you that their tablet will work perfectly with another application. This is not relevant. .. admonition:: Tell the user: Windows tablet drivers often have special code for different applications. Whether an application works or not depends on whether the programmers have tested their driver with an application or not. Tablet issues are almost always caused by the drivers being broken. Krita lags ~~~~~~~~~~ The word "lag" is meaningless. Complaints about "lag" are not bug reports. However, we should help the complainer. Mark the bug as ``NEEDSINFO/WAITINGFORINFO`` and ask the user: .. admonition:: Ask the user: Have you enabled the stabilizer? Check the tool options panel for the freehand tool. Also check the other possibilities mentioned here: https://docs.krita.org/en/KritaFAQ.html#krita-is-slow I cannot paint at all, in a particular document ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The user probably created, accidentally, a tiny selection, and saved that with the document. Mark as ``NEEDSINFO/WAITINGFORINFO`` and ask them: .. admonition:: Ask the user: Do you have a selection saved with that document. Use select/deselect on your image and check whether you can paint again. If not, please attach the .kra document to this bug report or make it available. diff --git a/reference_manual/main_menu/tools_menu.rst b/reference_manual/main_menu/tools_menu.rst index 837bd4c9e..6593e92a4 100644 --- a/reference_manual/main_menu/tools_menu.rst +++ b/reference_manual/main_menu/tools_menu.rst @@ -1,37 +1,38 @@ .. meta:: :description: The tools menu in Krita. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Scott Petrovic :license: GNU free documentation license 1.3 or later. .. index:: Macro, Scripts + .. _tools_menu: ========== Tools Menu ========== This contains three things. Scripting --------- When you have python scripting enabled and have scripts toggled, this is where most scripts are stored by default. Recording --------- .. caution:: The recording and macro features are unmaintained and buggy. -Record a macro. You do this by pressing start, drawing something and then pressing stop. This feature can only record brush strokes. The resulting file is stored as a *.kritarec file. +Record a macro. You do this by pressing start, drawing something and then pressing stop. This feature can only record brush strokes. The resulting file is stored as a \*.kritarec file. Macros ------ Play back or edit a krita rec file. The edit can only change the brush preset on strokes or add and remove filters. diff --git a/reference_manual/preferences/general_settings.rst b/reference_manual/preferences/general_settings.rst index 4cc933049..68ee5ba2c 100644 --- a/reference_manual/preferences/general_settings.rst +++ b/reference_manual/preferences/general_settings.rst @@ -1,182 +1,182 @@ .. meta:: :description: General Preferences in Krita. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Scott Petrovic - Greig :license: GNU free documentation license 1.3 or later. .. index:: Preferences, Settings, Cursor, Autosave, Tabbed Documents, Subwindow Documents, Pop up palette, File Dialog, Maximum Brush Size, Kinetic Scrolling .. _general_settings: ================ General Settings ================ You can access the General Category of the preferences by first going to :menuselection:`Settings --> Configure Krita`. .. image:: /images/en/Krita_Preferences_General.png Cursor Settings --------------- Customise the drawing cursor here: Cursor Shape ~~~~~~~~~~~~ Select a cursor shape to use while the brush tools are used. This cursor will always be visible on the canvas. It is usually set to a type exactly where your pen nib is at. The available cursor types are shown below. Tool Icon Shows the currently selected tool icon,even for the freehand brush. .. image:: /images/en/Settings_cursor_tool_icon.png Arrow Shows a generic cursor. .. image:: /images/en/Settings_cursor_arrow.png Crosshair Shows a precision reticule. .. image:: /images/en/Settings_cursor_crosshair.png Small circle Shows a small white dot with a black outline. .. image:: /images/en/Settings_cursor_small_circle.png No Cursor Show no cursor, useful for tablet-monitors. .. image:: /images/en/Settings_cursor_no_cursor.png Triangle Right-Handed. Gives a small white triangle with a black border. .. image:: /images/en/Settings_cursor_triangle_righthanded.png Triangle Left-Handed. Same as above but mirrored. .. image:: /images/en/Settings_cursor_triangle_lefthanded.png Black Pixel Gives a single black pixel. .. image:: /images/en/Settings_cursor_black_pixel.png White Pixel Gives a single white pixel. .. image:: /images/en/Settings_cursor_white_pixel.png Outline Shape ~~~~~~~~~~~~~ Select an outline shape to use while the brush tools are used. This cursor shape will optionally show in the middle of a painting stroke as well. The available outline shape types are shown below.(pictures will come soon) No Outline No outline. Circle Outline Gives a circular outline approximating the brush size. Preview Outline Gives an outline based on the actual shape of the brush. Tilt Outline Gives a circular outline with a tilt-indicator. Show Outline When Painting This option when selected will show the brush outline while a stroke is being made. If unchecked the brush outline will not appear during stroke making, it will show up only after the brush stroke is finished. This option works only when Brush Outline is selected as the Cursor Shape. .. _window_settings: Window Settings Multiple Document Mode This can be either tabbed like :program:`GIMP` or :program:`Painttool Sai`, or subwindows, like :program:`Photoshop`. Background image Allows you to set a picture background for subwindow mode. Window Background Set the colour of the subwindow canvas area. Don't show contents when moving subwindows. This gives an outline when moving windows to work around ugly glitches with certain graphics-cards. Show on-canvas popup messages Whether or not you want to see the on-canvas pop-up messages that tell you whether you are in tabbed mode, rotating the canvas, or mirroring it. Enable Hi-DPI support Attempt to use the Hi-DPI support. It is an option because we are still experiencing bugs on windows. Allow only once instance of Krita An instance is a single entry in your system's task manager. Turning this option makes sure that Krita will check if there's an instance of Krita open already when you instruct it to open new documents, and then have your documents opened in that single instance. There's some obscure uses to allowing multiple instances, but if you can't think of any, just keep this option on. Tool options ------------ In docker (default) Gives you the tool options in a docker. In toolbar Gives you the tool options in the toolbar, next to the brush settings. You can open it with :kbd:`\\`. Switch ctrl/alt modifiers This switches the function of the ctrl and alt buttons when modifying selections. Useful for those used to Gimp instead of photoshop, or Lefties without a right-alt key on their keyboard. Enable Touchpainting This allows fingerpainting with capacitive screens. Some devices have both capacitive touch and a stylus, and then this can interfere. In that case, just toggle this. Kinetic Scrolling (Needs Restart) This enables kinetic scrolling for scrollable areas. .. figure:: /images/en/Krita_4_0_kinetic_scrolling.gif :align: center Kinetic scrolling on the brush chooser drop-down with activation mode set to `guilabel:`On Click Drag`, with this disabled all of these clicks would lead to a brush being selected regardless of drag motion. Activation How it is activated. Disabled Will never activated. On Touch Drag Will activate if it can recognise a touch event. May not always work. On Click Drag Will activate when it can recognise a click event, will always work. Sensitivity How quickly the feature activates, this effective determines the length of the drag. Show Scrollbar Whether to show scrollbars when doing this. Miscellaneous ------------- Autosave Every Here the user can specify how often Krita should autosave the file, you can tick the checkbox to turn it off. For Windows these files are saved in the %TEMP% directory. If you are on Linux it is stored in /home/'username'. Compress \*.kra files more. This increases the zip compression on the saved Krita files, which makes them lighter on disk, but this takes longer to load. Upon importing Images as Layers, convert to the image color space. This makes sure that layers are the same color space as the image, necessary for saving to PSD. Undo Stack Size This is the number of undo commands Krita remembers. You can set the value to 0 for unlimited undos. Favorite Presets This determines the amount of presets that can be used in the pop-up palette. Create Backup File When selected Krita will try to save a backup file in case of a crash. Hide splash screen on startup. This'll hide the splash screen automatically once Krita is fully loaded. Enable Native File Dialog This allows you to use the system file dialog. By default turned off because we cannot seem to get native file dialogues 100% bugfree. Maximum brush size This allows you to set the maximum brush size to a size of up to 10.000 pixels. Do be careful with using this, as a 10.000 size pixel can very quickly be a full gigabyte of data being manipulated, per dab. In other words, this might be slow. Recalculate animation cache in background. .. versionchanged:: 4.1 This is now in the :ref:`performance_settings` under :guilabel:`Animation Cache`. - +