RFE: please list the subsets for Real #2315
Comments
|
You can click on stand-alone image to get it full size. Still,
All those numbers you mention are non-Complex, so they are included. It's a more precise and compact description. They are not "subsets". All those classes mix in or do that particular role. Type graphs are always on the bottom of the page, so that they don't get in the way of the actual documentation. As indicated, they can be accessed in full size just by clicking on the link. It's rendered in vector graphics, so I can't really see how it can be blurry; it does not get more crisp than vector graphics. |
|
On 9/16/18 10:38 PM, Juan Julián Merelo Guervós wrote:
You can click on stand-alone image
<https://docs.perl6.org/images/type-graph-Real.svg> to get it full size.
Still, |Real| says:
Common role for non-Complex numbers.
All those numbers you mention are non-Complex, so they are included.
It's a more precise and compact description. They are not "subsets". All
those classes /mix in/ or /do/ that particular role.
Type graphs are always on the bottom of the page, so that they don't get
in the way of the actual documentation. As indicated, they can be
accessed in full size just by clicking on the link. It's rendered in
vector graphics, so I can't really see how it can be blurry; it does not
get more crisp than vector graphics.
So I'm afraid I'm also closing this one.
Hi Juan,
I think you misunderstood my purpose. I was
not trying to correct an error.
I do complain a lot about the Doc being miserable for
beginners and common users. They are a vast step backwards
from Perldocs. They are written for those with developer
level skills and not us riff-raff.
So, instead of just complaining, I was trying to help
the situation.
Okay, I am using the terms "superset" and "subset" from the
mathematical world, not the Perl world. Of course you
should clean up the wording so it is official Perl-eess.
This is what I find difficult with the page. I came
there from
https://docs.perl6.org/type.html
I was trying to find out what classes belonged to "Real". What
I got was a lesson on what Real's specifications were.
I had to go down several pages to get to a blurry image
that told me what the members were. When I clicked on one
of the members, I got another page as complicated as the
one I was on. It was like reading an IRS publication.
And next to completely useless to a beginner.
What I would like to see is for you to start simple (like
perldocs) and then work up to the developer level
complicated stuff.
So, at the top, I wanted you to start simple. Below
that I am fine with you getting developer level complicated.
The docs need to accommodate both. (Actually, the developers
have their own specifications.)
Please reconsider reopening.
-T
|
|
@JJ If you open javadoc for Number, you're immediately presented with:
So the idea of wanting to see subclasses without having to scroll is not that unusual. I don't know if we want to do the same in perl6 docs, but the ticket by itself is a valid request that should be considered. |
|
I don't know who does javadoc for Number. I don't know what principles they follow, or if they have a quite clear type graph, which not only lists known subclasses, but known siblings and known superclasses and all kinds of things. I wasn't here when it was decided, but someone Who Knows decided that, instead of listing every single known subclass, by hand, we were going to do something which is infinitely better, automatically maintained and not prone to error: generate a Type Graph. The Type Graph has all that information and, as said above, then some. |
|
On 9/17/18 5:11 AM, Juan Julián Merelo Guervós wrote:
I don't know who does javadoc for Number. I don't know what principles
they follow, or if they have a quite clear type graph, which not only
lists known subclasses, but known siblings and known superclasses and
all kinds of things. I wasn't here when it was decided, but someone Who
Knows decided that, instead of listing every single known subclass, by
hand, we were going to do something which is infinitely better,
automatically maintained and not prone to error: generate a Type Graph.
The Type Graph has all that information and, as said above, then some.
So no, we don't want to do the same in Perl 6 docs which is why I closed
the ticket. And this is what I'm doing again.
If you want to open another different ticket saying "Repeat in every
Role all the known classes that mix it in, or include in every class all
known classes that subclass it" please do so by all means. That's
another reason why this ticket is closed. If we are going to do that, we
should do it, for simple coherency, for all classes and roles, and of
course do it automatically.
Hi Juan,
Then how about moving that graph to the top of the page?
There is no reason why you should have to trudge through
developer lever documentation just to find out a simple
relationship.
Start simple, then build up to the complex.
…-T
|
|
I really think that there is still something to discuss in this ticket. |
I agree with JJ. There's no point having this as a stand alone issue for this page. It would have to change across all the pages and I'd welcome you writing that up as an issue. For my part, I wouldn't like to see graphs at the top of pages. As JJ says, you can see the graph clearly by clicking on the link that says 'vector' (perhaps that needs to be more obvious in some way?) Ideally you wouldn't "go down several pages" but click on the link to Type Graph (Perhaps this needs to be more obvious in some way?) I think the language pages are more beginner orientated and once you're banging around in types, you're in something more of a reference section and there needs to be some expectation of understanding what you're looking at and why (I think that it would be really useful to have a document perhaps explaining what you're looking at though!) I'm not going to close this issue myself, otherwise it's just a tennis match, but if either @AlexDaniel or @ToddAndMargo want to, that would be good. It's definitely not a change that should be made in isolation. |
|
On 9/18/18 11:45 AM, MorayJ wrote:
As JJ says, you can see the graph clearly by clicking on the link that
says 'vector' (perhaps that needs to be more obvious in some way?)
That was my mistake. I was clicking on the picture itself.
What I want is the beginner's, common user's stuff
at the top and the advanced, developer's level stuff
underneath.
I think moving the graph to the top would accomplish that.
A quick link to it should also accomplish that as long
as your say "more obvious in some way".
|
|
On 9/18/18 11:45 AM, MorayJ wrote:
If you want to open another different ticket saying "Repeat in every
Role all the known classes that mix it in, or include in every class all
known classes that subclass it" please do so by all means
I did not see this. Would someone mind forwarding it to me?
|
|
@ToddAndMargo as participant in this issue, you should have received it. In the same email, there is a link in the bottom of the page which will direct you to all this conversation. |
|
Closed: superseded by #2315 |
But that's the same ticket? |
Request for Enhancement:
On https://docs.perl6.org/type/Real, you have to wade all the way down to find the subsets of what classes "Real" includes.
https://docs.perl6.org/type/Real#Type_Graph
Which is blurry and difficult to read.
It is not readily apparent what you are looking at.
Would you consider adding to the top of the page:
"Real" is a "Role" that includes the following classes: FatRat, Rat, Rational, Duration, Instant, Int, PromizeStatus, Bool, Automicint, Sinval, Order, InStr, NumStr, Num
I may have misspelled some of them, as the graph is blurry
The text was updated successfully, but these errors were encountered: