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;
}
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.
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.
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).
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.
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]$
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.
Hello,
Could you highlight the source code on the web site?
Regards
<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.
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
Grep S04 for newline. A boring example:
my @bar = grep {;]
@foo;
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).
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
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
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.
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
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
> p6doc Pod::To::Markdown
'less' is not recognized as an internal or external command,
operable program or batch file.
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.
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
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?
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?
Had to actually google for it! :-)
Suggestion: make "work in progress" the link.
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.
> my $x = sub double($y) { 2 * $y }
sub double (Any $y) { #`(Sub|74224392) ... }
> $x(2)
4
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'
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.
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.
-