Single style for output of examples

[Altai-man]

See #761 (comment)

TL;DR: right now we don't have a single "official" output format for our examples, and everyone who writes documentation uses their own style. It's bad if we want to test our examples result automatically in the future. Our current formatting variants:

• #-> result
• # result
• # OUTPUT: «result␤»
• # OUTPUT: result

• # OUTPUT:
  # result1
  # result2
  # result3
  # result4

Please, if you want to propose your own "style" - do it with a comment or just edit this message.
We need opinions about what style is best.

This issue is marked as `big`, because after selection we also need to rewrite all output results that don't match new "official" format line.

[zoffixznet]

I like using the following, as this way multi-line output aligns well and it's clear that it's output.

# OUTPUT:
# result1
# result2
# result3
# result4

I'm against using # result, because it'd conflict with regular comments, especially when we do automated output check and I'm against OUTPUT: «result␤» because it's hard to type the fancy-pants symbols (I don't even know how to type them on my phone at all) and multi-line output will look confusing, especially to people unfamiliar with the ␤ symbol and our use of it:

# OUTPUT: «result1␤result2␤result3␤result4␤»

[gfldex]

You don't type the result at all. You copy-pasta them from camelia into the docs because you tested the example against camelia to make sure they hold true.

The OUTPUT: «result␤» form allows easy parsing, I do agree that ¶ would have been a better pick because more ppl will be familiar with that symbol. We could change that automatically for html-output.

I'm sorry but the "I don't know how to ... on my phone"-argument is to selfish to be relevant to hopefully millions of readers of docs.perl6.org.

[AlexDaniel]

I agree that multi-line output should normally be on multiple lines. As for the «», these are usually typable on phones (and yeah, I think that the argument that you can't type something does not work so well in Perl 6 world). However, when I look at this:

OUTPUT: «result»
OUTPUT: result

It feels like «» are slightly redundant.

So:

say qw{1 2 3 4}; # OUTPUT: (1 2 3 4)

.say for qw{1 2 3 4};
# OUTPUT:
# 1
# 2
# 3
# 4

↑ I see no problem here whatsoever. It is parseable and it looks great.

Comparing that to this:

say qw{1 2 3 4}; # OUTPUT: «(1 2 3 4)»

↑ Meh, «» look a bit weird.

[Altai-man]

We don't have to type the result itself - it's true, but what if I(hypothetically) am a docs writer and I test my examples against my latest rakudo distribution, not camelia?
Solved with http://irclog.perlgeek.de/perl6/2016-07-28#i_12929832

I can replace every "write" occurrence with "paste result(and maybe add "OUTPUT:" word or something like this)" in original post if it matters.

[zoffixznet]

You copy-pasta them from camelia [...] I'm sorry but the "I don't know how to ... on my phone"-argument is to selfish to be relevant to hopefully millions of readers of docs.perl6.org.

So you hope for millions of readers but how many contributors do you envision? Your argumentation seems to assume all the docs will be written by a handful of nerds who know all about entering Unicode on any device that falls into their hands and who not only regularly hang out on IRC, but also are connected when they make a contribution.

My comments aren't about selfishness, but about pointing out that the proposed format alienates contributors by raising the knowledge required for making a contribution and reduces the amount of drive-by contributions we will get.

[zoffixznet]

And another point, the ␤ doesn't even display right on my Linux dev box. I'm sure I can't be the only one out of these supposed millions of readers who has this problem, but let me guess, this type of argument "does not work so well in Perl 6 world," right?

[coke]

I have no problem requiring unicode -- we're not going to hand out commit bits to everyone. The core contributors can keep things clean, and people contributing docs can do their best based on our submission guidelines when we have them.

Perl 6 has always encouraged unicode where it makes sense, and we should, IMO, continue that trend in the docs (again, where it makes sense)

@zoffixznet, if you're having trouble with the glyphs on this page (like ␤), I'm sure we can help you get that working (and then include that in a how to guide for getting people up and running with unicode)

[zoffixznet]

and then include that in a how to guide for getting people up and running with unicode

sudo apt-get install ttf-unifont brought in the missing glyphs

[AlexDaniel]

If it's going to be added to some guide, throw in fonts-freefont-ttf as well.

[uvtc]

See also comments in #51.

[gfldex]

be93ca1816

make extract-examples then find examples/ -iname '*.p6' -exec perl6 '{}' ';'

It's a disaster. :) Most of the errors come from missing ; at the end of statements. I may be able to cast a Makefile spell to generate files depending on source files. The 5to6 pods are a bit of a problem in that regard.

[gfldex]

As a prototype I made Signature.pod6 compile. Took only two hours. I had to remove FormattingCodes from examples because the parser adds newlines and spaces at spots where they don't belong. In HTML they are not visible (they may pop up on copypasta tho) because spaces and newlines on inline tags are not rendered by the browser. With that change it works quite nicely. I found 8 bugs in those examples. If that rate hold for all .pod6 we are looking about 300 odd bugs. :)

I'm not happy with having to add EVAL to two examples to catch compile time exceptions. Having EVAL blogs around each code block defies the purpose tho, as we want exit codes > 0 so make can complain properly.

[gfldex]

The EVAL problem is solved with:

=begin code :skip-test
=end code

[Altai-man]

edbad254e0 this commit adds last bits to the Type/ section work.
Now on
This is Rakudo version 2016.07.1-57-g0419194 built on MoarVM version 2016.07-3-gc01472d
all examples in the type documentation can be executed, infinite examples are skipped.

And, actually, I opened this issue to discuss how exactly we should format our output. There are many words(and I really appreciate everyone opinions), but no certain result, so my final thought is like this:

• We can use plain # result and sweet # OUTPUT: «result␤» styles. As for Type directory, I've found that they are the most common cases. Styles like #> or other are extremely rare and thus should be considered as bad-formatting and changed.
• There are two styles because, okay, there is more than one way to do it.

Any comments?

[coke]

I would recommend picking a single style. If we have more than one style, we have to write and maintain more code, and more documentation.

I recommend this style, with 2 variants; one for dealing with output, and one for just the last value, in case the example doesn't deal with stdio.

say 3; # OUTPUT: «3␤»

2+5; # RESULT: «7»

With this approach then we can have other comments that aren't being tested.

2+5i; # this is a complex number

I don't have a preference on the actual quotes; I think we can use any valid matching quote pair. (or a smaller whitelisted subset)

[Altai-man]

Let us(or, rather, just lazy me) reanimate this!

So, basically, judging by

➜  doc git:(master) grep -I -r '# .*' doc/ | wc -l
3975

• we have about ~4k of comments that need to be revisited and formatted by a style-guide that @coke suggested. I can do it.
• we need to mention our new comments style-guide in CONTRIBUTING.md. It will need someone's writing skills.
• we need to write an actual script/test that will execute examples and match its output with things in comments. It is a large task and, perhaps, another issue.

Any opposite thoughts?

[AlexDaniel]

No? Just go for it!

[Altai-man]

Actually, we don't need the third clause, see https://irclog.perlgeek.de/perl6/2017-02-01#i_14023735
The needed thing is just a test, not a whole Cool Compilation Suite.

[Altai-man]

With #1165 #1176 #1181 the first goal is done.
I'm quite short on time now, anybody willing to do the second or the third goal? Perhaps, I'll write a test by myself though.

Also, I think it will be great to mention such major change to CONTRIBUTE.md(when it will be written) in some global news source for contributors(not everyone re-read contribution guidelines every day and we don't want to ruin our unified style quickly) like perl 6 weekly(?). cast @gfldex.

And this hell will be closed soon.

[Altai-man]

The test is written and soon will be PR'ed.

[Altai-man]

The original goal was achieved. Closed.