raku / doc Goto Github PK
View Code? Open in Web Editor NEW🦋 Raku documentation
Home Page: https://docs.raku.org/
License: Artistic License 2.0
🦋 Raku documentation
Home Page: https://docs.raku.org/
License: Artistic License 2.0
> p6doc Pod::To::Markdown
'less' is not recognized as an internal or external command,
operable program or batch file.
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
}
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/+ and http://doc.perl6.org/routine/+ list the prefix version and the regex version, but not the infix operator.
--- 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);
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.
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.
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?
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
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.
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.
> my $x = sub double($y) { 2 * $y }
sub double (Any $y) { #`(Sub|74224392) ... }
> $x(2)
4
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.
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).
Expected: some kind of "no results". Got: no feedback.
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):
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.
Compare:
Are all of these sufficiently professional and newbie-friendly? Which is preferred?
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.
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.)
Compare:
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.
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?
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
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
Task::Star
*test stage failed for p6doc: Tests failed
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'
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
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:
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.
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.
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".
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]$
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: …"
Due to https://rt.perl.org/rt3/Ticket/Display.html?id=114510 we render source code like
C<< infix:<||> >>
wrongly (as < infix:<|| >>
).
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.
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.
The current (default) font being used in the svg/png diagram graphics may look a bit dated. I suggest switching to FreeSans.
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:
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
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
The recursive example on http://doc.perl6.org/routine/dir gives me a deprecation warning.
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
<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«42OH 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.
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.
Had to actually google for it! :-)
Suggestion: make "work in progress" the link.
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.
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; }Asking for not-existing method gives warnings
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
Different Layout for "This documentation was generated from <file>"
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).
Ticket for collecting all POD ERRORS
== 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.
Character class negation is undocumented
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.
Compile-time "constants" heading link broken
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
Recommend Projects
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
Recommend Topics
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web
Some thing interesting about web. New door for the world.
server
A server is a program made to process requests and deliver data to clients.
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization
Some thing interesting about visualization, use data art
Game
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.
Microsoft
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.