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
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
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.
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.
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.
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?
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.
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:
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.
Due to https://rt.perl.org/rt3/Ticket/Display.html?id=114510 we render source code like
C<< infix:<||> >>
wrongly (as < infix:<|| >>
).
<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.
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?
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/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
}
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; }Make search function (in web version of p6doc) visible
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?
Duplicate documentation for methods from Grammar
http://doc.perl6.org/routine/parse shows two explanations for the same method, presumably once from
lib/Type/Grammar.pod
(good) and once fromlib/language/grammars.pod
(bad). Those docs should be unified, and language/grammars should link to the type with the API docs.eqv docs misleading
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]$Customize font used in svg/ping diagram graphics
The current (default) font being used in the svg/png diagram graphics may look a bit dated. I suggest switching to FreeSans.
Does not work on Windows cmd.exe because of dependency on less
> p6doc Pod::To::Markdown 'less' is not recognized as an internal or external command, operable program or batch file.
lib/Type/Str.pod small changes
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
searching for 'map' does not show Supply in the results
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.
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
Search gives no feedback when nothing found
Expected: some kind of "no results". Got: no feedback.
Confusion in documentation of < >
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).
TODO: Explanation of compilation phases and phasers
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.
Include :e and -s and friends in the index
http://doc.perl6.org/List.pick returns "page not found"
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
Colored source code
Hello,
Could you highlight the source code on the web site?
Regards
Searching for mkdir fails
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 anchormkdir
leading to http://doc.perl6.org/routine/mkdir which 404.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.
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).
recursive dir example is deprecated
The recursive example on http://doc.perl6.org/routine/dir gives me a deprecation warning.
Put link to github repo on doc.perl6.org footer
Had to actually google for it! :-)
Suggestion: make "work in progress" the link.
classtut example doesn't work
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'
missing File::Temp dependency
just started with a fresh
rakudobrew build moar; rakudobrew build-panda; panda install Task::Star;
and got to this failure. Had to manuallypanda 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 ........ okTest 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:87Failure Summary
Task::Star
*test stage failed for p6doc: Tests failedtraits should be searchable just as other routines
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 asTrait: is default
Html link to Compile-time variables.
On the page
http://doc.perl6.org/language/variables
at the bottom of theThe ? 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.[PATCH] eval -> EVAL in bin/p6doc
--- 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);
Html link to nativeInt
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.Allow search for variables
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.t/pod-htmlify.t fails
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
usesPod::Htmlify
, which in turn usesURI::Escape
. Which makes the test fail when one tries to install doc via panda, and also in the smoke testInfix + doesn't show up in documentation
http://doc.perl6.org/+ and http://doc.perl6.org/routine/+ list the prefix version and the regex version, but not the infix operator.
Ops that are a prefix and infix get folded in search to "Prefix: Op"
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: …"
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
named subroutine also could store in a named scalar
> my $x = sub double($y) { 2 * $y } sub double (Any $y) { #`(Sub|74224392) ... } > $x(2) 4
pack/unpack seem to be for Buf but still docs and tests are associated with Str
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
TODO: make anchors available for linking to sections directly
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.
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.
Jobs
Jooble