# HG changeset patch
# User Nathann Cohen
# Date 1337265592 7200
# Node ID 110a0124a616e025b926f2bb9d18cc8cd4127ad7
# Parent 4196c0242945b3e49ed356b1ad5c4749bffa24eb
#12961: Documentation of the facade argument in Poset constructor
diff git a/sage/combinat/posets/posets.py b/sage/combinat/posets/posets.py
 a/sage/combinat/posets/posets.py
+++ b/sage/combinat/posets/posets.py
@@ 1,6 +1,9 @@
# * coding: utf8 *
r"""
Posets
+
+This module implements finite partialy ordered sets. The main
+constructor is :meth:`Poset`.
"""
#*****************************************************************************
# Copyright (C) 2008 Peter Jipsen ,
@@ 38,40 +41,45 @@ from sage.combinat.posets.elements impor
def Poset(data=None, element_labels=None, cover_relations=False, linear_extension=False, category = None, facade = None, key = None):
r"""
 Construct a poset from various forms of input data.
+ Construct a finite poset from various forms of input data.
INPUT:
 1. A twoelement list or tuple (E, R), where E is a collection of
 elements of the poset and R is the set of relations. Elements
 of R are twoelement lists/tuples/iterables. If
 cover_relations=True, then R is assumed to be the cover
 relations of the poset. If E is empty, then E is taken to be
 the set of elements appearing in the relations R.

 2. A twoelement list or tuple (E, f), where E is the set of
 elements of the poset and f is a function such that f(x,y) is
 True if x <= y and False otherwise for all pairs of elements in
 E. If cover_relations=True, then f(x,y) should be True if and
 only if x is covered by y, and False otherwise.

 3. A dictionary, list or tuple of upper covers: data[x] is an
 list of the elements that cover the element x in the poset.

 .. note::

 If data is a list or tuple of length 2, then it is handled
 by the above cases.

 4. An acyclic, loopfree and multiedge free DiGraph. If
 cover_relations is True, then the edges of the digraph
 correspond to cover relations in the poset. If cover_relations
 is False, then the cover relations are computed.

 5. A previously constructed poset (the poset itself is returned).


  ``element_labels``  (default: None) an optional list or
+  ``data``  different input are accepted by this constructor:
+
+ 1. A twoelement list or tuple `(E, R)`, where `E` is a
+ collection of elements of the poset and `R` is a collection
+ of relations `x<=y`, each represented as a twoelement
+ lists/tuples/iterables such as [x,y]. The poset is then the
+ transitive closure of the provided relations. If
+ ``cover_relations=True``, then `R` is assumed to contain
+ exactly the cover relations of the poset. If `E` is empty,
+ then `E` is taken to be the set of elements appearing in
+ the relations `R`.
+
+ 2. A twoelement list or tuple `(E, f)`, where `E` is the set
+ of elements of the poset and `f` is a function such that,
+ for any pair `x,y` of elements of `E`, `f(x,y)` returns
+ whether `x <= y`. If ``cover_relations=True``, then
+ `f(x,y)` should return whether `x` is covered by `y`.
+
+ 3. A dictionary, list or tuple of upper covers: ``data[x]`` is
+ a list of the elements that cover the element `x` in the
+ poset.
+
+ .. WARNING::
+
+ If data is a list or tuple of length `2`, then it is
+ handled by the above case..
+
+ 4. An acyclic, loopfree and multiedge free ``DiGraph``. If
+ ``cover_relations`` is ``True``, then the edges of the
+ digraph are assumed to correspond to the cover relations of
+ the poset. Otherwise, the cover relations are computed.
+
+ 5. A previously constructed poset (the poset itself is returned).
+
+  ``element_labels``  (default: None); an optional list or
dictionary of objects that label the poset elements.
 ``cover_relations``  a boolean (default: False); whether the
@@ 83,9 +91,13 @@ def Poset(data=None, element_labels=None
use the provided list of elements as default linear extension
for the poset; otherwise a linear extension is computed.
+  ``facade``  a boolean (default: False); whether the Poset's
+ elements should be wrapped to make them aware of the Poset they
+ belong to. See below for details.
+
OUTPUT:
 FinitePoset  an instance of the FinitePoset class.
+ ``FinitePoset``  an instance of the ``FinitePoset`` class.
If ``category`` is specified, then the poset is created in this
category instead of :class:`FinitePosets`.
@@ 223,7 +235,23 @@ def Poset(data=None, element_labels=None
sage: c < a
True
 As an experimental feature, one can construct instead facade posets::
+ However, this may have surprising effects::
+
+ sage: my_elements = ['a','b','c','d']
+ sage: any(x in my_elements for x in P)
+ False
+
+ and can be anoying when one wants to manipulate the elements of
+ the poset::
+
+ sage: a + b
+ Traceback (most recent call last):
+ ...
+ TypeError: unsupported operand type(s) for +: 'FinitePoset_with_category.element_class' and 'FinitePoset_with_category.element_class'
+ sage: a.element + b.element
+ 'ac'
+
+ Alternatively, one can construct instead facade posets::
sage: P = Poset(DiGraph({'d':['c','b'],'c':['a'],'b':['a']}),
... facade = True)
@@ 321,7 +349,22 @@ def Poset(data=None, element_labels=None
sage: P = Poset([[1,2],[3],[3]])
sage: type(hash(P))
+
+ Bad input::
+
+ sage: Poset([1,2,3], lambda x,y : x