diff --git a/contributors_manual/krita_manual_conventions.rst b/contributors_manual/krita_manual_conventions.rst index f9b1c2b49..1cce5742e 100644 --- a/contributors_manual/krita_manual_conventions.rst +++ b/contributors_manual/krita_manual_conventions.rst @@ -1,553 +1,553 @@ .. 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 restructured text `_ -- This is useful for the specific sphinx directives and roles it uses to generate for example table of contents. There are differences 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 an 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-separated 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 follows:: .. 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 its 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 with 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. +`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 with 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]_ . .. [CIT2002] This is the citation. It's just like a footnote, except the label is textual. Citation 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/sample.png :width: 800 :align: center :alt: an image. And figure directives for images with captions:: .. figure:: /images/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/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`` 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 preferred 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 - viridian - emerald - dark emerald - light emerald - very light emerald. - blue Defined as such:: - red - yellow - green - seagreen - verdigris - teal - - veridian + - viridian - emerald - dark emerald - light emerald - very light emerald. - blue Definition Lists ~~~~~~~~~~~~~~~~ A favourite! Definition lists are especially useful when dealing with enumerating all the options in a docker and trying to add a simple explanation behind them. Definition Explanation. Another option Explanation. To make them. You can make them like this:: Definition Explanation. Another option Explanation. 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 separate 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, "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 Text. You can make it like this:: .. 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 than 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 the 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 separated from the flow, so it goes into a different subject than the text itself is naturally going to. Rubric When the text isn't separated 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 before 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 # Python comment def my_function(): alist = [] alist.append(1) string = "hello world" Becomes .. code:: python # Python comment def my_function(): alist = [] alist.append(1) string = "hello world" some more... .. code:: c++ // C++ comment int myFunction(int i) { i += 1; // Check if more than 12 if (i>12) { i = 0; } return i; } .. code:: css /* CSS comment */ 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/user_support.rst b/contributors_manual/user_support.rst index 7834ee711..dda0d2865 100644 --- a/contributors_manual/user_support.rst +++ b/contributors_manual/user_support.rst @@ -1,165 +1,150 @@ .. meta:: :description: Introduction to user support. .. metadata-placeholder :authors: - Agata Cacko :license: GNU free documentation license 1.3 or later. .. _gitlab : https://invent.kde.org .. _repository : https://invent.kde.org/kde/krita .. _bugzilla : https://bugs.kde.org/ .. _Krita developer IRC : https://krita.org/irc/ .. _API guide : https://api.kde.org/extragear-api/graphics-apidocs/krita/html/index.html .. _intro_user_support: ============================ Introduction to User Support ============================ .. requirements (aka just know a bit of Krita, the more you know, the more you'd be able to help) (+ if you don't know the answer, come to IRC) .. general philosophy .. + tablet support .. + quick solutions .. + important information needed .. + animation (how to debug) .. + crashes .. + advices .. useful links to quickly answer people .. contents:: Tablet Support -------------- The majority of help requests are about pen pressure and tablet support in general. Quick solutions ~~~~~~~~~~~~~~~ #. On Windows: reinstall your driver (Windows Update often breaks tablet driver settings, reinstallation helps). -#. Change API in Configure Krita -> Tablet Settings (for some devices, especially N-trig ones, Windows Ink work better, for some it's Wintab). +#. Change API in :menuselection:`Settings --> Configure Krita --> Tablet Settings` (for some devices, especially N-trig ones, Windows Ink work better, for some it's Wintab). #. On Windows, Wacom tablets: if you get straight lines at the beginnings of the strokes, disable/minimize "double-click distance" in Wacom settings. Gathering information ~~~~~~~~~~~~~~~~~~~~~ #. Which OS do you use? #. Which tablet do you have? #. What is the version of the tablet driver? -#. Please collect Tablet Tester (Configure Krita -> Tablet Settings) output, paste it to pastebin or similar website and give us a link. +#. Please collect Tablet Tester (:menuselection:`Settings --> Configure Krita --> Tablet Settings`) output, paste it to `Pastebin `_ or similar website and give us a link. Additional information for supporters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Except for the issue with beginnings of the strokes, Wacom tablets usually work no matter the OS. #. Huion tablets should work on Windows and on Linux, on Mac there might be issues. #. XP-Pen tablets and other brands can have issues everywhere. #. If someone asks about a tablet to buy, generally a cheaper Wacom or a Huion are the best options as of 2019, if they want to work with Krita. :ref:`list_supported_tablets` -#. `Possibly useful instruction in case of XP Pen tablet issues ` +#. `Possibly useful instruction in case of XP-Pen tablet issues `_. Animation --------- -Issues with rendering animation can be of various shapes and colors. First thing to find out is whether the issue happens on Krita's or ffmpeg's side (Krita saves all the frames, then ffmpeg is used to render a video using this sequence of images). To learn that, instruct the user to render as "Image Sequence". If the image sequence is correct, ffmpeg (or more often: render options) are at fault. If the image sequence is incorrect, either the options are wrong (if for example not every frame got rendered), or it's a bug in Krita. +Issues with rendering animation can be of various shapes and colors. First thing to find out is whether the issue happens on Krita's or FFmpeg's side (Krita saves all the frames, then FFmpeg is used to render a video using this sequence of images). To learn that, instruct the user to render as "Image Sequence". If the image sequence is correct, FFmpeg (or more often: render options) are at fault. If the image sequence is incorrect, either the options are wrong (if for example not every frame got rendered), or it's a bug in Krita. .. note:: If the user opens the Log Viewer docker, turns on logging and then tries to render a video, Krita will print out the whole ffmpeg command to Log Viewer so it can be easily investigated. There is a log file in the directory that user tries to render to. It can contain information useful to investigation of the issue. Onion skin issues ----------------- The great majority of issues with onion skin are just user errors, not bugs. Nonetheless, you need to find out why it happens and direct the user how to use onion skin properly. Crash ----- In case of crash try to determine if the problem is known, if not, instruct user to create a bug report (or create it yourself) with following information: #. What happened, what was being done just before the crash. #. Is it possible to reproduce (repeat)? If yes, provide a step-by-step instruction to get the crash. -#. Backtrace (crashlog) -- the instruction is here: :ref:`dr_minw`, and the debug symbols can be found in the annoucement of the version of Krita that the user has. But it could be easier to just point the user to `https://download.kde.org/stable/krita `. +#. Backtrace (crashlog) -- the instruction is here: :ref:`dr_minw`, and the debug symbols can be found in the annoucement of the version of Krita that the user has. But it could be easier to just point the user to `https://download.kde.org/stable/krita `_. Other possible questions with quick solutions --------------------------------------------- -#. When the user has trouble with anything related to preview or display, ask them to change Canvas Graphics Acceleration in Configure Krita -> Display. +#. When the user has trouble with anything related to preview or display, ask them to change :guilabel:`Canvas Graphics Acceleration` in :menuselection:`Settings --> Configure Krita --> Display`. .. note: Telling people to disable canvas acceleration to get better performance is something we shouldn't do, ever. #. When the user has any weird issue, something you've never heard about, ask them to reset the configuration: :ref:`faq_reset_krita_configuration`. Advices for supporters ---------------------- #. If you don't understand the question, ask for clarification -- asking for a screen recording or a screenshot is perfectly fine. #. If you don't know the solution but you know what information will be needed to investigate the issue further, don't hesitate to ask. Other supporters may know the answer, but have too little time to move the user through the whole process, so you're helping a lot just by asking for additional information. This is very much true in case of tablet issues, for example. #. If you don't know the answer/solution and the question looks abandoned by other supporters, you can always ask for help on Krita IRC channel. It's #krita on freenote.net: :ref:`the_krita_community`. #. Explain steps the user needs to make clearly, for example if you need them to change something in settings, clearly state the whole path of buttons and tabs to get there. -#. Instead of `Settings -> Configure Krita` use just `Configure Krita` -- it's easy enough to find and Mac users (where you need to select Krita -> Settings) won't get confused. +#. Instead of :menuselection:`Settings --> Configure Krita` use just :menuselection:`Configure Krita` -- it's easy enough to find and Mac users (where you need to select :menuselection:`Krita --> Settings`) won't get confused. -#. If you ask for an image, mention usage of `Imgur `_ or `Pasteboard `_, otherwise reddit users might create a new post with this image instead of including it to the old conversation. +#. If you ask for an image, mention usage of `Imgur `_ or `Pasteboard `_, otherwise Reddit users might create a new post with this image instead of including it to the old conversation. #. If you want to quickly answer someone, just link to the appropriate place in this manual page -- you can click on the little link icon next to the section or subsection title and give the link to the user so they for example know what information about their tablet issue you need. #. If the user access the internet from the country or a workplace with some of the websites blocked (like imgur.com or pastebin.com), here is a list of alternatives that works: - * Images (e.g. screenshots): `Pasteboard ` + * Images (e.g. screenshots): `Pasteboard `_ - * Text only: `BPaste `, `paste.ubuntu.org.cn `, `paste.fedoraproject.org `, `https://invent.kde.org/dashboard/snippets (needs KDE Identity) ` + * Text only: `BPaste `_, `paste.ubuntu.org.cn `_, `paste.fedoraproject.org `_ or `https://invent.kde.org/dashboard/snippets (needs KDE Identity) `_. - * .kra and other formats: by mail? Or encode the file using `base64` command on Linux, send by mail or on pastebin, then decode using the same command. + * ``.kra`` and other formats: by mail? Or encode the file using `base64` command on Linux, send by mail or on Pastebin, then decode using the same command. .. attention:: If you ask user to store their log or other data on a website, make sure it stays there long enough for you to get it -- for example bpaste.net stores files by default only for a day! And you can extend it only to one week. - Make sure they don't post their personal data. Tablet Tester log is safe, log from the Help -> Show system information for bug reports might not be that safe. Maybe you could ask them to send it to you by mail? - - - - - - - - - - - - - - - + Make sure they don't post their personal data. Tablet Tester log is safe, log from the :menuselection:`Help -> Show system information for bug reports` might not be that safe. Maybe you could ask them to send it to you by mail? diff --git a/general_concepts/colors.rst b/general_concepts/colors.rst index 8341deafb..4ec242361 100644 --- a/general_concepts/colors.rst +++ b/general_concepts/colors.rst @@ -1,81 +1,81 @@ .. meta:: :description lang=en: The Colors Category. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Emmet O'Neil :license: GNU free documentation license 1.3 or later. .. _cat_colors: .. _general_concept_color: ###### Colors ###### Okay, so... Let's talk **colors**! Colors are pretty, and they're also *pretty* fundamental to painting. When painting, we want to be able to access and manipulate colors easily to do fun stuff like :ref:`mixing ` them together or matching them to create visual **harmony** or **contrast**. We also want to be able to quickly find our favorite shades of red or favorite tints of blue without thinking or working too hard. All of this becomes even more important the more colors we have access to! Naturally, the first thing we do is organize the colors, usually based on what we see in nature. For example, we tend to order hues in the order that they appear in a rainbow, and we think about brightness of values as a tonal range from white to black. Of course, nature itself is tied to physics, and the order of hues and the concept of brightness has everything to do with the wavelength and energy of light as it bounces around and eventually enters our eyes. .. image:: /images/color_category/Krita_color_mixing_natural_order.png :align: center In the case of *traditional media*, we order the colors (**hues**) by how they result from mixes of other colors, starting with the *subtractive* **primary colors**: cyan, magenta, yellow. Mixing each primary color with each other reveals three secondary colors: violet, orange, and green. Mixing between those colors creates tertiary colors, and so on - the variations of hues between each named color are practically limitless! Thinking of colors in this way creates a circle of hues that artists call *"the color wheel"*! Each one of these hues can be made **lighter (tint)** or **darker (shade)** by mixing with white or black, respectively, and any color can be made **less saturated** (more gray or muted) by mixing with another color on the opposite side of the color wheel. .. image:: /images/color_category/Krita_color_mixing_traditional_order.png :align: center In the digital world of computers color is treated similarly, and we order colors by the *way the screen generates them*; each **pixel** of color on our screen is produced by combining *super tiny* red, green, and blue lights of varying intensities. Unlike mixing paint, where light intensity is subtracted by pigment and mixing all the colors together produces a muddy brown or gray, *mixing lights is additive* - no light at all is obviously black, and mixing all of the colored lights produces white. As such, we can make a list of possible primary color **intensities**: .. image:: /images/color_category/percentages_red.svg Shown above is a table of different intensities of red light. Our screens can certainly create a lot of shades of red, but we only start to see *the power of pixels* when we add in the other primary colors, green and blue, and show the colors of light that are produced when they are added together! For example, here's a table showing various mixes of red and green: .. image:: /images/color_category/percentages_red_green.svg But that's just red and green, what about blue? I guess we can make *even more tables* to show what happens when different amounts of blue are added into the mix: .. image:: /images/color_category/percentages_red_green_blue.svg This way of ordering colors is probably familiar to you if you have used some programs for making internet applications, like Flash. In fact, if we had made 6 samples instead of 5 per "channel" (that is, per each primary color), we'd have gotten the `216 websafe colors `_! Showing the colors in a bunch of tables just *feels wrong*, though, doesn't it? That's because, while our tables are *2D*, as we are mixing *three* primary colors, color can be thought of as *3D*! It’s a bit odd the first time you think about it this way, but you can actually stack these tables based on the amount of blue and they become a **cube**! .. image:: /images/color_category/Rgbcolorcube_2.png :align: center -This cube is not filled with water, or sand, or even *concrete*, but colors! Colors are pretty *abstract*, and we typically talk about cubes and other 3D objects that represent abstract ideas as **spaces**, hence we call this cube a **color space**. Because this particular cube uses red, green, and blue as its axes, we say that our cube is in the RGB :ref:`RGB color model `. +This cube is not filled with water, or sand, or even *concrete*, but colors! Colors are pretty *abstract*, and we typically talk about cubes and other 3D objects that represent abstract ideas as **spaces**, hence we call this cube a **color space**. Because this particular cube uses red, green, and blue as its axes, we say that our cube is in the :ref:`RGB color model `. There are many more color models. For example, if we were to balance our cube on the black corner, the white corner would be right under our finger at the very top of the cube. And as geometry and maths would have it, if we were to cut the cube in half as we balanced it, the line from the white point at the top to the black point at the bottom would be the **grayscale**. .. image:: /images/color_category/Rgbcolorcube_HSI.png :align: center When you think about a strip of grays running through the middle of the cube, as we move farther away from that grayscale towards the *outer edges* of the cube the colors would begin to become more saturated (colorful and vivid). The circle of colors around that middle axis of gray would then define the hue, with a different color in each direction. This is the basic idea of the :ref:`HSV, HSL, HSI, and HSY color models `. This particular model is called **HSI** (hue, saturation, and intensity), because it maps each unique color to the intensity of the primary colored lights that mix to create them. There are other color models, like :ref:`model_lab`, where we look at the corresponding gray value of a color first, and then try to describe it, not it terms of hue and saturation, but by how red, green, blue, and yellow it is. Because our brains cannot really comprehend a color that is both green and red, or yellow and blue, this makes them good *polar opposites* in a sliding scale. We call this a **perceptual model**, as it is based on how *we see color instead of how the color is generated*. Color models describe color spaces, which, in turn, are all sorts of sizes and shapes as well. Krita allows you to do operations in different models and spaces, and we call this functionality **"Color Management"**. -Color Management is necessary for :ref:`**CMYK** (subtractive) ` support, but outside of that, not many drawing or painting programs offer the feature, as *some* developers believe that artists have no need for such functionality. *What a pity!* Especially because Color Management allows for far more *cool tricks* than just basic CMYK support, and the ability to *manipulate colors like a computer can* is perhaps digital painting’s most unique quality! +Color Management is necessary for :ref:`CMYK (subtractive) ` support, but outside of that, not many drawing or painting programs offer the feature, as *some* developers believe that artists have no need for such functionality. *What a pity!* Especially because Color Management allows for far more *cool tricks* than just basic CMYK support, and the ability to *manipulate colors like a computer can* is perhaps digital painting’s most unique quality! As Krita is giving almost *unprecedented control of color*, this unfortunately means that there are little to no articles out there on how to use color management for artists or painters. And so, we made this category and hope to fill it up with relatively short articles explaining color-related concepts in a light-hearted and visual manner. We recommend going over the :ref:`color managed workflow page ` next - even if you don't plan on using it, it will help make sense out of the many features related to colors and Color Management. Other than that, each article should stand on its own and can be taken in at your own direction and pace! .. toctree:: :maxdepth: 1 :caption: Topics: :glob: colors/* diff --git a/general_concepts/file_formats.rst b/general_concepts/file_formats.rst index a1be7f6d8..3fd48810a 100644 --- a/general_concepts/file_formats.rst +++ b/general_concepts/file_formats.rst @@ -1,58 +1,58 @@ .. meta:: :description: The file formats category. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier :license: GNU free documentation license 1.3 or later. .. _general_concept_file_formats: ============ File Formats ============ This category is for graphics file-formats. While most file-formats can be looked up on wikipedia, this doesn't always explain what the format can be used for and what its strengths and weaknesses are. In this category we try to describe these in a manner that can be read by beginners. Generally, there are the following features that people pay attention to in regards to file formats: Compression ----------- Compression is how the file-format tries to describe the image with as little data as possible, so that the resulting file is as small as it can get without losing quality. What we generally see is that formats that are small on disk either lose image quality, or require the computer to spend a lot of time thinking about how the image should look. Vector file-formats like ``svg`` are a typical example of the latter. They are really small because the technology used to create them is based on mathematics, so it only stores maths-variables and can achieve very high quality. The downside is that the computer needs to spend a lot of time thinking about how it should look, and sometimes different programs have different ways of interpreting the values. Furthermore, vector file-formats imply vector graphics, which is a very different way of working than Krita is specialized in. :ref:`Lossy file formats `, like ``jpg`` or ``webp`` are an example of small on disk, but lowering the quality, and are best used for very particular types of images. Lossy thus means that the file format plays fast and loose with describing your image to reduce filesize. :ref:`Non-lossy or lossless formats `, like ``png``, ``gif`` or ``bmp`` are in contrast, much heavier on disk, but much more likely to retain quality. Then, there's proper working file formats like Krita's ``.kra``, Gimp's ``xcf``, Photoshop's ``psd``, but also interchange formats like ora and exr. These are the heaviest on the hard-drive and often require special programs to open them up, but on the other hand these are meant to keep your working environment intact, and keep all the layers and guides in them. Metadata -------- Metadata is the ability of a file format to contain information outside of the actual image contents. This can be human readable data, like the date of creation, the name of the author, a description of the image, but also computer readable data, like an icc-profile which tells the computer about the qualities of how the colors inside the file should be read. Openness -------- This is a bit of an odd quality, but it's about how easy it to open or recover the file, and how widely it's supported. -Most internal file formats, like PSD are completely closed, and it's really difficult for human outsiders to recover the data inside without opening photoshop. Other examples are camera raw files which have different properties per camera manufacturer. +Most internal file formats, like PSD are completely closed, and it's really difficult for human outsiders to recover the data inside without opening Photoshop. Other examples are camera raw files which have different properties per camera manufacturer. SVG, as a vector file format, is on the other end of the spectrum, and can be opened with any text-editor and edited. Most formats are in-between, and thus there's also a matter of how widely supported the format is. jpg and png cannot be read or edited by human eyes, but the vast majority of programs can open them, meaning the owner has easy access to them. .. toctree:: :maxdepth: 1 :caption: Contents: :glob: file_formats/*