Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

document how to pretty-print objects #18634

Merged
merged 1 commit into from
Sep 23, 2016
Merged

document how to pretty-print objects #18634

merged 1 commit into from
Sep 23, 2016

Conversation

stevengj
Copy link
Member

This fixes #9458.

This has come up a zillion times on julia-users (here, here, here, here, here, here, here, ....). I can't believe we've gone this long without a manual section on it.

@stevengj stevengj added the docs This change adds or pertains to documentation label Sep 22, 2016
@stevengj stevengj merged commit 990dcd9 into JuliaLang:master Sep 23, 2016
@stevengj stevengj deleted the doc-show branch September 23, 2016 00:47
@tkelman
Copy link
Contributor

tkelman commented Sep 23, 2016

These should be doctests

tkelman
tkelman reviewed Sep 23, 2016
View reviewed changes
doc/manual/types.rst

More fine-grained control over display of ``Polar`` objects is possible.
In particular, sometimes one wants both a verbose multi-line printing
format, used for displaying an single object in the REPL and other interactive
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a single object

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed.

@tkelman
Copy link
Contributor

tkelman commented Sep 23, 2016

I think PR's that aren't absolutely trivial or urgent should remain open at least long enough for contributors in all time zones to get a chance to review them before they get merged.

stevengj added a commit to stevengj/julia that referenced this pull request Sep 23, 2016
@stevengj
add pretty-printing doctests (for JuliaLang#18634)
d76e98f
@stevengj stevengj mentioned this pull request Sep 23, 2016
Merged
stevengj added a commit to stevengj/julia that referenced this pull request Sep 23, 2016
@stevengj
add pretty-printing doctests (for JuliaLang#18634)
806b504
StefanKarpinski
StefanKarpinski reviewed Sep 23, 2016
View reviewed changes
doc/manual/types.rst

Base.show{T}(io::IO, ::MIME"text/html", z::Polar{T}) =
println(io, "<code>Polar{$T}<code> complex number: ",
z.r, " <i>e</i><sup>", z.Θ, " <i>i</i></sup>")
Copy link
Sponsor Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to use inline HTML in Markdown to show how this looks?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I can add it to #18649 via the .. raw:: html technique.

tkelman referenced this pull request Sep 23, 2016
@stevengj
typo
792ded8
stevengj added a commit that referenced this pull request Sep 26, 2016
@stevengj
add pretty-printing doctests (#18649)
c71f205 
* add pretty-printing doctests (for #18634)

* in the HTML manual, render the HTML pretty-printing example
JeffBezanson pushed a commit that referenced this pull request Sep 26, 2016
@stevengj @JeffBezanson
add pretty-printing doctests (#18649)
3bebffb 
* add pretty-printing doctests (for #18634)

* in the HTML manual, render the HTML pretty-printing example
@nalimilan
Copy link
Member

Thanks for adding this, but I think I'm even more confused than before. Indeed the manual now says we should use the two-argument show method to print the compact representation. Yet, the docstring for showcompact says (since 5d7dd9c, but before that it was Base.limit_output) one should use get(io, :compact, false) for that. That's what e.g. Nullable printing uses currently.

So how are these two mechanisms related? Should they be used for different things?

@vtjnash
Copy link
Sponsor Member

vtjnash commented Oct 2, 2016

The tl;dr difference should be:

  • 2-arg show: default representation
  • show compact: hide non-essential information (such as types and type parameters)
  • show limited: truncate the output, to "fit" (which may hide essential information)
  • mime-show: use more verbose formatting (same information, but better layout)

@nalimilan
Copy link
Member

Thanks. So the manual should stop recommending the two-argument form of show for compact representation, and advise using the compact attribute instead?

@vtjnash
Copy link
Sponsor Member

vtjnash commented Oct 2, 2016

It seems like "unformatted" may be a better term, since describing it as "compact" is ambiguous with the compact attribute?

@StefanKarpinski
Copy link
Sponsor Member

Despite being semi-convinced when Jameson, Jeff and I hashed this out in person after JuliaCon, I think this current design is too complicated and hard to explain. The multiline option was easier to explain than this. We should probably come up with something clearer for the next release.

@vtjnash
Copy link
Sponsor Member

vtjnash commented Oct 2, 2016

The multiline attribute just completely didn't work. I think we just need to be better at explaining this upfront in the documentation for custom IO formatting. The distinction should be:

  • mimetype -> specifies the layout type (e.g. do you use \n ("text/plain") or <br> ("text/html") or \n\n ("text/md") or <ul></ul> ("text/html", for a list) to make a paragraph?)
  • iocontext parameters -> specifies what information is unnecessary or uses an alternate form (e.g. using color vs. bold vs. proofreaders' marks to highlight content, or whether to drop type parameters, or etc.)

@nalimilan
Copy link
Member

There's also the issue with print which is documented to give an "(un-decorated) text representation" and yet calls show instead of showcompact by default... (And @enum which defines showcompact in terms of print...)