[gimp-help/gimp-help-2-10] concepts: revise and update plugins.xml

[Jacob Boerema <jboerema src gnome org>]

commit d1a11d24ef6d222ae08ec896cb8b7884ae87d336
Author: Jacob Boerema <jgboerema gmail com>
Date:   Sun Jul 10 14:04:52 2022 -0400

    concepts: revise and update plugins.xml
    
    This also fixes issue #339 by updating paths and version numbers, and
    not mentioning Xtns anymore.
    
    The parts about Mac and Linux may need more adjusting.
    
    (cherry picked from commit 51b3d2708bf9e4d18a39734c39c0a1ce6d429270)

 src/concepts/plugins.xml | 236 +++++++++++++++++++----------------------------
 1 file changed, 97 insertions(+), 139 deletions(-)
---
diff --git a/src/concepts/plugins.xml b/src/concepts/plugins.xml
index 92568c03e..dfb852689 100644
--- a/src/concepts/plugins.xml
+++ b/src/concepts/plugins.xml
@@ -37,64 +37,48 @@
       use one without ever realizing that it is a plugin: for example, the
       "Normalize" function for automatic color correction is actually a
       plugin, although there is nothing about the way it works that would tell
-      you this.
+      you this. Even importing and exporting of images is done by plugins.
     </para>
-    <!--
     <para>
-      In addition to the plugins included with <acronym>GIMP</acronym> , many
-      more are available on the net. A large number can be found at the
-      <acronym>GIMP</acronym> Plugin Registry
-      <xref linkend="bibliography-online-gimp-plugin-registry"/>,
-      a web site whose purpose is to provide a central repository for
-      plugins. Creators of plugins can upload them there; users in search of
-      plugins for a specific purpose can search the site in a variety of ways.
-    </para>-->
+      Everyone can write a <acronym>GIMP</acronym> plugin and make it available
+      online. There are many useful plugins that can be obtained this way. Some
+      of them are described elsewhere in the User's Manual.
+    </para>
     <para>
-      Anybody in the world can write a <acronym>GIMP</acronym> plugin and make
-      it available over the web, either via the Registry or a personal web
-      site, and many very valuable plugins can be obtained in this way ­ some
-      are described elsewhere in the User's Manual. With this freedom from
-      constraint comes a certain degree of risk, though: the fact that anybody
-      can do it means that there is no effective quality control. The plugins
-      distributed with <acronym>GIMP</acronym> have all been tested and tuned
-      by the developers, but many that you can download were just hacked
-      together in a few hours and then tossed to the winds. Some plugin
-      creators just don't care about robustness, and even for those who do,
-      their ability to test on a variety of systems in a variety of situations
-      is often quite limited. Basically, when you download a plugin, you are
-      getting something for free, and sometimes you get exactly what you pay
-      for. This is not said in an attempt to discourage you, just to make sure
-      you understand reality.
+      With this free availability comes a certain degree of risk. The fact that
+      anyone can release plugins means that there is no effective quality
+      control. The plugins distributed with <acronym>GIMP</acronym> have all
+      been tested and tuned by the developers. Additional plugins available
+      online, may have been hacked together in a few hours and then
+      abandoned. Some plugin creators don't care about robustness, and even for
+      those who do, their ability to test on a variety of systems in a variety
+      of situations is often quite limited. Basically, when you download a
+      plugin, you are getting something for free, and sometimes you get exactly
+      what you pay for. This is not to discourage you, just to make sure you
+      understand that not all plugins available online will deliver what you
+      expect from them.
     </para>
     <warning>
       <para>
-        Plugins, being full-fledged executable programs, can do any of the
-        things that any other program can do, including install back-doors on
-        your system or otherwise compromise its security. Don't install a
-        plugin unless it comes from a trusted source.
+        Plugins, being full-fledged executable programs, can do all of the
+        things that any other program can do. This includes installing
+        back-doors on your system or otherwise compromise its security. Don't
+        install a plugin unless it comes from a trusted source.
       </para>
     </warning>
-    <!--
-    <para>
-      These caveats apply as much to the Plugin Registry as to any other
-      source of plugins. The Registry is available to any plugin creator who
-      wants to use it:  there is no systematic oversight. Obviously if the
-      maintainers became aware that something evil was there, they would
-      remove it. (That hasn't happened yet.)  There is, however, for
-      <acronym>GIMP</acronym> and its plugins the same warranty as for any
-      other free software: namely, none.
-    </para>-->
-    <caution>
+    <note>
       <para>
-        Plugins have been a feature of <acronym>GIMP</acronym> for many
-        versions. However, plugins written for one version of
-        <acronym>GIMP</acronym> can hardly ever be used successfully with
-        other versions. They need to be ported: sometimes this is easy,
-        sometimes not. Many plugins are already available in several
-        versions. Bottom line: before trying to install a plugin, make sure
-        that it is written for your version of <acronym>GIMP</acronym>.
+        Plugins written for a certain version of <acronym>GIMP</acronym> may not
+        always work well in other versions. Though in general the
+        <acronym>GIMP</acronym> team tries to minimize changes that affect
+        plugins. Usually the only time you can expect serious problems with
+        plugins, is when the major version of GIMP changes.
+        When a plugin made for an older version doesn't work correctly
+        anymore, it needs to be ported. Sometimes this is easy, sometimes not.
+        Bottom line: before trying to install a plugin, make sure
+        that it is compatible with your version of <acronym>GIMP</acronym>.
       </para>
-    </caution>
+    </note>
   </sect2>
 
   <sect2>
@@ -110,17 +94,16 @@
       <acronym>GIMP</acronym> core. When <acronym>GIMP</acronym> crashes, it
       is considered a very serious thing: it can cost the user a lot of
       trouble and headache. When a plugin crashes, the consequences are
-      usually not so serious.  In most cases you can just continuing working
-      without worrying about it.
+      usually not as serious. In most cases you can continue working
+      without worrying about it too much.
     </para>
     <note>
       <para>
-        Because plugins are separate programs, they communicate with the
-        <acronym>GIMP</acronym> core in a special way: The
-        <acronym>GIMP</acronym> developers call it <quote>talking over a
-          wire</quote>. When a plugin crashes, the communication breaks down,
-        and you will see an error message about a <quote>wire read
-          error</quote>.
+        Because plugins are separate programs, they communicate with
+        <acronym>GIMP</acronym> in a special way: The <acronym>GIMP</acronym>
+        developers call it <quote>talking over a wire</quote>. When a plugin
+        crashes, the communication breaks down, and you may see an error
+        message about a <quote>wire read error</quote>.
       </para>
     </note>
     <tip>
@@ -141,13 +124,13 @@
       Because of the way plugins communicate with <acronym>GIMP</acronym>,
       they do not have any mechanism for being informed about changes you make
       to an image after the plugin has been started. If you start a plugin,
-      and then alter the image using some other tool, the plugin will often
-      crash, and when it doesn't will usually give a bogus result. You should
+      and then alter the image using some other tool, the plugin may crash.
+      Even if it doesn't, doing this may cause incorrect results. You should
       avoid running more than one plugin at a time on an image, and avoid
       doing anything to the image until the plugin has finished working on it.
-      If you ignore this advice, not only will you probably screw up the
-      image, you will probably screw up the undo system as well, so that you
-      won't even be able to recover from your foolishness.
+      If you ignore this advice, not only could you screw up the image, you
+      may also screw up the undo system, so that you won't be able to recover
+      from your mistake.
     </para>
   </sect2>
 
@@ -159,11 +142,16 @@
     </indexterm>
     <para>
       The plugins that are distributed with <acronym>GIMP</acronym> don't
-      require any special installation. Plugins that you download yourself do.
+      require installation. Plugins that you download yourself do.
+      Usually the default location is in <acronym>GIMP</acronym>'s user
+      directory in a folder under <filename>/plug-ins</filename>, where the
+      folder name needs to be the same as the plugin filename.
+      You can find the default locations where <acronym>GIMP</acronym> searches
+      for plugins in <acronym>GIMP</acronym>'s folder preferences. There you
+      can also add new locations where <acronym>GIMP</acronym> should look
+      for plug-ins.
       There are several scenarios, depending on what OS you are using and how
-      the plugin is structured. In Linux it is usually pretty easy to install
-      a new plugin; in Windows, it is either easy or very hard. In any case,
-      the two are best considered separately.
+      the plugin is structured.
     </para>
     <sect3>
       <title>Linux / Unix-like systems</title>
@@ -176,84 +164,31 @@
       <para>
         For a simple one-file plugin, call it <filename>borker.c</filename>,
         installing it is just a matter of running the command
-        <command>gimptool-2.0 --install borker.c</command>.   This command
+        <command>gimptool-2.0 --install borker.c</command>. This command
         compiles the plugin and installs it in your personal plugin directory,
-        <filename>~/gimp-2.4/plugins</filename> unless you have changed it.
+        <filename>~/gimp-2.10/plug-ins</filename> unless you have changed it.
         This will cause it to be loaded automatically the next time you start
         <acronym>GIMP</acronym>. You don't need to be root to do these things;
         in fact, you shouldn't be. If the plugin fails to compile, well, be
         creative.
       </para>
-      <para><!-- changed 11-10-2004 -->
-        Once you have installed the plugin, how do you activate it? The menu
-        path is determined by the plugin itself, so to answer this you need to
-        either look at the documentation for the plugin (if there is any), or
-        launch the Plugin Description dialog (from Xtns/Plugins Details)
-        search the plug-in by its name and look of the
-        <guilabel>Tree view</guilabel>
-        tab. If you still don't find, finally explore the menus or look at the
-        source code in the Register section -- whichever is easiest.
-      </para>
-      <para>
-        For more complex plugins, organized as a directory with multiple
-        files, there ought to be a file inside called either
-        <filename>INSTALL</filename> or <filename>README</filename>, with
-        instructions. If not, the best advice is to toss the plugin in the
-        trash and spend your time on something else:  any code written with so
-        little concern for the user is likely to be frustrating in myriad
-        ways.
-      </para>
-      <para>
-        Some plugins (specifically those based on the <acronym>GIMP</acronym>
-        Plugin Template) are designed to be installed in the main system
-        <acronym>GIMP</acronym> directory, rather than your home directory.
-        For these, you will need to be root to perform the final stage of
-        installation (when issuing the <command>make install</command>
-        command).
-      </para>
-      <para>
-        If you install in your personal plugin directory a plugin that has the
-        same name as one in the system plugin directory, only one can be
-        loaded, and it will be the one in your home directory. You will
-        receive messages telling you this each time you start
-        <acronym>GIMP</acronym>. This is probably a situation best avoided.
-      </para>
     </sect3>
 
     <sect3>
       <title>Windows</title>
       <para>
-        Windows is a much more problematic environment for building software
-        than Linux. Every decent Linux distribution comes fully supplied with
-        tools for compiling software, and they are all very similar in the way
-        they work, but Windows does not come with such tools. It is possible
-        to set up a good software-building environment in Windows, but it
-        requires either a substantial amount of money or a substantial amount
-        of effort and knowledge.
-      </para>
-      <para>
-        What this means in relation to <acronym>GIMP</acronym> plugins is the
-        following: either you have an environment in which you can build
-        software, or you don't. If you don't, then your best hope is to find a
-        precompiled version of the plugin somewhere (or persuade somebody to
-        compile it for you), in which case you simply need to put it into your
-        personal plugin directory. If you do have an environment in which you
-        can build software (which for present purposes means an environment in
-        which you can build <acronym>GIMP</acronym>), then you no doubt
-        already know quite a bit about these things, and just need to follow
-        the Linux instructions.
+        Most <acronym>GIMP</acronym> plugins available on Windows supply either
+        an installer, or can be downloaded in a pre-compiled binary format
+        ready to copy to a folder of your choice that is recognized by
+        <acronym>GIMP</acronym>.
       </para>
-      <!--
       <para>
-        If you would like to set up a build environment, and are ready for the
-        heroism involved, you can find a reasonably recent description of how
-        to go about it in the <acronym>GIMP</acronym> Wiki, at
-        HowToCompileGimp/MicrosoftWindows
-        <xref linkend="bibliography-online-gimp-wiki-compile-windows"/>.
-        Since it is a Wiki, anybody is free to edit it, so please keep it up
-        to date by adding advice based on your own experiences.
+        If an installer is available, that should do all the work for you
+        selecting an appropriate folder and copying all relevant files.
+        If not, you may have to check in <acronym>GIMP</acronym>'s folder
+        preferences where the plugins should be copied to. Remember, each
+        plugin needs to be in its own folder with the same name as the plugin.
       </para>
-      -->
     </sect3>
 
     <sect3>
@@ -271,16 +206,39 @@
         manager, so give it a try.
       </para>
       <para>
-        If you on the other hand are one of the Users that preferred to grab a
-        prebuild <acronym>GIMP</acronym> package like GIMP.app, you most
-        probably want to stick
-        to that prebuild stuff. So you can try to get a prebuild version of
-        the plugin of you dreams from the author of the plugin, but I'd not
-        want to bet on this. Building your own binaries unfortunately involves
-        installing <acronym>GIMP</acronym> through one of the package managers
-        mentioned above.
+        If, on the other hand, you prefer to grab a prebuilt
+        <acronym>GIMP</acronym> package like GIMP.app, you most likely want to
+        a prebuilt plugin too. You can try to get a prebuilt version of
+        the plugin of your dreams from the author of the plugin. Building your
+        own binaries unfortunately involves installing <acronym>GIMP</acronym>.
       </para>
     </sect3>
+
+    <para>
+      Once you have installed the plugin, how do you activate it? The menu
+      path is determined by the plugin itself, so to answer this you need to
+      either look at the documentation for the plugin (if there is any),
+      explore the menus, or use <acronym>GIMP</acronym>'s command search
+      function by pressing <keycap>/</keycap> and then entering the name of the
+      plugin. If you know how to read source code you could also check that to
+      see in what menu it registers itself.
+    </para>
+    <para>
+      For more complex plugins, organized as a directory with multiple
+      files, there usually is a file inside called either
+      <filename>INSTALL</filename> or <filename>README</filename>, with
+      instructions. If not, the best advice is to toss the plugin in the
+      trash and spend your time on something else: any code written with so
+      little concern for the user is likely to be frustrating in myriad
+      ways.
+    </para>
+    <para>
+      If you install a plugin in your personal plugin directory that has the
+      same name as one in the system plugin directory, only one can be
+      loaded, and it will be the one in your home directory. You will
+      receive messages telling you this each time you start
+      <acronym>GIMP</acronym>. This is probably a situation best avoided.
+    </para>
   </sect2>
 
   <sect2 id="plugins-write">
@@ -295,10 +253,10 @@
       <xref linkend="bibliography-online-gimp-dev-plugin"/>.
       <acronym>GIMP</acronym> is a complex
       program, but the development team has made strenuous efforts to flatten
-      the learning curve for plugin writing:  there are good instructions and
+      the learning curve for plugin writing: there are good instructions and
       examples, and the main library that plugins use to interface with
       <acronym>GIMP</acronym> (called <quote>libgimp</quote>) has a
-      well-documented <acronym>API</acronym>.  Good programmers, learning by
+      well-documented <acronym>API</acronym>. Good programmers, learning by
       modifying existing plugins, are often able to accomplish interesting
       things after just a couple of days of work.
     </para>