Meaning of "Out" for export

[amueller]

I realized a bit late that "Out" is only attached to the return value of a cell, not to output going to standard out. This is somewhat non-obvious.

I guess that is something done very intentionally, but it leads to some odd effects when converting to other formats, in particular markdown.
I kind of expected the "Out" do separate the input from the output, because there is no formatting as in the HTML. But that's not how it works. The "Out" could be anywhere in the output, or not present at all. And in black and white (print) the distinction between code and output can also not be made via the syntax highlighting.

For my book, I would like to have an "Out" associated with the output to make clear what the output is, but that means I'm changing the semantics with respect to what it means in the notebook, which is also not ideal.

Has anyone thought about this? What do you think would be a good way to format "the output" of a cell when exporting for publishing?

In notebook usage, I never really paid attention to where the "Out" is because the colors are a much stronger cue.

[amueller]

One possibility would be to never use the return value and always use display for displaying things, so the meaning would be more consistent within the published material. But it still would change the meaning of "Out".

[takluyver]

By default, nbconvert tries to put Out prompts in the same places they appear in the live notebook; it's roughly trying to recreate the appearance of the notebook in whatever format it's converting to. Obviously that works better in some cases than others.

It should be straightforward to make a template that doesn't use Out prompts at all, or puts a prompt before every group of outputs. I wouldn't worry too much about preserving the semantic meaning of the prompt for a custom conversion.

[amueller]

Yeah I did the later, which puts an Out before every group.
I guess I'll go that route in #355.

[amueller]

So the solution is "create templates that look reasonable" and close? I haven't checked all the templates, though.

[takluyver]

I'd be OK with skipping the Out prompts in the default Markdown template, but I'd like to see what other people think about it.

[mpacer]

Now #554 takes care of hiding output prompts with --no-prompt, or explicitly only the output prompts with --TemplateExporter.exclude_output=True.