Opened 6 years ago

Closed 6 years ago

#17073 closed enhancement (fixed)

Documentation for Facade Sets

Reported by: ncohen Owned by:
Priority: major Milestone: sage-6.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 nthiery

  • Branch set to u/nthiery/documentation_for_facade_sets

comment:2 Changed 6 years ago by nthiery

  • Branch u/nthiery/documentation_for_facade_sets deleted

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,

Nicolas

comment:3 Changed 6 years ago by tscrim

  • Branch set to u/nthiery/documentation_for_facade_sets
  • Commit set to 9db774dfe9b360a225680f3cb2f2a59c51cef4e5

(to also cc myself)


New commits:

9db774d17073: added link to Sets.SubcategoryMethods.Facade

comment:4 Changed 6 years ago by ncohen

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 jmantysalo

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 git

  • Commit changed from 9db774dfe9b360a225680f3cb2f2a59c51cef4e5 to fd456bcd98f33a28f37a7dfd243d21fd89345b4d

Branch pushed to git repo; I updated commit sha1. New commits:

fd456bc17073: more progressive introduction to facade sets and improved cross links; also deprecated Sets.Facades

comment:7 follow-up: Changed 6 years ago by jmantysalo

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 non-facade 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.

Authors-field should be filled.

comment:8 Changed 6 years ago by nthiery

  • Authors set to Nicolas M. Thiéry

comment:9 Changed 6 years ago by git

  • Commit changed from fd456bcd98f33a28f37a7dfd243d21fd89345b4d to 326da075daeeb625bb56adfe55ed03e47ecddf40

Branch pushed to git repo; I updated commit sha1. New commits:

326da0717073: added example comparing explicitly the facade and non facade situations

comment:10 in reply to: ↑ 7 ; follow-up: Changed 6 years ago by nthiery

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 non-facade 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!

Authors-field should be filled.

Done!

Thanks for the review,

Nicolas


New commits:

326da0717073: added example comparing explicitly the facade and non facade situations

comment:11 Changed 6 years ago by nthiery

  • Status changed from new to needs_review

comment:12 Changed 6 years ago by git

  • Commit changed from 326da075daeeb625bb56adfe55ed03e47ecddf40 to 085747762d62e95b29bde051fa87f9c845bf5a5a

Branch pushed to git repo; I updated commit sha1. New commits:

085747717073: suggestion to look at the code of the examples

comment:13 in reply to: ↑ 10 ; follow-up: Changed 6 years ago by jmantysalo

  • 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 vbraun

  • Status changed from positive_review to needs_work

Various doctest failures of the form

sage -t --long --warn-long 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 git

  • Commit changed from 085747762d62e95b29bde051fa87f9c845bf5a5a to e7445946ab0fd81992eddf2579a5f3d42c875ac4

Branch pushed to git repo; I updated commit sha1. New commits:

473989cMerge branch 'develop = 6.4 beta6' into t/17073/documentation_for_facade_sets
e74459417073: Fixed old Sets.Facades to Sets.Facade

comment:16 Changed 6 years ago by nthiery

  • Status changed from needs_work to needs_review

Oops, sorry. Fixed! Trivial enough that I set it back to positive review.

New commits:

473989cMerge branch 'develop = 6.4 beta6' into t/17073/documentation_for_facade_sets
e74459417073: Fixed old Sets.Facades to Sets.Facade

New commits:

473989cMerge branch 'develop = 6.4 beta6' into t/17073/documentation_for_facade_sets
e74459417073: Fixed old Sets.Facades to Sets.Facade

comment:17 Changed 6 years ago by nthiery

  • Status changed from needs_review to positive_review

comment:18 in reply to: ↑ 13 Changed 6 years ago by nthiery

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 vbraun

  • Branch changed from u/nthiery/documentation_for_facade_sets to e7445946ab0fd81992eddf2579a5f3d42c875ac4
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.