Opened 6 years ago
Closed 6 years ago
#17073 closed enhancement (fixed)
Documentation for Facade Sets
Reported by:  ncohen  Owned by:  

Priority:  major  Milestone:  sage6.4 
Component:  categories  Keywords:  
Cc:  nthiery, jmantysalo  Merged in:  
Authors:  Nicolas M. Thiéry  Reviewers:  Jori Mäntysalo 
Report Upstream:  N/A  Work issues:  
Branch:  e744594 (Commits)  Commit:  e7445946ab0fd81992eddf2579a5f3d42c875ac4 
Dependencies:  Stopgaps: 
Description
Nicolas,
I documented two Poset
functions in #17051 which have a facade
boolean argument (the same that Poset()
has) and added a link toward the Facade
module. The problem is that there is no documentation there to find, and it would help if you could write something to say to the new users what they need to know about Facade
in such situations.
This page is also the page that appears first when you type "sage facade" in google.
Thanks.
Nathann
Change History (19)
comment:1 Changed 6 years ago by
 Branch set to u/nthiery/documentation_for_facade_sets
comment:2 Changed 6 years ago by
 Branch u/nthiery/documentation_for_facade_sets deleted
comment:3 Changed 6 years ago by
 Branch set to u/nthiery/documentation_for_facade_sets
 Commit set to 9db774dfe9b360a225680f3cb2f2a59c51cef4e5
comment:4 Changed 6 years ago by
Hello Nicolas,
I was thinking of users who do not know what a facade/category is and find this keyword in a constructor like !Posets. The documentation of the category is not something that will answer their questions: could you write a couple of lines somewhere meant for users who just want to find out if they need to change that flag or not ?
Something like: here are two sets, one is a Facade and the other is not: notice how the type of their elements has changed, and here is how to get the original value of an element from its wrapped counterpart ?
Nathann
comment:5 Changed 6 years ago by
Nathann is right from user perspective. Normal user is interested in doing something with, say, posets, and not learning Sage. Hence user should be able to found information just enought to be able to do what he wants. And copying same information is of course stupid.
comment:6 Changed 6 years ago by
 Commit changed from 9db774dfe9b360a225680f3cb2f2a59c51cef4e5 to fd456bcd98f33a28f37a7dfd243d21fd89345b4d
Branch pushed to git repo; I updated commit sha1. New commits:
fd456bc  17073: more progressive introduction to facade sets and improved cross links; also deprecated Sets.Facades

comment:7 followup: ↓ 10 Changed 6 years ago by
I understand everything until the end. There is an example with P(2) < P(3)
. However, this is just the part where difference between facade and nonfacade sets could be shown. For example we define poset where 2<1:
P=Poset({2:[1]}, facade=False) Q=Poset({2:[1]}, facade=True) print 2 < 1 print P(2) < P(1) print Q(2) < Q(1) # Maybe also P.unwrap(P(2)) < P.unwrap(P(1)) here?
It is unnecessary to know that MuPAD was first system with facade sets.
Authorsfield should be filled.
comment:8 Changed 6 years ago by
comment:9 Changed 6 years ago by
 Commit changed from fd456bcd98f33a28f37a7dfd243d21fd89345b4d to 326da075daeeb625bb56adfe55ed03e47ecddf40
Branch pushed to git repo; I updated commit sha1. New commits:
326da07  17073: added example comparing explicitly the facade and non facade situations

comment:10 in reply to: ↑ 7 ; followup: ↓ 13 Changed 6 years ago by
Replying to jmantysalo:
I understand everything until the end.
That's good news :)
There is an example with
P(2) < P(3)
. However, this is just the part where difference between facade and nonfacade sets could be shown.
Ok, good idea. I just used a slightly different example, mathematically natural, and that is in line with the previous one.
# Maybe also P.unwrap(P(2)) < P.unwrap(P(1)) here?
I left that out: this would certainly make sense in a specific documentation about facade posets, but not here: so far only posets follow that convention.
It is unnecessary to know that MuPAD was first system with facade sets.
On the contrary, when we reuse concepts introduced by other systems, we should give appropriate credit!
Authorsfield should be filled.
Done!
Thanks for the review,
Nicolas
New commits:
326da07  17073: added example comparing explicitly the facade and non facade situations

comment:11 Changed 6 years ago by
 Status changed from new to needs_review
comment:12 Changed 6 years ago by
 Commit changed from 326da075daeeb625bb56adfe55ed03e47ecddf40 to 085747762d62e95b29bde051fa87f9c845bf5a5a
Branch pushed to git repo; I updated commit sha1. New commits:
0857477  17073: suggestion to look at the code of the examples

comment:13 in reply to: ↑ 10 ; followup: ↓ 18 Changed 6 years ago by
 Reviewers set to Jori Mäntysalo
 Status changed from needs_review to positive_review
Replying to nthiery:
It is unnecessary to know that MuPAD was first system with facade sets.
On the contrary, when we reuse concepts introduced by other systems, we should give appropriate credit!
But I want my users to just eat cheese, not to know the name of the cow producing milk. :=)
Anyways, now this seems be good, so changed to positive review.
comment:14 Changed 6 years ago by
 Status changed from positive_review to needs_work
Various doctest failures of the form
sage t long warnlong 120.7 src/sage/misc/c3_controlled.pyx ********************************************************************** File "src/sage/misc/c3_controlled.pyx", line 205, in sage.misc.c3_controlled Failed example: x = HierarchyElement(10, P) Expected nothing Got: doctest:1: DeprecationWarning: Facades is deprecated. Please use Facade instead. See http://trac.sagemath.org/17073 for details.
comment:15 Changed 6 years ago by
 Commit changed from 085747762d62e95b29bde051fa87f9c845bf5a5a to e7445946ab0fd81992eddf2579a5f3d42c875ac4
comment:16 Changed 6 years ago by
 Status changed from needs_work to needs_review
Oops, sorry. Fixed! Trivial enough that I set it back to positive review.
New commits:
473989c  Merge branch 'develop = 6.4 beta6' into t/17073/documentation_for_facade_sets

e744594  17073: Fixed old Sets.Facades to Sets.Facade

New commits:
473989c  Merge branch 'develop = 6.4 beta6' into t/17073/documentation_for_facade_sets

e744594  17073: Fixed old Sets.Facades to Sets.Facade

comment:17 Changed 6 years ago by
 Status changed from needs_review to positive_review
comment:18 in reply to: ↑ 13 Changed 6 years ago by
Replying to jmantysalo:
But I want my users to just eat cheese, not to know the name of the cow producing milk. :=)
Here it's about who invented the cheese recipe! Sage is to follow the scientific tradition of giving credit when reusing others ideas, even if in most cases, like for papers, the user/reader does not immediately care.
Anyways, now this seems be good, so changed to positive review.
Thanks!
Cheers,
Nicolas
comment:19 Changed 6 years ago by
 Branch changed from u/nthiery/documentation_for_facade_sets to e7445946ab0fd81992eddf2579a5f3d42c875ac4
 Resolution set to fixed
 Status changed from positive_review to closed
Good point: the introductory documentation is located in a natural spot to find it by introspection; but it's hard to guess this spot if you look for it from the reference manual. I added a crosslink; does this do the job?
Thanks for pointing this out.
Cheers,