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;
}
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]$
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.
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.
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.
Grep S04 for newline. A boring example:
my @bar = grep {;]
@foo;
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'
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
Hello,
Could you highlight the source code on the web site?
Regards
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.
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.
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.
== If you have you just seen a POD ERRORS message ==
If a github page corresponding to a doc page displays "POD ERRORS", please:
- Search this issue page for the relevant topic/filename combo (eg Language/unicode_entry.pod or Type/AST.pod).
- 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.
- 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.
--- 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);
> p6doc Pod::To::Markdown
'less' is not recognized as an internal or external command,
operable program or batch file.
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
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
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).
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
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
The current (default) font being used in the svg/png diagram graphics may look a bit dated. I suggest switching to FreeSans.
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.
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/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?
<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.
Expected: some kind of "no results". Got: no feedback.
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).
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
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.
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
> my $x = sub double($y) { 2 * $y }
sub double (Any $y) { #`(Sub|74224392) ... }
> $x(2)
4
Had to actually google for it! :-)
Suggestion: make "work in progress" the link.
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?
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
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.
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.
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".
Recommend Projects
-
-
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
š Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
An Open Source Machine Learning Framework for Everyone
-
The Web framework for perfectionists with deadlines.
-
A PHP framework for web artisans
-
Bring data to life with SVG, Canvas and HTML. ššš
-
Recommend Topics
-
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
Some thing interesting about web. New door for the world.
-
A server is a program made to process requests and deliver data to clients.
-
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Some thing interesting about visualization, use data art
-
Some thing interesting about game, make everyone happy.
-
Recommend Org
-
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Open source projects and samples from Microsoft.
-
Google ā¤ļø Open Source for everyone.
-
Alibaba Open Source for everyone
-
Data-Driven Documents codes.
-
China tencent open source team.
-
Jobs
Jooble