raku / doc Goto Github PK

this is probably related to #33
I thought both cwd and mkdir should be listed on http://doc.perl6.org/routine.html shouldn't they?

The current (default) font being used in the svg/png diagram graphics may look a bit dated. I suggest switching to FreeSans.

On docs.perl6.org/language/variables, there's a heading called Compile-time "constants" . Clicking on the link heading fails because of the quotation marks (%22) in the heading title.

The heading tag is incorrectly rendered as <h2 id="Compile-time_"constants""> .

My suggestion is to remove the quotation marks around "constants"; perhaps "compile-time variables" or "compile-time values" is a better wording anyway.

Pm

For example, under http://doc.perl6.org/#Routines :

• http://doc.perl6.org/routine/left+elems
• http://doc.perl6.org/routine/calling+package

As someone new to Perl 6 I found some documentation missing and in the processes of getting familiar with certain undocumented or poorly documented packages it seems natural for me to contribute docs. Especially from the unspoiled 'what would a new user need' perspective.

But even though I am not new to programming, not new to documenting code or writing docs in general and not even new to writing POD I am having a hard time to figure out where to actually start contributing.

I am pretty sure a quick getting started guide could help a great deal to get drive-by contributions to the docs.

== If you have you just seen a POD ERRORS message ==

If a github page corresponding to a doc page displays "POD ERRORS", please:

1. Search this issue page for the relevant topic/filename combo (eg Language/unicode_entry.pod or Type/AST.pod).
2. Skip to the last match, if any. If the last comment mentioning the page you're searching for was written more than a day ago and says it's been fixed, or if there's no match at all, then assume you are seeing a new problem and add a new comment to alert us to a new problem. Please paste a link back to the github page containing the error plus the error message from that page. See the first comment added to this issue below for an example.
3. You can still edit the github page despite the error; just click the Pencil icon.

Thanks!

== Closing this issue ==

When we've: A) eliminated all POD ERRORS generated by github's web interface for displaying P6 doc pages; and B) expect them to only rarely re-occur; then we can close this issue.

On the Perl6 doc page about types http://doc.perl6.org/type.html the link to class int on the bottom of the line points to a non existing file (http://doc.perl6.org/type/nativeInt). I've found http://doc.perl6.org/type/int.html though but I'm not sure if this one is meant.

pack is documented (and unpack is mentioned) in S32/Str but not S32/Containers which describes Buf. Tests similarly in S32-str. Also don't see pack/unpack in doc.perl.org. Noticed some doc here https://gist.github.com/1239203

Ron

Due to https://rt.perl.org/rt3/Ticket/Display.html?id=114510 we render source code like

C<< infix:<||> >>

wrongly (as < infix:<|| >>).

If our users use doc.perl6.org as their first step towards finding out how something works, but whatever it is isn't covered there (in my case I was looking for an easy to find explanation of 'for' loops), they would miss this excellent resource.

We should perhaps consider either getting the set of available translations from their website or look for a way to link to perl6 "in all available languages".

When one enters < >in the search box, and selects Circumfix < > one lands on /routine/<+>, which is a 404. The same happens for Quote < >, which links to /syntax/<+>, which is also a 404.

The correct URL seems to be with %20 instead of a + sign.

http://doc.perl6.org/search is an URL that delivers search-as-you-type results and/or a web listing of search results.

This search feature is just about invisible. A google search for links to it returns no matches. It's not even linked from any of the http://doc.perl6.org/ pages!

I think making it visible would deliver a relatively big bang for the buck.

Some ideas:

• add a search link, or the box itself, to http://doc.perl6.org/ pages
• add a search link, or the box itself, to other pages in perl6.org?
• ask folk to add a link outside of perl6.org (eg topic of #perl6 IRC channel)?
• publish code to allow adding the search box to pages outside perl6.org?
• ask folk with pages outside per6.org to add a link/box? (eg http://search.perlhacks.com)?
• can it be tied directly in to CSEs (eg http://search.perlhacks.com, http://now.perl6.org)?
• can it be tied directly in to duckduckgo's Perl 6 search?
• other ideas?

Specifically, http://doc.perl6.org/routine/~ and http://doc.perl6.org/routine/- (and probably others) are displayed in the search as "Prefix: ~" and "Prefix: -", when they should really be "Routine: …" or perhaps "Operator: …"

lib/type/Variable.pod has headings like =head2 trait is default, which should work like =head2 method foo, and should show up in the search as Trait: is default

Entering "http://doc.perl6.org/List.pick" into a browser results in "Not Found". Ideally it should take me directly to the documentation for List.pick.

Pm

http://doc.perl6.org/routine/parse shows two explanations for the same method, presumably once from lib/Type/Grammar.pod (good) and once from lib/language/grammars.pod (bad). Those docs should be unified, and language/grammars should link to the type with the API docs.

http://doc.perl6.org/type/Supply

though the page http://doc.perl6.org/routine/map lists Supply as well. So maybe this is how it is supposed to be.

The first example in classtut doesn't work. I get the error message: 'Nominal type check failed for parameter '@Dependencies'; expected Positional but got Array instead'

Under the Operators heading on the page for class SetHash, the link to setbagmix#Set/Bag Operators is broken. I suspect that the slash between Set/Bag is seen as a bad path.

I might also add the union operator (|) and the corresponding unicode operator to the example code on this page.

More specifically if I search for mkdir on http://doc.perl6.org/ I get a link to http://doc.perl6.org/type/X%3A%3AIO%3A%3AMkdir which is not the best hit, but then the documentation has a link with anchor mkdir leading to http://doc.perl6.org/routine/mkdir which 404.

line:178

  say split(';', "a;b;c", :all).perl;    # ("a", ";", "b", ";", "c").list 

should be:

  say split(';', "a;b;c", :all).perl    # (("a", ";"), ("b", ";"), "c").list

line: 180

  say split(';', "a;b;c", 2, :all).perl; #("a", ";", "b;c").list

should be:

  say split(';', "a;b;c" ,2, :all).perl  # (("a", ";"), "b;c").list

We have type relationships like

 role X::Comp is Exception { }
 role X::Syntax does X::Comp { }
 class X::Syntax::Confused does X::Syntax { }

now all of X::Comp, X::Syntax and X::Syntax::Confused have an inheritance arrow to Exception, which is clearly too much.

In the very least X::Syntax shouldn't have such an arrow (ie roles only have arrows to direct superclasses), and in general either the role or the class should have an inheritance arrow.

Today on IRC a P6 newbie was asking for the Perl 6 equivalent of Perl 5's __FILE__ . It might be nice the search box would allow searching for variables by name.

Expected: some kind of "no results". Got: no feedback.

<masak> [backlog] should lazy attribute defaults be part of http://doc.perl6.org/language/classtut ? did someone file an issue about this?
<masak> m: class C { has $.x = "OH HAI" }; say C.new(:x(42)).x; say C.new.x
<camelia> rakudo-moar 86b1b2: OUTPUT«42␤OH HAI␤»
* masak submits an issue
<liztormato> To be clear: has $.a = 42 is not lazy but run at build time
<masak> oh! yes, you are right. those two are not the same.

Up until that point in the conversation I was confusing "build-time" and "lazy", which are indeed different points. Leaving aside the lazy case for this issue (as the syntax is still being discussed), I think it'd make sense to document how to do the build-time default thing with attributes.

...including the nice trick with putting die in the rhs to make the object explode at build time if an attribute was not passed in.

just started with a fresh rakudobrew build moar; rakudobrew build-panda; panda install Task::Star; and got to this failure. Had to manually panda install File::Temp before retrying.

==> Fetching p6doc
==> Building p6doc
Compiling lib/Perl6/Type.pm to mbc
Compiling lib/Perl6/TypeGraph.pm to mbc
Compiling lib/Perl6/Documentable.pm to mbc
Compiling lib/Pod/Htmlify.pm6 to mbc
Compiling lib/Pod/Convenience.pm6 to mbc
Compiling lib/Perl6/TypeGraph/Viz.pm to mbc
Compiling lib/Perl6/Documentable/Registry.pm to mbc
Compiling lib/Pod/To/SectionFilter.pm to mbc
==> Testing p6doc
t/pod-convenience.t .. ok
===SORRY!===
Could not find File::Temp in any of: file#lib, file#lib, file#/home/hayter/.panda-work/1431054053_9/blib/lib, file#/home/hayter/.panda-work/1431054053_9/lib, file#lib, file#/home/hayter/.perl6/2015.04-179-g6b4f9be/lib, inst#/home/hayter/.perl6/2015.04-179-g6b4f9be, file#/home/hayter/.rakudobrew/moar-nom/install/share/perl6/lib, file#/home/hayter/.rakudobrew/moar-nom/install/share/perl6/vendor/lib, file#/home/hayter/.rakudobrew/moar-nom/install/share/perl6/site/lib, inst#/home/hayter/.rakudobrew/moar-nom/install/share/perl6, inst#/home/hayter/.rakudobrew/moar-nom/install/share/perl6/vendor, inst#/home/hayter/.rakudobrew/moar-nom/install/share/perl6/site
t/pod-htmlify.t ......
No subtests run
t/typegraph.t ........ ok

Test Summary Report

t/pod-htmlify.t (Wstat: 0 Tests: 0 Failed: 0)
Parse errors: No plan found in TAP output
Files=3, Tests=18, 2 wallclock secs ( 0.01 usr 0.00 sys + 2.32 cusr 0.07 csys = 2.40 CPU)
Result: FAIL
test stage failed for p6doc: Tests failed
in method install at lib/Panda.pm:133
in block at lib/Panda.pm:210
in method resolve at lib/Panda.pm:204
in sub MAIN at /home/hayter/.rakudobrew/bin/../moar-nom/install/share/perl6/site/bin/panda:20
in sub MAIN at /home/hayter/.rakudobrew/bin/../moar-nom/install/share/perl6/site/bin/panda:18
in block at /home/hayter/.rakudobrew/bin/../moar-nom/install/share/perl6/site/bin/panda:87

Failure Summary

Task::Star
*test stage failed for p6doc: Tests failed

doc doesn't declare a dependency on Pod::To::HTML or URI because most users don't need to run htmlify. But t/pod-htmlify.t uses Pod::Htmlify, which in turn uses URI::Escape. Which makes the test fail when one tries to install doc via panda, and also in the smoke test

Hello,

Could you highlight the source code on the web site?

Regards

Grep S04 for newline. A boring example:
my @bar = grep {;]
@foo;

The sentence "This documentation was generated from " at the end of documents such as http://doc.perl6.org/language/mop should be in a different layout than the normal copy (or it should move to the footer).

On Any doc class http://doc.perl6.org/type/Any there is link to http://doc.perl6.org/images/type-graph-Any.png instead of http://doc.perl6.org/images//type-graph-Any.svg

Anyway clicking anywhere in this svg tree leads to not existing html documents

In the html output at doc.perl6.org, it would be nice if the

 blocks stood out a little bit from the surrounding text. Consider adding this to the css:

pre {
    background-color: #f4f4f8;
    border: 1px solid #ededf2;
    padding: 6px;
}
    

The recursive example on http://doc.perl6.org/routine/dir gives me a deprecation warning.

To me them imply this would return True:

[jdv@wieldy rakudo]$ perl6 -e 'class A{has $a};say A.new(:a(5)) eqv A.new(:a(5))'
False
[jdv@wieldy rakudo]$

On the page http://doc.perl6.org/language/variables at the bottom of the The ? Twigil section there is a pointer to Compile-time variables (http://doc.perl6.org/type/Compile-time%20variables) which points to a non-existing document. I also couldn't find an alternative file in the same directory.

In our type graphs, enum types like PromiseStatus are currently rendered like normal subtypes of their value type: http://doc.perl6.org/images/type-graph-Int.png

This can create confusion.

We should review all built-in enum types and then decide which of the following solutions is better:

• render enum types differently from classes
• exclude enum subtypes altogether from type graphs of class types

It might be good to have a style guide for people (such as myself) who are contributing POD content to this repo, so the "finished" docs end up in a consistent and professional state.

Here are a few "questions" that imo should be covered by such a guide (though I don't have good answers for all of them):

Structure

How to document multiple similar routines

I'd suggest making it a guideline to avoid wtiting a routine's documentation in the form

Like [other method] except [...]

even when they're in the same class, because readers might not read the whole class page, but rather navigate to a specific routine (maybe even out of context in the /routine/ section of the website) and expect it to tell them how it works without being sent on a goose chase around the site.
In other words, give each routine documentation a self-contained introduction, and only link to related/similar routines below that introduction, even if that means duplicating some half-sentences multiple times.

Language

How to refer to the concept of only using the .Bool/.Num/etc. coercion of a value and discarding the original information

Compare:

• "it evaluates the value in boolean/numeric context"
• "it boolifies/numifies the value"
• "it uses the truthy/numeric value"
• "it reduces the value to its boolean/numeric equivalent"

Are all of these sufficiently professional and newbie-friendly? Which is preferred?

Whether to write 'parameter' vs 'argument'

I recently came across this in S06:

S06: "In Perl 6 culture, we distinguish the terms parameter and argument; a parameter is the formal name that will attach to an incoming argument during the course of execution, while an argument is the actual value that will be bound to the formal parameter. The process of attaching these values (arguments) to their temporary names (parameters) is known as binding. (Some C.S. literature uses the terms "formal argument" and "actual argument" for these two concepts, but here we try to avoid using the term "argument" for formal parameters.)"

I'd suggest we follow the spec here from now on, and make this an official guideline for p6doc.

Whether to write 'object' vs 'value'

Is it OK to use "objects" as an umbrella term for instances of any Perl 6 type, including immutable value types?

Or should it be reserved for reference types, and be replaced with the phrase "objects/values" whenever we're talking about both reference and value types?
(See the introduction of /type/Set for an example of this usage, though this shouldn't be seen as a recommendation.)

Whether to use past tense or present tense when talking about Perl 5 features

Compare:

• "In Perl 5 this was used for ..., but in Perl 6 ..."
• "In Perl 5 this is used for ..., but in Perl 6 ..."

Slipping into the past there can be tempting when writing such docs, but I think we should avoid it, as it misrepresents the development status of Perl 5 (which is actively maintained both now and probably for a long time to come), and could come across as needlessly abrasive to Perl 5 programmers.

Formatting

How to show output of sample code lines

Currently, we tend to use normal # comments both for annotating code, and for showing its output:

my @a = 2, 4, 6; # creates a new array
say @a.WHAT;     # (Array)

Though I think I've also seen this convention used somewhere:

my @a = 2, 4, 6; # creates a new array
say @a.WHAT;     #> (Array)

It could avoid ambiguity, and while it is a little uglier by itself, htmlify could detect it so we could give it special CSS rendering (think dark background with light text like a terminal) that would make its purpose extra clear to readers.

Would it be worth it?

Character class negation isn't documented anywhere in regex. I asked on IRC where they told be the syntax is <-[abcd]> compared with Perl5 [^abcd].

This should be documented.

http://doc.perl6.org/+ and http://doc.perl6.org/routine/+ list the prefix version and the regex version, but not the infix operator.

When github renders a README, hoovering over the heading shows a link with an anchor to exactly that section.

I'd like to have something similar for the htmlify output, so that it becomes easy to link to a section directly.

Entering "< >" in the search box currently lists three entries:
Postcircumfix: .< > leads to routine/.<%20> (currently 404 not found)
Circumfix: < > leads to routine/<%20>
Quote: < > leads to syntax/<%20>

I don't think there should be a "circumfix" entry, as < > is not an operator, nor is there a circumfix:«< >» function/routine. As far as I can tell, it's purely a syntactic construct.

I suspect the same should be said for postcircumfix .< > -- as far as I know it's not a routine in its own right -- it's really syntactic sugar for .{< >} . It's not an operator in its own right (e.g., that could be overloaded).

A question on #perl6 was roughly: from a CHECK phaser inside a class, can I use the class?

To answer this (and other) questions, the various compilation phases, phasers, and type composition time should be explained.

http://doc.perl6.org/language/io and http://doc.perl6.org/type/IO should mention how to iterate over a file line-by-line. I mean:

for 'sets.txt'.IO.lines -> $line {
    # Do something with $line
}

I tried ./bin/p6doc Str.zbd and got a lot of these warnings on STDERR before it printed the whole pod:

use of uninitialized variable $from of type Any in numeric context in method render at ./bin/../lib/Pod/To/SectionFilter.pm:15

use of uninitialized variable $heading-level of type Any in numeric context in method render at ./bin/../lib/Pod/To/SectionFilter.pm:16

use of uninitialized value of type Any in string context in method render at ./bin/../lib/Pod/To/SectionFilter.pm:21

to lead to http://doc.perl6.org/type/IO%3A%3AFileTestable

--- a/bin/p6doc
+++ b/bin/p6doc
@@ -70,7 +70,7 @@ multi sub MAIN() {
multi sub MAIN($docee) {
return MAIN($docee, :f) if defined $docee.index('.') ;
if 'index.data'.IO ~~ :e {

•    my %data = eval slurp 'index.data';
  

•    my %data = EVAL slurp 'index.data';
   if %data{$docee} {
       my $newdoc = %data{$docee}[0][0] ~ "." ~ %data{$docee}[0][1];
       return MAIN($newdoc, :f);
  

http://doc.perl6.org/type/Int doesn't show methods from Numeric, but it does show methods from Real. Presumably this is because Int does Real, and Real does Numeric, and the code that composes the roles doesn't do so recursively.

Had to actually google for it! :-)

Suggestion: make "work in progress" the link.