gh-35040: Document argument is_open in ManifoldSubset.complement and …

…difference

    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
### 📚 Document argument is_open of methods complement and difference in
ManifoldSubset

<!-- Describe your changes here in detail -->
<!-- Why is this change required? What problem does it solve? -->
<!-- If it resolves an open issue, please link to the issue here. For
example "Closes #1337" -->

The argument `is_open`  was not documented in the docstrings of
`ManifoldSubset.complement` and `ManifoldSubset.difference`

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->

- [x ] I have made sure that the title is self-explanatory and the
description concisely explains the PR.
- [ ] I have linked an issue or discussion.
- [ x] I have created tests covering the changes.
- [ x] I have updated the documentation accordingly.

### ⌛ Dependencies
<!-- List all open pull requests that this PR logically depends on -->
<!--
- #xyz: short description why this is a dependency
- #abc: ...
-->
    
URL: #35040
Reported by: Eric Gourgoulhon
Reviewer(s): Matthias Köppe, Tobias Diez

src/sage/manifolds/subset.py

@@ -2629,11 +2629,13 @@ def complement(self, superset=None, name=None, latex_name=None, is_open=False):
         - ``latex_name`` --  (default: ``None``) LaTeX symbol to denote the
           complement in the case the latter has to be created; the default
           is built upon the symbol `\setminus`
+        - ``is_open`` -- (default: ``False``) if ``True``, the created subset
+          is assumed to be open with respect to the manifold's topology
 
         OUTPUT:
 
-        - instance of :class:`ManifoldSubset` representing the
-          subset that is difference of ``superset`` minus ``self``
+        - instance of :class:`ManifoldSubset` representing the subset that
+          is ``superset`` minus ``self``
 
         EXAMPLES::
 
@@ -2650,6 +2652,15 @@ def complement(self, superset=None, name=None, latex_name=None, is_open=False):
             ...
             TypeError: superset must be a superset of self
 
+        Demanding that the complement is open makes ``self`` a closed subset::
+
+            sage: A.is_closed()  # False a priori
+            False
+            sage: A.complement(is_open=True)
+            Open subset M_minus_A of the 2-dimensional topological manifold M
+            sage: A.is_closed()
+            True
+
         """
         if superset is None:
             superset = self.manifold()
@@ -2672,11 +2683,13 @@ def difference(self, other, name=None, latex_name=None, is_open=False):
         - ``latex_name`` --  (default: ``None``) LaTeX symbol to denote the
           difference in the case the latter has to be created; the default
           is built upon the symbol `\setminus`
+        - ``is_open`` -- (default: ``False``) if ``True``, the created subset
+          is assumed to be open with respect to the manifold's topology
 
         OUTPUT:
 
-        - instance of :class:`ManifoldSubset` representing the
-          subset that is difference of ``self`` minus ``other``
+        - instance of :class:`ManifoldSubset` representing the subset that is
+          ``self`` minus ``other``
 
         EXAMPLES::
 
@@ -2706,6 +2719,13 @@ def difference(self, other, name=None, latex_name=None, is_open=False):
             sage: M.difference(O, is_open=True)
             Open subset CO2 of the 2-dimensional topological manifold M
 
+        Since `O` is open and we have asked `M\setminus O` to be open, `O`
+        is a clopen set (if `O\neq M` and `O\neq\emptyset`, this implies that
+        `M` is not connected)::
+
+            sage: O.is_closed() and O.is_open()
+            True
+
         """
         # See if it has been created already
         diffs = []