nixos/xdg.portal: deprecate gtkUsePortal option

It was never meant to be used for anything other than testing
and setting it globally can cause weird loops in GTK-based portals,
where the portal will end up waiting for itself until it times out.

#135898

Or it can mess up fonts:

#155291 (comment)

Having the option in NixOS makes it look like it is okay or even
desirable to enable, when in fact it is a hack that can subtly break apps.

Some apps allow opting into using portal-based APIs, e.g. for Firefox,
you can set `widget.use-xdg-desktop-portal.file-picker` to `1` in about:config.
Otherwise, you can set the `GTK_USE_PORTAL` environment variable to 1
for individual apps.

People who really want it and aware of the downsides can just set
`environment.sessionVariables.GTK_USE_PORTAL = "1";` NixOS option
directly to set the environment variable globally.

nixos/modules/config/xdg/portal.nix

@@ -13,6 +13,18 @@ in
 {
   imports = [
     (mkRenamedOptionModule [ "services" "flatpak" "extraPortals" ] [ "xdg" "portal" "extraPortals" ])
+
+    ({ config, lib, options, ... }:
+      let
+        from = [ "xdg" "portal" "gtkUsePortal" ];
+        fromOpt = lib.getAttrFromPath from options;
+      in
+      {
+        warnings = lib.mkIf config.xdg.portal.gtkUsePortal [
+          "The option `${lib.showOption from}' defined in ${lib.showFiles fromOpt.files} has been deprecated. Setting the variable globally with `environment.sessionVariables' NixOS option can have unforseen side-effects."
+        ];
+      }
+    )
   ];
 
   meta = {
@@ -40,11 +52,12 @@ in
 
     gtkUsePortal = mkOption {
       type = types.bool;
+      visible = false;
       default = false;
       description = ''
         Sets environment variable <literal>GTK_USE_PORTAL</literal> to <literal>1</literal>.
-        This is needed for packages ran outside Flatpak to respect and use XDG Desktop Portals.
-        For example, you'd need to set this for non-flatpak Firefox to use native filechoosers.
+        This will force GTK-based programs ran outside Flatpak to respect and use XDG Desktop Portals
+        for features like file chooser but it is an unsupported hack that can easily break things.
         Defaults to <literal>false</literal> to respect its opt-in nature.
       '';
     };