From 62963aa748f4ca4db5dc4e3ebb54f96e9414aba8 Mon Sep 17 00:00:00 2001 From: Jehan Date: Sat, 15 Oct 2022 22:29:03 +0200 Subject: [PATCH] devel-docs: delete various devel docs which are now in developer.gimp.org. --- devel-docs/CODING_STYLE.md | 963 ----------------------------------- devel-docs/HACKING.md | 8 +- devel-docs/Makefile.am | 2 - devel-docs/README.md | 14 +- devel-docs/compositing.txt | 274 ---------- devel-docs/exif-handling.txt | 97 ---- 6 files changed, 11 insertions(+), 1347 deletions(-) delete mode 100644 devel-docs/CODING_STYLE.md delete mode 100644 devel-docs/compositing.txt delete mode 100755 devel-docs/exif-handling.txt diff --git a/devel-docs/CODING_STYLE.md b/devel-docs/CODING_STYLE.md deleted file mode 100644 index 992bff2be5..0000000000 --- a/devel-docs/CODING_STYLE.md +++ /dev/null @@ -1,963 +0,0 @@ -# GIMP Coding Style - -This document describes the preferred coding style for the GIMP source code. -It was originally inspired by [GNU's coding -style](https://www.gnu.org/prep/standards/standards.html#Writing-C) and -developed from there across the years. - -Coding style is completely arbitrary as it is a a matter of consistency, -readability and maintenance, not taste. Therefore it doesn't matter what -you prefer (we all have some part of the rules we would like different, -and we can apply these to our personal projects), just follow these -rules so that we can work together efficiently. - -This document will use examples at the very least to provide -authoritative and consistent answers to common questions regarding the -coding style and will also try to identify the allowed exceptions. - -## Table of contents - -[TOC] - -## Dealing with the old code - -__The new GIMP code should adhere to the style explained below.__ The existing -GIMP code largely follows these conventions, but there are some differences like -extra or missing whitespace, tabs instead of space, wrong formatting, etc. - -__Our policy is to update the style of a code block or function if and only if -you happen to touch that code.__ - -Please don't waste your time and reviewers' time with merge requests or patches -with _only_ code style fixes unless you have push rights to the GIMP's -repository. - -## Git usage -### Commit messages - -Commit messages should follow the following rules: - -- Always provide informative titles. No one-word commits saying nothing - like "bug fix", so that we can at least search through the git history - if needed. It can still be short messages for very simple fixes: for - instance "Fix typo" or "Fix small memory leak" are informative of the - type of fix. -- Prefix the title with the codebase section (i.e. the root folder - usually) which was changed. For instance: `libgimpbase: fix memory - leak` immediately tells us it was a memory leak fix in the - `libgimpbase` library. If several sections are touched, list them with - comma-separation. -- Alternatively, when the change is a response to a bug report, you may - prefix with `Issue #123:` (where `#123` is the report ID) instead. -- If the changed code itself is not self-explanatory enough, you can add - longer change description (2 lines after the title) to explain more. - It is not mandatory, but it is never unwelcome because old code - exploration to understand why things were done (possibly years before - by people long gone) is a real thing we do all the time. So if it's - not obvious, explain us. -- Explanations can also be made in the shape of links to a bug report - (ours, or a third-party project tracker, or some manual), even though - additional text explanations may still be useful (unfortunately URLs - may change or disappear). If the link is to our own bug tracker, - usually giving the ID is enough. -- Same [as for code](#line-width), wrap your commit message to - reasonable line widths, such as 72 or 80 maximum so that other - contributors don't have to scroll horizontally on narrow - vizualisation. There may be exceptions, for instance when pasting some - error messages which may end up confusing when wrapped. But other than - this, wrap your text (most `git` client would have a feature to do it - for you). -- If the title is too long because of the max-width settings, a common - format is to break it with '…' and to continue the title 2 lines below. - Then the description goes again 2 lines below. - -Here is an example of a well formatted fix in the `plug-ins/` section: - -``` -plug-ins: fix file-gih. - -We currently cannot call gimp_pdb_run_procedure() for procedures -containing arrays because this C-type doesn't contain the size -information (which is in a second parameter but since the rule is not -hard-coded, our API can't know this). - -See issue #7369. -``` - -Here is another as a response to a bug report and a long title: - -``` -Issue #6695: Wrong tab after JPG export because of "Show preview"… - -… feature. - -Using the new gimp_display_present() function in file-jpeg to make sure -the original display is back to the top. -``` - -If you want to see more good examples, this `git` command will list -commits whose messages are generally well formatted: -`git log --author="Jehan\|mitch\|Jacob Boerema"` - -### Linear git log - -Nearly all our repositories (`gimp-web` being the exception) have a -fully linear history. The "merge commit" workflow is definitely good and -useful in some projects' workflow, especially with bigger projects with -many contributors and subdivided maintenance roles (where the main tree -is mostly about merging public trees of several submaintainers' public -trees, who themselves applied contributed commits by individuals). - -This doesn't work well with GIMP's current workflow and our number of -contributors. This is even worse with the completely useless merge -commits created by hosting tools which completely misused (or even -misunderstood) the merge concept. - -This is why our Gitlab projects are configured to only push commits -linearly. This means that when a contributed tree is behind, you must -first rebase it through the "Rebase" button in the merge request (which -requires contributors to check the "*Allow commits from members who can -merge to the target branch*" option) or by rebasing in the tree then -force-pushing when Gitlab is unable to merge. - -When you push directly (for contributors with push rights), you are also -expected to never push a merge commit. - -### Multiple or single commits? - -When contributing merge requests or patch files, you should break your -work into logical changes, not into review timelines. - -E.g. after a review, instead of pushing fixes as an additional commit, -amend your commits to rewrite your local git history as though reviewed -bugs never existed. - -On the other hand, we appreciate separate commits when they are logical -units. For instance, you could have 1 commit adding a GUI feature, then -1 commit adding a `libgimp` API to manipulate the new feature and 1 -commit for a plug-in to use this new API. It makes perfect sense to -separate these 3 changes into their own commits and even help for review -and later dig through development logs. - -## C code -### Line width - -The recommended line width for source files is _80 characters_ whenever possible. -Longer lines are usually an indication that you either need a function or a -pre-processor macro. - -The point is to have clear code to read and not overly long lines. Don't break -code into ugly and choppy parts to blindly follow this rule. - -Function definitions in the function forward declaration block don't have to -obey the 80 characters limit. The only general rule for headers is to align the -function definitions vertically in three columns. -See more information in [Headers sections](#Headers) - -### Whitespaces -#### Indentation - -Each new level is indented 2 or more spaces than the previous level: - -```c - if (condition) - single_statement (); -``` - -Use only __space characters__ to achieve this. Code indented with tabs will not -be accepted into the GIMP codebase. - -Even if two spaces for each indentation level allow deeper nesting, GIMP favors -self-documenting function names that can be quite long. For this reason, you -should avoid deeply nested code. - -*Note*: the only place where we use Tab indentation and alignment is the -Makefiles. In there, Tab are expected to be displayed as 8 characters -for proper display - -#### Vertical spaces (new lines) - -Except for one single newline at the end of the file, other empty lines (at the -beginning and the end) of a file are not allowed. - -On the other hand, empty lines in the middle of code are very encouraged -for well-ventilated code. For instance gathering and separating code by -logical parts making it easy to read and understand. - -#### Horizontal spaces - -Always put a space before an opening parenthesis but never after: - -```c - /* valid */ - if (condition) - do_my_things (); - - /* valid */ - switch (condition) - { - } - - /* invalid */ - if(condition) - do_my_things(); - - /* invalid */ - if ( condition ) - do_my_things ( ); -``` - -Do not eliminate whitespace and newlines just because something would -fit on 80 characters: - -```c - /* invalid */ - if (condition) foo (); else bar (); -``` - -#### Tab characters in strings - -Use `\t` instead of literal tab inside the source code strings. - -### Braces - -#### If-else - -Don't use curly braces for single statement blocks: - -```c - /* valid */ - if (condition) - single_statement (); - else - another_single_statement (arg1); -``` - -In the case of multiple statements, put curly braces on another indentation level: - -```c - /* valid */ - if (condition) - { - statement_1 (); - statement_2 (); - statement_3 (); - } - - /* invalid */ - if (condition) { - statement_1 (); - statement_2 (); - } - - /* invalid */ - if (condition) - { - statement_1 (); - statement_2 (); - } -``` - -The "no block for single statements" rule has only three exceptions: - - ① _Both sides of the if-else statement_ must have curly braces when - either side of this if-else statement has braces or when - the single statement covers multiple lines, and it's followed - by else or else if (e.g., for functions with many arguments). - -```c - /* valid */ - if (condition) - { - a_single_statement_with_many_arguments (some_lengthy_argument, - another_lengthy_argument, - and_another_one, - plus_one); - } - else - { - another_single_statement (arg1, arg2); - } -``` - - ② if the condition is composed of many lines: - -```c - /* valid */ - if (condition1 || - (condition2 && condition3) || - condition4 || - (condition5 && (condition6 || condition7))) - { - a_single_statement (); - } -``` - - ③ In the case of nested if's, the block should be placed on the outermost if: - -```c - /* valid */ - if (condition) - { - if (another_condition) - single_statement (); - else - another_single_statement (); - } - - /* invalid */ - if (condition) - if (another_condition) - single_statement (); - else if (yet_another_condition) - another_single_statement (); -``` - -#### Switch - -A `switch()` should open a block on a new indentation level, and each case -should start on the same indentation level as the curly braces, with the -case block on a new indentation level: - -```c - /* valid */ - switch (condition) - { - case FOO: - do_foo (); - break; - - case BAR: - do_bar (); - break; - } - - /* invalid */ - switch (condition) { - case FOO: do_foo (); break; - case BAR: do_bar (); break; - } - - /* invalid */ - switch (condition) - { - case FOO: do_foo (); - break; - case BAR: do_bar (); - break; - } - - /* invalid */ - switch (condition) - { - case FOO: - do_foo (); - break; - case BAR: - do_bar (); - break; - } -``` - -It is preferable, though not mandatory, to separate the various cases with -a newline: - -```c - switch (condition) - { - case FOO: - do_foo (); - break; - - case BAR: - do_bar (); - break; - - default: - do_default (); - break; - } -``` - -If a case block needs to declare new variables, the same rules as the inner -blocks (see above) apply; place the break statement outside of the inner block: - -```c - switch (condition) - { - case FOO: - { - int foo; - - foo = do_foo (); - } - break; - - ... - } -``` - -Do not add `default:` case if your `switch ()` is supposed to handle _all cases_. - -#### Random blocks - -Using blocks to group code is discouraged and must not be used in newly -written code. - -```c -int retval = 0; -gbool condition = retval >= 0; - -statement_1 (); -statement_2 (); - - /* discouraged in newly written code */ - { - int var1 = 42; - gboolean res = FALSE; - - res = statement_3 (var1); - retval = res ? -1 : 1; - } -``` - -### Conditions - -Do not check boolean values for equality: - -```c - /* valid */ - if (another_condition) - do_bar (); - - /* invalid */ - if (condition == TRUE) - do_foo (); -``` - -Even if C handles NULL equality like a boolean, be explicit: - -```c - /* valid */ - if (some_pointer == NULL) - do_blah (); - - /* invalid */ - if (some_other_pointer) - do_blurp (); -``` - -When conditions split over multiple lines, the logical operators should always -go at the end of the line. Align the same level boolean operators to show -explicitly which are on the same level and which are not: - -```c - /* valid */ - if (condition1 && - condition2 && - (condition3 || (condition4 && condition5))) - { - do_blah (); - } - - /* invalid */ - if (condition1 - || condition2 - || condition3) - { - do_foo (); - } -``` - -### Variables declaration and definition - -Place each variable on a new line. The variable name must be right-aligned, -taking into account pointers: - -```c - /* valid */ - int first = 42; - gboolean second = TRUE; - GimpObject *third = NULL; -``` - -Blocks of variable declaration/initialization should align the variable names, -allowing quick skimming of the variable list. - -### Functions - -Function header has the return type on one line; the name starting in the first -column of the following line. Prototype each parameter and place each on a -new line. - -In function names, each word must be lowercase and separated by an underscore. - -In the function definition, place the return value on a separate line from the -function name: - -```c -void -my_function (void) -{ -} -``` - -The parameters list must be broken into a new line for each parameter, with the -parameter names right-aligned, taking into account pointers: - -```c -void -my_function (some_type_t some_param, - another_type_t *a_pointer_param, - final_type_t final_param) -{ -} -``` - -While curly braces for function definitions should rest on a new line they -should not add an indentation level: - -```c -/* valid */ -static void -my_function (int parameter) -{ - do_my_things (); -} -``` - -The alignment also holds when invoking a function: - -```c - align_function_arguments (first_argument, - second_argument, - third_argument); -``` - -If your function name is very long, it's always better to extract arguments into -separate variables to improve readability: - -```c - /* valid */ - first_a = argument_the_first; - second_a = argument_the_second; - a_very_long_function_name_with_long_arguments (first_a, second_a); -``` - -Keep the function name and the arguments on the same line. Otherwise, it will -hurt readability. - -```c - /* invalid */ - a_very_long_function_name_with_long_arguments - (argument_the_first, argument_the_second); -``` - -### Macros - -Try to avoid private macros unless strictly necessary. Remember to `#undef` -them at the end of a block or a series of functions needing them. - -Use inline functions instead of private macro definitions. -Do not use public macros unless they evaluate to a constant. - -### Includes - -GIMP source files should never include the global `gimp.h` header, but instead -include the individual headers that are needed. - -Includes must be in the following order: - - 0. `config.h` first; - 0. System and third-party headers; - 0. GIMP library headers (`libgimp*` headers); - 0. GIMP core/app headers that it needs including its own; - -Sort alphabetically the includes within the blocks. - - -```c -/* valid */ -#include "config.h" - -#include -#include - -#include "libgimpbase/gimpbase.h" -#include "libgimpcolor/gimpcolor.h" - -#include "core/gimp.h" -#include "core/gimpcontainer.h" - -#include "gimpcolorpanel.h" -#include "gimpcontainerentry.h" -``` - -### Structures - -When declaring a structure type use newlines to separate logical sections: - -```c - /* preferred for new code*/ - typedef struct - { - gint n_pages; - gint *pages; - - gbool read_only; - } Pages; -``` - -When initializing a structure variable with constants, shortly enough -that it can be done on a single line, then you should add a space after -the opening curly brace and before the closing one, such as: - -```C - GimpRGB color = { 0.0, 0.0, 0.0, GIMP_OPACITY_OPAQUE }; -``` - -### Memory management - -To dynamically allocate data on the heap, use `g_new()`. To allocate memory for -multiple small data structures, `g_slice_new()`. - -When possible, all public structure types should be returned fully initialized, -either explicitly for each member or by using `g_new0()` or `g_slice_new0()`. - -As a general programming rule, it is better to allocate and free data on the -same level. It is much easier to review code because you know that when you -allocate something there, then you also free it there. - -```c -GeglBuffer *buffer; -void *p; - -*buffer = gegl_buffer_new (some, args); -*p = g_new (something, n); - -/* do stuff */ - -g_object_unref (buffer); -g_free (p); -``` - -When a transfer of ownership is unavoidable make it clear in the function -documentation. - -### Comments -#### In-code explanation - -The only allowed style is C-style comments `/* */`. In particular C++ -comments `//` are strictly forbidden from our source. - -We are not asking contributors to over-comment their code, yet we highly -value quality comments to explain complicated algorithms or non-obvious -code. Just ask yourself this: what if someone sees my code 5 years later -(another contributor or even your future self)… - -- will one easily understand what you meant to do? -- In particular: if it needs to be removed later, won't one be scared to - delete now-useless code by fear of unexpected side-effects? -- Or oppositely: won't someone delete the code by mistake because it - looks useless while it was actually dealing with a very particular - (yet absolutely non-obvious) issue? - -Adding links which explain well a problem or the reason for some -non-obvious code is also permitted. For instance a link to a bug report -(ours or some other projects') can sometimes be a good complement to a -comment. -Nevertheless it should not be overdone and in particular not for links -likely to disappear (personal blog posts, forums, corporate websites -which often revamp their design, breaking URLs, etc.). - -#### Public API Documentation - -All public APIs (i.e. any function exported in a header inside -`libgimp*/` folders) **MUST** have proper GObject-introspection (GIR) comments. -For functions, these should be placed in the source file directly above. - -These annotations are also relevant for [GObject -Introspection](https://gi.readthedocs.io/en/latest/annotations/giannotations.html) -to generate bindings for other languages. - -```c -/* valid */ -/** - * gimp_object_set_name: - * @object: a #GimpObject - * @name: the @object's new name (transfer none) - * - * Sets the @object's name. Takes care of freeing the old name and - * emitting the ::name_changed signal if the old and new name differ. - **/ -void -gimp_object_set_name (GimpObject *object, - const gchar *name) -{ - - ... - -} -``` - -Doc comments for macros, function types, class structs, etc., should be placed -next to the definitions, typically in headers. - -#### Non-public API documentation - -Project-only code (for instance any code from the `app/` folder) can be -less documented. For instance when a function has obvious naming, not -explaining it is perfectly acceptable. - -Nevertheless adding documentation even for these private APIs is -welcome, especially when the usage is not as obvious as it looks, or -to make sure to advertize the proper memory handling (does it allocate -new memory? Which function to free it with? Or shouldn't the returned -memory be freed?), avoiding silly bugs and not wasting developer times -(when we have to look at the implementation to verify each time we use a -function). - -In such a case, using gtk-docs syntax is still a nice idea as we will -understand it directly (even though we won't generate any docs from it). - -### Public API -#### No variables - -Avoid exporting variables as public API since this is cumbersome on some -platforms. It is always preferable to add getters and setters instead. - -#### Def files for Windows - -List all public functions alphabetically in the corresponding `.def` file. - - - `app/gimpcore.def` - - `libgimp/gimp.def` - - `libgimpbase/gimpbase.def` - - etc - -## Natural language text - -### Base rules - -Any text in GIMP source should follow these base rules: - -- Our base language is US English, both for historical reason and - because this is the usual expectation with `gettext`, the - localization tool used by GIMP. In particular when variants of words - or idioms exist in several native English countries, we should choose - the US variant. Other English variants can be used in specific locales - (such as `en_GB` or `en_CA`…). -- Text meant for technical people, such as API documentation (in-code - comments, in-repository documentation, or gtk-doc/docgen style - comments for generated docs…) usually does not need localization, and - therefore can just be written in US English. -- Text meant to be viewed by all users should be translatable. In - particular in GIMP source code, it means that we need to use `gettext` - API. -- Use gender-neutral terms, in particular not using words such as "she/he" - or "her/his" is better. We should not use over-complicated wording to - achieve this and should look for simpler writing if necessary. -- Be nice and open-minded in all text, even in code comments. Remember - these will be read by others and that we are here to have fun - together, not fight. - -### User-visible text in C code - -As explained, C code uses the gettext API. Any text which might appear -in front of people should be translatable, with the following -exceptions: - -- Error or warning output in `stderr` might often be untranslated - (because we assume these are mostly used for debugging and people who - will see these would be more comfortable with digging into issue - causes; also it makes debugging and searches in code easier). -- Technical error text in the graphical interface when it is made to be - reported to developers. Basically error messages meant for users - themselves should still be translatable. For instance, if one tries to - draw on a layer group, we'd display: - - ```C - _("Cannot modify the pixels of layer groups.") - ``` - - Indeed this is an error message to give an information to the user. - It's not a bug. - Now when a crash happens, we add a translated header message to - explain a problem occured, but the core information stays in English - because we are not asking people to understand it, only report it to - us. - -The most common variant of gettext API is the underscore `_()` (alias of -`gettext()`) for simple text: - -```C -frame = gimp_frame_new (_("Shadows")); -``` - -When used in some widgets, we may want to add mnemonics for -accessibility. This is done with the underscore: - -```C -label = gtk_label_new_with_mnemonic (_("_Width:")); -``` - -Note that it is a good idea to not change well-known mnemonics, such as -`_("_OK")`, `_("_Cancel")` or `_("_Reset")`. Also you should avoid using -the same mnemonics in 2 widgets on the same interface (even though GTK -has some way to handle mnemonic duplicate, but it's not really -practical). - -Translators may (and often will) change mnemonics. It is therefore up to -them to take care of not having the same mnemonics on a same interface -in their specific locale. - -When some messages cannot be translated at initialization, you must use -the no-op variant `N_()`. For instance, when we declare and initialize a -struct: - -```C -static const struct -{ - const gchar *name; - const gchar *description; -} -babl_descriptions[] = -{ - { "RGB u8", N_("RGB") }, - […] - { "Y u8", N_("Grayscale") }, - […] - { "R u8", N_("Red component") }, - […] - { "G u8", N_("Green component") }, - […] -}; -``` - -The normal gettext `_()` would not compile because you must initialize -struct elements with constants. `N_()` allows the gettext tools to -detect the strings which will need to go into the translator files. -Note though that these strings will still need to be translated when -used at runtime: - -```C - g_hash_table_insert (babl_description_hash, - (gpointer) babl_descriptions[i].name, - gettext (babl_descriptions[i].description)); -``` - -Finally note that for any strings which depends on a variable number, -you must use the ngettext variant: - -```C - desc = g_strdup_printf (ngettext ("Crop Layer to Selection", - "Crop %d Layers to Selection", - g_list_length (layers)), - g_list_length (layers)); -``` - -It is important to use `ngettext()` even in cases where there will -always be a count bigger than 1. Say our indexed image do not support -the monochrome (1 color) case, and even less 0 colors, then this seems -useless because we will always use the second string only: - -```C - g_snprintf (buf, sizeof (buf), - ngettext ("Indexed color (monochrome)", - "Indexed color (%d colors)", - gimp_image_get_colormap_size (image)), - gimp_image_get_colormap_size (image)); -``` - -Yet it's actually not useless as it allows translators for languages -with more plural forms to translate GIMP correctly. For instance, -[gettext documentation](https://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms) -mentions the Polish language has different grammatical agreements for -2,3,4 and 5-21 or again 22-24 and so on. If we were to use solely -`_("Indexed color (%d colors)")`, Polish translators would not be able -to list all these cases (therefore GIMP would have a crappy Polish -localization), so we have to use `ngettext()` even if it feels useless -in English. - -Finally when you add translated strings in a file which had none until -now, for it to be processed by `gettext`, you need to add its path in -alphabetical order in `po/POTFILES.in` for core files (or other -`POTFILES.in`, for instance `po-plug-ins/POTFILES.in` for plug-ins). We -have a test checking this, so the `make distcheck` step will fail anyway -when you forgot to add a new file with translation. Yet as developers -don't always run this step locally, the bug may be discovered during CI -builds. It is obviously prefered to not forget it hence not push code -which breaks the CI (and localization). - -## Helping tools -### Git - -We recommend enabling the default git pre-commit hook that detects trailing -whitespace and non-ASCII filenames for you and helps you to avoid corrupting -GIMP's tree with it. - -In the terminal, navigate into your GIMP source code folder. Then do that as -follows (one command at a time): - -```shell - cp -v .git/hooks/pre-commit.sample .git/hooks/pre-commit - chmod a+x .git/hooks/pre-commit -``` - -If any command above fails, visit your `.git/hooks/` folder and check for the -existence of `pre-commit.sample` or `pre-commit` files. - -You might also find the `git-stripspace` utility helpful, which acts as a filter -to remove trailing whitespace as well as initial, final, and duplicate blank -lines. - -### Code editor / Integrated Development Environment (IDE) - -GIMP's codebase is not tied to a specific editor or IDE. The whole build -can be performed from anywhere, and we don't care what you write your -code with (as long as it follows syntax rules from this document). - -Several configuration files were contributed across the years to -configure your favorite software to follow our coding style. -You are very welcome to use them (or improve them and contribute the -change when they are not perfect): - -- [.dir-locals.el](.dir-locals.el) for Emacs; -- [.kateconfig](.kateconfig) for Kate; -- [c.vim](devel-docs/c.vim) for Vim (check the top comments to see how - to enable it automatically when opening a file in the GIMP tree). - -*Note: the Kate and Emacs config file should work out-of-the-box, but -the Vim one needs to be enabled explicitly because it is too powerful, -hence is basically [unsafe](https://github.com/vim/vim/issues/1015).* - -If you use another software to write code, you are welcome to contribute -coding style files following our rules. - -### Code Formatter - -Our project contains a `.clang-format` in the repository root. - -A good way to test your code is with the following command while it's -not committed yet: - -```sh -git diff -U0 --no-color | clang-format-diff -p1 -``` - -Note that we are not considering these format rules as perfect, because -it seems the tool still cannot handle several special cases we have in -our coding style. Also we are not perfectly fond of the way it handles -long lines (when to accept lines a bit longer than the max line width or -not) as well as other rules. Therefore the current document remains the -ultimate one to verify when unsure of how to format something. - -The CI for any merge request will contain a job called `clang-format` -which will also run your proposed change through the clang-format code -formatter as a soft verification of contributed patches. Note that this -job is only informational and in particular, it isn't considered a CI -failure, since — as said above — we are not perfectly happy with the -tool yet. -Nevertheless we expect new contributors to look at the result to fix -their basic coding style mistakes and free up reviewing contributors' -time. diff --git a/devel-docs/HACKING.md b/devel-docs/HACKING.md index 8b59f59513..d3e298bf48 100644 --- a/devel-docs/HACKING.md +++ b/devel-docs/HACKING.md @@ -135,10 +135,10 @@ request or attach your patch to the report as a plain text file, not compressed. Please follow the guidelines for coding style and other requirements -listed in [CODING_STYLE.md](CODING_STYLE.md). When you will contribute -your first patches, you will notice that we care very much about clean -and tidy code, which helps for understanding. Hence we care about coding -style and consistency! +listed in [CODING_STYLE.md](https://developer.gimp.org/core/coding_style/). When +you will contribute your first patches, you will notice that we care very much +about clean and tidy code, which helps for understanding. Hence we care about +coding style and consistency! ## Auto-generated Files diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am index f291f6e1e8..618ccb8281 100644 --- a/devel-docs/Makefile.am +++ b/devel-docs/Makefile.am @@ -7,12 +7,10 @@ SUBDIRS = \ performance-logs EXTRA_DIST = \ - CODING_STYLE.md \ HACKING.md \ README.md \ contexts.txt \ debug-plug-ins.txt \ - exif-handling.txt \ gitlab-milestones.txt \ includes.txt \ libtool-instructions.txt \ diff --git a/devel-docs/README.md b/devel-docs/README.md index 201c9faa65..d229b6d2a1 100644 --- a/devel-docs/README.md +++ b/devel-docs/README.md @@ -383,7 +383,7 @@ Eventually we want to move this pipeline to Gitlab as well. When writing code, any core developer is expected to follow: -- GIMP's [coding style](CODING_STYLE.md); +- GIMP's [coding style](https://developer.gimp.org/core/coding_style/); - the [directory structure](#directory-structure-of-gimp-source-tree) - our [header file inclusion policy](includes.txt) @@ -589,7 +589,7 @@ Developers are welcome to read the [specifications of XCF](specifications/xcf.tx Items in an image can be locked in various ways to prevent different types of edits. -This is further explained in [the specifications of locks](specifications/locks.md). +This is further explained in [the specifications of locks](https://developer.gimp.org/core/specifications/locks/). #### UI Framework @@ -627,11 +627,11 @@ GIMP supports Exif, IPTC and XMP metadata as well as various image format-specific metadata. The topic is quite huge and complex, if not overwhelming. -This [old document](exif-handling.txt) might be of interest (or maybe -not, it has not been recently reviewed and might be widely outdated; in -any case, it is not a complete document at all as we definitely do a lot -more nowadays). **TODO**: review this document and delete or update it -depending of whether it still makes sense. +This [old document](https://developer.gimp.org/core/specifications/exif_handling/) +might be of interest (or maybe not, it has not been recently reviewed and might +be widely outdated; in any case, it is not a complete document at all as we +definitely do a lot more nowadays). **TODO**: review this document and delete or +update it depending of whether it still makes sense. #### Tagging diff --git a/devel-docs/compositing.txt b/devel-docs/compositing.txt deleted file mode 100644 index d98b049bde..0000000000 --- a/devel-docs/compositing.txt +++ /dev/null @@ -1,274 +0,0 @@ -=================================== -Compositing and layer modes in GIMP -=================================== - -This document describes the process of compositing layers and the layer modes -in GIMP. - -License -------- -This is free documentation; you can modify and/or redistribute -it according to the terms of the GNU General Public License -as published by the Free Software Foundation, either version -2 of the license, or (at your option) any later version. - -About this document -------------------- - -This document was originally written by Henning Makholm and part of the -XCF file format specification. Because the topics here are more general -in the context of GIMP they have been moved into a separate document. - -9. COMPOSITING AND LAYER MODES -=============================== - -This section describes the "flattening" process that GIMP applies -when a multi-layer image is displayed in the editor or exported to -other image file formats. It is present for reference only; an XCF -consumer may well elect to do something different with pixel data from -the layers than flattening them. - -Most XCF consumers will need to react to the layer mode property of -each layer; such a reaction must be informed by knowledge of how the -different layer modes affect the flattening process. In some -applications it might be acceptable for an XCF consumer to refuse -processing images with layer modes other than "Normal", but such an -application will probably not be considered fully XCF capable by its -users. - -In this section we consider primary color (or grayscale) intensities -and alpha values for pixels to be real numbers ranging from 0.0 to -1.0. This makes many of the formulas easier; the reader is asked to -keep in mind that a (linear) conversion from the integral 0..255 scale -of the actual XCF scale is implied whenever data from the XCF file is -mentioned. - -Any practical implementation of the computations specified below may -suffer rounding errors; this specification do not detail how these are -to be handled. GIMP itself rounds values to an integral number of -255ths at many points in the computation. This specification does not -specify exactly which these points are, and authors of XCF renderers -that aim to reproduce the effects of GIMP's flattening down to the -least significant bits are referred to studying its source code. - -In the description below, the variable letter "a" is used for alpha -values. The variable letter "r", "g", "b" are used for primary -intensities, "y" is used for grayscale intensities, and "i" is used -for color map indexed. The letter "c" is used for the complete -color information for a pixel; depending on the color mode of the -image that is either an (r,g,b) triple, a y, or a c. - -The flattening process works independently for each pixel in the -canvas area. The description of some layer modes in the GIMP manual -may give the impression that they involve filters that let pixels -influence neighbor pixels, but that is not true. - -This description does not attempt to preserve the color information -for completely transparent pixels in a layer. If an application uses -this color information, it should document explicitly how it behaves -when transparent pixels from several different layers cover the same -point of the canvas. - -Flattening overview -------------------- - -This is how to compute the flattened result for a single pixel -position (in theory, that is - efficient implementations will of -course follow this procedure or an equivalent one for many pixels in -parallel): - -1. Initialize a "working pixel" (a1,c1) to be completely transparent - (that is, a1=0.0 and the value of c1 is immaterial). - -2. Do the following for each visible layer in the image, starting with - the one that comes LAST in the master layer list: - - 3. Ignore the layer if it is the floating selection, or if it - does not overlap the pixel position in question. - - 4. Let (a2,c2) be the pixel data for the layer at the pixel - position in question. If the layer does not have an alpha - channel, then set a1 to 1.0. - - 5. If the layer is the one that the floating selection is attached - to and the floating selection overlaps the pixel position in - question, then do the following: - - 6. Let (a3,c3) be the pixel data for the floating selection - layer at the pixel position in question. - - 7. If there is a selection channel, then let x be its value - at the pixel position in question, and set a3 to a3*x. - - 8. Let m3 be the layer mode of the floating selection. - - 9. Set (a2,c2) to COMPOSITE(a2,c2, a3,c3,m3). - The COMPOSITE function is defined below. - - 10. If the layer has a layer mask and it is enabled, then let x be - the value of the layer mask at the pixel position in question, - and set a2 to a2*x. - - 11. Let m2 be the layer mode of the layer. - - 12. If the layer is the bottommost visible layer (i.e., if it is - the last visible layer in the master layer list) and m2 is not - "Normal" or "Dissolve", then set m2 to "Normal". - - 13. Set (a1,c1) to COMPOSITE(a1,c1, a2,c2,m2). - The COMPOSITE function is defined below. - -14. If the flattened image is to be shown against a background of - color c0, then actually visible pixel is - COMPOSITE(1.0,c0, a1,c1,Normal). - - Note that unless all layers have mode Normal, it would give the - wrong result to start by initializing (a1,c1) to (1.0,c0). - -Helper functions ----------------- - -The following auxiliary functions are used in the definition of -COMPOSITE below: - - MIN(x1,...,xn) is the least value of x1...xn - - MAX(x1,...,xn) is the largest value of x1..xn - - MID(x1,...,xn) = (MIN(x1,...,xn)+MAX(x1,...,xn))/2 - - CLAMP(x) = if x < 0 then 0.0 else if x > 1 then 1.0 else x - - BLEND(a1,x1, a2,x2) = (1-k)*x1 + k*x2 - where k = a2/(1-(1-a1)*(1-a2)) - -Layer modes ------------ - -This and the following sections define the COMPOSITE function used in -the general flattening algorithm. - -"Normal" mode for RGB or grayscale images is the usual mode of -compositing in computer graphics with alpha channels. In indexed -mode, the alpha value gets rounded to either 1.0 or 0.0 such that -no colors outside the color map get produced: - - COMPOSITE(a1,y1, a2,y2,Normal) - = ( 1-(1-a1)*(1-a2), BLEND(a1,y1, a2,y2) ) - - COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,Normal) - = ( 1-(1-a1)*(1-a2), BLEND(a1,r1, a2,r2), - BLEND(a1,g1, a2,g2), - BLEND(a1,b1, a2,b2) ) - - COMPOSITE(a1,i1, a2,i2,Normal) = if a2 > 0.5 then (1.0,i2) else (a1,i1) - -"Dissolve" mode corresponds to randomly dithering the alpha channel to -the set {0.0, 1.0}: - - COMPOSITE(a1,c1, a2,c2,Dissolve) = chose pseudo-randomly between - (1.0,c2) with probability a2 - (a1,c1) with probability 1-a2 - -These two modes are the only ones that make sense for all of the RGB, -grayscale and indexed color models. In the indexed color model, all -layer modes except Dissolve are treated as Normal. - -Most layer modes belong to the following group, which makes sense for -RGB and grayscale images, but not for indexed ones: - - COMPOSITE(a1,y2, a2,y2,m) - = ( a1, BLEND(a1,y1, MIN(a1,a2),f(y1,y2, m)) ) - - COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,m) - = ( a1, BLEND(a1,r2, MIN(a1,a2),f(r1,r2, m)), - BLEND(a1,g1, MIN(a1,a2),f(g1,g2, m)), - BLEND(a1,b1, MIN(a1,a2),f(b1,g2, m)) ) - -when 3 <= m <= 10 or 15 <= m <= 21. - -The following table defines f(x1,x2,m): - - Multiply: f(x1,x2, 3) = x1*x2 - Screen: f(x1,x2, 4) = 1-(1-x1)*(1-x2) - Overlay: f(x1,x2, 5) = (1-x2)*x1^2 + x2*(1-(1-x2)^2) - Difference: f(x1,x2, 6) = if x1 > x2 then x1-x2 else x2-x1 - Addition: f(x1,x2, 7) = CLAMP(x1+x2) - Subtract: f(x1,x2, 8) = CLAMP(x1-x2) - Darken Only: f(x1,x2, 9) = MIN(x1,x2) - Lighten Only: f(x1,x2, 10) = MAX(x1,x2) - Divide: f(x1,x2, 15) = CLAMP(x1/x2) - Dodge: f(x1,x2, 16) = CLAMP(x1/(1-x2)) - Burn f(x1,x2, 17) = CLAMP(1-(1-x1)/x2) - Hard Light: f(x1,x2, 18) = if x2 < 0.5 then 2*x1*x2 else 1-2*(1-x1)(1-x2) - Soft Light: f(x1,x2, 19) = (1-x2)*x1^2 + x2*(1-(1-x2)^2) - Grain Extract: f(x1,x2, 20) = CLAMP(x1-x2+0.5) - Grain Merge: f(x1,x2, 21) = CLAMP(x1+x2-0.5) - -Note that the "Overlay" and "Soft Light" modes have identical effects. -In the "Divide", "Dodge", and "Burn" modes, division by zero should -be considered to produce a number so large that CLAMP(x/0) = 1 unless -x=0, in which case CLAMP(0/0) = 0. - -The remaining four layer modes only make sense in the RGB color model; -if the color mode of the image is grayscale or indexed they will be -interpreted as Normal. - - COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,m) - = ( a1, BLEND(a1,r2, MIN(a1,a2),r0), - BLEND(a1,g1, MIN(a1,a2),g0), - BLEND(a1,b1, MIN(a1,a2),b0) ) - where (r0,g0,b0) = h(r1,g1,b1, r2,g2,b2, m) - -when 11 <= m <= 14. - -For defining these modes, we say that - -(r,g,b) has the _hue_ of (r',g',b') - if r' = g' = b' and r >= g = b - or there exist p and q such that p>=0 and r=p*r'+q and b=p*b'+q and g=p*g'+q - -(r,g,b) has the _value_ of (r',g',b') - if MAX(r,g,b) = MAX(r',g',b') - -(r,g,b) has the _HSV-saturation_ of (r',g',b') - if r' = g' = b' = 0 and r = g = b - or MIN(r,g,b) = MAX(r,g,b)*MIN(r',g',b')/MAX(r',g',b') - -(r,g,b) has the _luminosity_ of (r',g',b') - if MID(r,g,b) = MID(r',g',b') - -(r,g,b) has the _HSL-saturation_ of (r',g',b') - if r' = g' = b' and r = g = b - or MAX(r,g,b)-MIN(r,g,b) = MIN(MID(r,g,b),1-MID(r,g,b)) * - (MAX(r',g',b')-MIN(r',g',b'))/MIN(MID(r',g',b'),1-MID(r',g',b')) - -Mode 11: Hue (H of HSV) - - h(r1,g1,b1, r2,g2,b2, 11) is - if r2=g2=b2 then (r1,g1,b1) unchanged - otherwise: the color that has - the hue of (r1,g2,b2) - the value of (r1,g1,b1) - the HSV-saturation of (r1,g1,b1) - -Mode 12: Saturation (S of HSV) - - h(r1,g1,b1, r2,g2,b2, 12) is the color that has - the hue of (r1,g1,b1) - the value of (r1,g1,b1) - the HSV-saturation of (r2,g2,b2) - -Mode 13: Color (H and S of HSL) - - h(r1,g1,b1, r2,g2,b2, 13) is the color that has - the hue of (r2,g2,b2) - the luminosity of (r1,g1,b1) - the HSL-saturation of (r2,g2,b2) - -Mode 14: Value (V of HSV) - - h(r1,g1,b1, r2,g2,b2, 14) is the color that has - the hue of (r1,g1,b1) - the value of (r2,g2,b2) - the HSV-saturation of (r1,g1,b1) \ No newline at end of file diff --git a/devel-docs/exif-handling.txt b/devel-docs/exif-handling.txt deleted file mode 100755 index e196752ee8..0000000000 --- a/devel-docs/exif-handling.txt +++ /dev/null @@ -1,97 +0,0 @@ - How GIMP should handle EXIF data - - Bill Skaggs 1/2/05 - -This is a summary of how an image editing program is supposed to -handle each of the EXIF fields, according to the EXIF specs. Note -that this expresses my understanding based on a quick reading, and -should not be taken as gospel. For details on the contents of each of -these fields, consult the formal EXIF specifications, available from -http://www.exif.org/specifications.html. - -(Note: according to the EXIF specs, an EXIF jpeg file must have a name -that is ASCII, in 8.3 format, with extension .JPG, but of course we -are not going to enforce this.) - - - -Fields that should be used to set up the GIMP image when an EXIF file -is loaded, either by using them to configure the image (e.g., -orientation), or by placing them in parasites that can be accessed by -non-exif-aware functions. - -Orientation -XResolution -YResolution -ResolutionUnit -ImageDescription -Artist -Copyright -Colorspace -ComponentsConfiguration -UserComment -SubjectArea -SubjectLocation -ImageUniqueID -PixelXDimension -PixelYDimension - - - -Fields that should be modified by GIMP when an EXIF jpeg file is -saved. A letter "M" indicates fields whose presence is mandatory -according to the spec. - -Orientation -XResolution (M) -YResolution (M) -ResolutionUnit (M) -Software -DateTime -ImageDescription -Artist -Colorspace (M) -PixelXDimension (M) -PixelYDimension (M) -ComponentsConfiguration (M) -UserComment -SubsecTime -SubjectArea -SubjectLocation -FileSource -ImageUniqueID -thumbnail Compression (M) -thumbnail XResolution (M) -thumbnail YResolution (M) -thumbnail JPEGInterchangeFormat (M) -thumbnail JPEGInterchangeFormatLength (M) - - - -Fields that should be used and saved related to color management: - -TransferFunction -WhitePoint -PrimaryChromaticity -YCbCrCoefficients -ReferenceBlackWhite - - - -Fields that should be deleted if they exist when saving a file as -jpeg, because they only apply to uncompressed (TIFF) data. This -applies both to the main image and to the thumbnail, if there is one. - -ImageWidth -ImageLength -BitsPerSample -Compression -SamplesPerPixel -PhotometricInterpretation -StripOffsets -PlanarConfiguration -YCbCrSubSampling - - - -Any field not mentioned here should be passed through unchanged.