devel-docs: rewording, grammar fixes, etc.

devel-docs/README

@@ -3,10 +3,11 @@ Developers documentation
 
 This directory holds information that you will find useful if you
 develop a GIMP plug-in or want to work on the GIMP core.
-See http://wiki.gimp.org/index.php/Main_Page for more.
+
+See http://wiki.gimp.org/index.php/Main_Page for more information.
 
    app                     - setup for documentation of the GIMP core;
-                             not build by default since it is huge and
+                             not built by default since it is huge and
                              only relevant for core developers
 
    libgimp
@@ -28,7 +29,7 @@ See http://wiki.gimp.org/index.php/Main_Page for more.
                              uses milestones in the Bugzilla bugtracker
    commit-rules.txt        - describes rules and things to think
                              about when creating GIMP commits
-   contexts.txt            - describes how the GimpContext's in GIMP are used
+   contexts.txt            - describes how GimpContexts are used in GIMP
    debug-plug-ins.txt      - how to debug GIMP plug-ins
    exif-handling.txt       - how GIMP should handle EXIF data
    includes.txt            - the policy for inclusion of header files
@@ -36,7 +37,7 @@ See http://wiki.gimp.org/index.php/Main_Page for more.
    release-howto.txt       - a check-list for doing a GIMP release
    submitting-patches.txt  - how to submit a patch for GIMP
    tagging.txt             - how resource tagging in Gimp works
-   ui-framework.txt        - describes the GIMP UI framework functions and
+   ui-framework.txt        - describes how the GIMP UI framework functions and
                              how it is implemented
    undo.txt                - description of the undo system
 
@@ -46,9 +47,9 @@ See http://wiki.gimp.org/index.php/Main_Page for more.
                              also check out gimp-module-dependencies.svg
 
 
-   gbr.txt                 - description of the GBR format used to store a
+   gbr.txt                 - description of the GBR format used to store
                              pixmap brushes
-   ggr.txt                 - description of the GGR format used to store a
+   ggr.txt                 - description of the GGR format used to store
                              GIMP gradients
    gih.txt                 - description of the GIH format used to store a
                              series of pixmap brushes

devel-docs/bugzilla-milestones.txt

@@ -9,8 +9,8 @@ https://bugzilla.gnome.org/browse.cgi?product=GIMP.
 Stable milestone
 ----------------
 
-The bugs on the stable milestone, i.e. on the 2.6 milestone if GIMP
+The bugs on a stable milestone, e.g. on the 2.8 milestone if GIMP
-2.6 is the stable release, are bugs for which fixes will be accepted
+2.8 is the stable release, are bugs for which fixes will be accepted
 onto the stable branch.
 
 Reports for bugs that are fixed in the stable branch should have the
@@ -21,8 +21,8 @@ branch and then cherry-picked to the stable branch.
 Next stable milestone
 ---------------------
 
-The bugs/enhancement requests on the next stable milestone, i.e. on
+The bugs/enhancement requests on the next stable milestone, e.g. on
-the 2.8 milestone if GIMP 2.6 is the stable release, are bugs or
+the 2.10 milestone if GIMP 2.8 is the stable release, are bugs or
 enhancement requests scheduled and planned for inclusion in the next
 stable version. This list is rather dynamic and will be altered during
 the execution of a development cycle.

devel-docs/contexts.txt

@@ -4,7 +4,7 @@ contexts.txt
 Introduction
 ------------
 
-This file describes how the GimpContext's in GIMP are used.
+This file describes how GimpContexts are used in GIMP.
 
 
 Overview
@@ -21,7 +21,7 @@ also have their own context.
 Communication between contexts
 ------------------------------
 
-So how does the various contexts synchronize and propagate changes?
+So how do the various contexts synchronize and propagate changes?
 This is most easily explained by a sequence diagram. Let's say there
 are two image windows with different images opened in GIMP. Call them
 A and B. Let's say A is currently active. When the user activates B,
@@ -54,9 +54,9 @@ events is as follows:
         |                |              |              |------------>|
         |                |              |              |             |
 
-In single-window mode, the dockables listens directly to the user
+In single-window mode, the dockables listen directly to the user
 context. When switching between single-window and multi-window modes,
-the dockables are updated with their new context. Just as when moving
+the dockables are updated with their new context, just as when moving
 a dockable between different dock windows and thus also different
 contexts. The sequence diagram for single-window mode is:
 

devel-docs/gtkbuilder-porting-guide.txt

@@ -1,7 +1,7 @@
 gtkbuilder-porting-guide.txt
 ============================
 
-This document describes some tips and rules for how to port UI code
+This document describes some tips and rules for porting UI code
 written with GTK+ and C to GtkBuilder + Glade.
 
 

devel-docs/tagging.txt

@@ -1,137 +1,137 @@
 =============================================================
-How resource tagging in Gimp works?
+How does resource tagging in Gimp work?
 =============================================================
 
 
 GimpTagged
 
 Tagging is not limited to a concrete class hierarchy, but any class
-implementing GimpTagged interface can be tagged. In addition to
+implementing the GimpTagged interface can be tagged. In addition to
 methods for adding/removing/enumerating tags it also requires
 GimpTagged objects to identify themselves:
 
-* gimp_tagged_get_identifier: used to get a unique identifier of
+* gimp_tagged_get_identifier: used to get a unique identifier of a
 GimpTagged object. For objects which are stored in a file it will
 usually be a filename.
 
-* gimp_tagged_get_checksum: identifier mentioned above has a problem
+* gimp_tagged_get_checksum: the identifier mentioned above has the problem
 that it can change during sessions (for example, user moves or renames
-a resource file). Therefore, there needs to be a way to get other
+a resource file). Therefore, there needs to be a way to get another
-identifier from data of the tagged object, so that tags stored between
+identifier from the data of the tagged object, so that tags stored between
-session could be properly remapped.
+session can be remapped properly.
 
 
 GimpTag
 
-Tags are represented by GimpTag object. There are no limitations for
+Tags are represented by a GimpTag object. There are no limitations for
-tags names except they cannot contain a selected set of terminal
+tag names except that they cannot contain a selected set of terminal
-punctuations characters (used to separate tags), no whitespace at the
+punctuation characters (used to separate tags), leading or trailing
-end or front and cannot begin with a reserved prefix for internal tags
+whitespace and cannot begin with a reserved prefix for internal tags
-('gimp:'). These conditions are ensured when creating tag object from
+('gimp:'). These conditions are enforced when creating a tag object from a
-tag string. The only reason for tag creation to fail is when there are
+tag string. The only reason for tag creation to fail is if there are
-no characters left after applying trying to fix a tag according to the
+no characters left after trying to fix a tag according to the
-rules above. Tag names are displayed as user typed them (case
+rules above. Tag names are displayed as the user typed them (case
-sensitive), but tag comparing is done case insensitively.
+sensitive), but tag comparison is done case-insensitively.
 
-Tags are immutable, ie. when tag is created with one name string, it
+Tags are immutable, i.e. when a tag is created with one name string, it
-cannot be changed, but new tag has to be created instead.
+cannot be changed, but a new tag has to be created instead.
 
-There are methods provided for convenient use with GLib: compare
+There are methods provided for convenient use with glib, a comparison
-function which can be used to sort tag list and functions for storing
+function which can be used to sort tag lists and functions for storing
-tags in GHashTable.
+tags in a GHashTable.
 
 
 GimpTagCache
 
-Between sessions tags assigned to objects are stored in a cache
+Between sessions, tags assigned to objects are stored in a cache
-file. Cache file is a simple XML file, which lists all resources and
+file. The cache file is a simple XML file, which lists all resources and
 tags which are added to them. Resources which have no tags assigned
 are listed here too, so that when we check the cache we know that they
-have no tags assigned instead trying to find out if the resource file
+have no tags assigned instead of trying to find out if the resource file
 has been renamed.
 
-When session ends, list or all resources and tags they have assigned
+When the session ends, a list of all resources and their tags
 is constructed. Resources which were not loaded during this session,
 but had tags assigned are also added to the list (they are saved
 because they could be useful in the next session, for example, when
-temporarily disconnected network directory is reconnected). The list
+a temporarily disconnected network directory is reconnected). The list
-is then written to a tag cache file in user home directory.
+is then written to a tag cache file in the user's home directory.
 
-When session starts, previously saved resource and tag mapping has to
+When the session starts, the previously saved resource and tag mapping has to
-be loaded and assigned to GimpTagged objects.  First tag cache is
+be loaded and assigned to GimpTagged objects. First the tag cache is
 loaded from file, and then containers are added (GimpContainer objects
-where contained items implement GimpTagged interface). After that,
+which contain items implementing the GimpTagged interface). After that,
 loaded resources are assigned tags:
 
-  If resource identifier matches identifier in cache,
+  If a resource identifier matches an identifier in the cache,
-    corresponding tags are assigned to GimpTagged object.
+    corresponding tags are assigned to the GimpTagged object.
-  Else, if the identifier is not found in tag cache,
+  Else, if the identifier is not found in the tag cache,
-    attempt is made to check if resource file has been
+    an attempt is made to check if the resource file has been
-    moved/renamed. In such case checksum is used to match the
+    moved/renamed. In such case the checksum is used to match the
-    GimpTagged object with all of the records in tag cache.
+    GimpTagged object with all of the records in the tag cache.
-    If match is found,
+    If a match is found,
-      identifier is updated in tag cache.
+      the identifier is updated in the tag cache.
     Otherwise,
-      loaded GimpTagged object is considered to be a newly
+      the loaded GimpTagged object is considered to be a newly
       added resource.
 
 
 GimpFilteredContainer
 
-GimpFilteredContainer is a "view" (representation) of
+A GimpFilteredContainer is a "view" (representation) of a
-GimpContainer. What relates it to tagging, is that it can be used to
+GimpContainer. It is related to tagging in that it can be used to
-filter GimpContainer to contain only GimpTagged objects which have
+filter a GimpContainer to contain only GimpTagged objects which have
 certain tags assigned. It is automatically updated with any changes in
-GimpContainer it wraps. However, items should not be added or removed
+the GimpContainer it wraps. However, items should not be added or removed
-from this container manually as changes do not affect original
+from this container manually as changes do not affect the original
-container and would be lost when GimpFilteredContainer is
+container and would be lost when the GimpFilteredContainer is
-updated. Instead, the contents should be changed by setting tag list
+updated. Instead, the contents should be changed by setting a tag list
 which would be used to filter GimpTagged objects containing all of the
 given GimpTags.
 
-GimpFilteredContainer can use any GimpContainer as source
+GimpFilteredContainer can use any GimpContainer as a source
-container. Therefore, it is possible to use decorator design pattern
+container. Therefore, it is possible to use the decorator design pattern
-to implement additional container views, such as view combining items
+to implement additional container views, such as a view combining items
 from multiple containers.
 
 
 GimpTagEntry widget
 
-GimpTagEntry widget extends GtkEntry and is used to either assign or
+The GimpTagEntry widget extends GtkEntry and is used to either assign or
-query tags depending on selected mode. The widget support various
+query tags depending on the selected mode. The widget support various
 usability features:
 
- * jellybeans. When tag is entered and confirmed by either separator,
+ * Jellybeans: When a tag is entered and confirmed by either separator,
    pressing return or otherwise, it becomes a jellybean, i.e. a single
-   unit, not a bunch of characters. Navigating in GimpTagEntry,
+   unit, not a bunch of characters. Navigating in a GimpTagEntry,
-   deleting tags, etc can be performed much quicker. However, when tag
+   deleting tags, etc. can be performed much faster. However, while a tag
    is just being entered (not yet confirmed), all actions operate on
    characters as usual.
 
- * custom auto completion is implemented in GimpTagEntry widget which
+ * Custom auto completion is implemented in the GimpTagEntry widget which
-   allows to complete tags in the middle of tag list, doesn't offer
+   allows to complete tags in the middle of a tag list, doesn't offer
    already completed tags, tab cycles all possible completions, etc.
 
- * when GimpTagEntry is empty and unused it displays description for
+ * If the GimpTagEntry is empty and unused it displays a description for
-   user regarding it's purpose.
+   the user regarding its purpose.
 
 When operating in tag assignment mode, tags are assigned only when
-user hits return key.
+the user hits the return key.
 
-When operating in tag query mode, given GimpFilteredContainer is
+When operating in tag query mode, the given GimpFilteredContainer is
-filtered as user types. GimpTagEntry also remembers recently used
+filtered as the user types. The GimpTagEntry also remembers recently used
 configurations, which can be cycled using up and down arrow keys.
 
 
 GimpComboTagEntry widget
 
-GimpComboTagEntry widget extends GimpTagEntry and adds ability to pick
+The GimpComboTagEntry widget extends GimpTagEntry and adds the ability to pick
-tags from a menu like list (GimpTagPopup widget).
+tags from a menu-like list (using the GimpTagPopup widget).
 
 
 GimpTagPopup widget
 
-GimpTagPopup widget is used as a tag list menu from GimpComboTagEntry
+The GimpTagPopup widget is used as a tag list menu from the GimpComboTagEntry
 widget. It is not designed to be used with any other widget.
 
 GimpTagPopup has many visual and behavioral similarities to GtkMenu.
@@ -139,10 +139,10 @@ In particular, it uses menu-like scrolling.
 
 GimpTagPopup implements various usability features, some of which are:
 
- * tags which would result in empty selection of resource are made
+ * Tags which would result in an empty selection of resources are made
    insensitive.
 
- * closing with either keyboard or pressing outside the popup area.
+ * Closing either with the keyboard or by clicking outside the popup area.
 
- * underline highlighted (hovered) tags.
+ * Underlining of highlighted (hovered) tags.