[perl #58742] [TODO] Marker for RTs re SmartLinks
James Keenan
# Please include the string: [perl #58742]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=58742 >
Only last night I discovered this group of Parrot RT tickets which
Paul Cochrane opened nearly a year ago:
http://rt.perl.org/rt3/Search/Simple.html?q=smartlinks
Of these 14, 11 are completely untouched.
I would like to encourage the folks who have volunteered for Perl 5-
ish assignments in Parrot in the last day to look into working on
these tickets.
Thank you very much.
kid51
James Keenan via RT
The 2 newest have actually been resolved. So we have 12 remaining.
James Keenan via RT
> I've looked at the state of the Smart Link concept as applied for Parrot
> and it looks like there are some issues that would need to be addressed
> before progress can be made on some tickets and other tickets might not
> make sense.
>
> The format of smartlinks is kind of loosely defined, the original Pugs
> implementation seem to contain some POD documentation to address some
> rough formatting needs though:
> http://svn.pugscode.org/pugs/util/smartlinks.pl
>
> The documentation there contradicts the Perl 6 POD draft
> (http://svn.pugscode.org/pugs/docs/Perl6/Spec/Documentation.pod) and the
> currently broken implementation in the Parrot repository.
>
> The POD incompatibility is only an issue of course in case someone would
> want to embed smartlinks inside a POD document and expect a (currently
> draft spec) compliant POD parser to behave nicely.
>
> The Pugs vs Parrot smartlink formats both follow the same general
layout of:
>
> L<spec/section/keywords>
>
> However, in the case of Pugs the smartlink utility deprecated the
> possibility to use regexps for the keywords segment and instead relies
> on simple key phrases to skip forward in the POD text when more
> precision than the specific section is desired.
>
> There is the issue of quoting - Pugs flavored smartlinks use double or
> single quotes to quote the section segment (optionally) and the key
> phrases. In case key phrases contain whitespace they are mandatory.
>
> Currently if someone would want to refer to a section that contains a
> forward slash, I assume Pugs flavoured smartlinks would do
>
> # L<PDD22/"I/O Iterator PMC API"/=item new>
>
> while t/pmc/io_iterator.t contains:
>
> # L<PDD22/I\/O Iterator PMC API/=item new>
>
> ...which results in an error from Parrot kind smartlinks.pl.
>
> Parrot kind smartlinks doesn't allow multiline smartlinks, but the Pugs
> kind does.
>
> Some of these issues could undoubtably be classified as bugs aswell in
> the Parrot kind smartlinks. I wonder however whether compatibility with
> Pugs style smartlinks is desired and what people think about that.
>
> Most of the tickets referenced by this one concern the implementation of
> the Parrot kind smartlinks.pl, which - if compatibility with Pugs's kind
> of smartlinks is the goal - would have to change enough to make at least
> some of them invalid.
>
> There has to be a working implementation based on a specification before
> smartlinks.pl can be tested properly whether the former conforms to the
> latter.
Thanks for this detailed analysis. It raises many questions in my mind.
My sense from reading the above and skimming the docs linked to above is
that any implementation of Perl 6 has to have something called
smartlinks because they're specified in the Perl 6 design documents. So
Rakudo Perl -- the implementation of Perl 6 in Parrot -- has to have
smartlinks just as Pugs does.
But that says nothing about whether *Parrot itself* must have something
called smartlinks. Parrot's source code is written in a variety of
languages, each of which has its own documentation format. Do PIR and
PASM need smartlinks? What would they do?
My impression is that we have a bunch of code in our
distribution/repository which someone, at some point in the past,
thought would be a good idea to bring into Parrot because it had
appeared in Pugs. This code is largely undocumented and, per szbalint's
report, doesn't work.
Is there any compelling reason to retain *any* of this code in Parrot?
If not, I'll propose a patch to rip it out after this week's release.
Moritz Lenz
I'll try to clear things up.
No Perl 6 implementation must do smartlinks.
Currently the smartlinks are in the test suite (which is supposed to be
implementation independent, and I'm working on making it like that). The
HTML that is generated from the synopsis then contain the smartlinks (so
it's kind of a reverse linking process; the result is visible at the
link destination, not at the source), so that you can see which part of
the synopsis is covered by which part of the tests.
The place where the implementation comes into play is that currently the
tests are also annotated with the information if they pass in pugs. This
requires pugs to report the line number of the tests (done through
caller() in Test.pm). Rakudo could certainly do the same once line
numbers and caller() are implemented.
However the real smartlinking process would always be done by an
external tool related to the test harness, which IMHO can continue to
live in the pugs repo (where the test suite also lives).
> But that says nothing about whether *Parrot itself* must have something
> called smartlinks. Parrot's source code is written in a variety of
> languages, each of which has its own documentation format. Do PIR and
> PASM need smartlinks? What would they do?
They would just be in the comments, and presumable link to the PDDs or
other documents. I don't know if you want that kind of "visual coverage
test", and if it's useful.
> My impression is that we have a bunch of code in our
> distribution/repository which someone, at some point in the past,
> thought would be a good idea to bring into Parrot because it had
> appeared in Pugs. This code is largely undocumented and, per szbalint's
> report, doesn't work.
>
> Is there any compelling reason to retain *any* of this code in Parrot?
> If not, I'll propose a patch to rip it out after this week's release.
As stated above, Rakudo doesn't need it. If we don't see a reason to use
it in parrot, rip it out.
Moritz
--
Moritz Lenz
http://moritz.faui2k3.org/ | http://perl-6.de/
Balint Szilakszi via RT
James Keenan via RT
>
> As stated above, Rakudo doesn't need it. If we don't see a reason to use
> it in parrot, rip it out.
>
> Moritz
>
See patch attached. The patch eliminates smartlink-related code from
Parrot, but does not touch anything in languages/.
kid51
Chromatic
> See patch attached. The patch eliminates smartlink-related code from
> Parrot, but does not touch anything in languages/.
It contains some commented out code that should probably just go away.
Otherwise, +1.
-- c
James Keenan via RT
Yes, this was a first version of the patch which I rushed out largely to
see what effect deleting the code would have on the Parrot and Perl 6
'make test' suites. (Answer: none, accounting for deleted tests.) My
plan is to fine tune it by also deleting some comments referring to
smartlinks in other tests such as t/pmc/object.t.
Thanks for taking a look.
kid51
Jerry Gay
i started the current smartlinks code as an experiment in using moose,
and as a reaction to the mess of smartlink code that's in the pugs
repo. however, i'm not married to the code, so rip it out if you
like--i never completed it, anyway.
a few things about the smartlink code currently in pugs that needs to
be addressed to work well with parrot:
* parrot both follows the parrot design documents, and the perl 6 spec
docs (mainly pge). this is not possible in pugs' system
* it should be well-tested. if pugs' system is used, hopefully the
tests can be used there as well
* it should be easily maintainable. i don't find the pugs' code easy to read.
i'd *love* to see smartlinks working in parrot. one of the big
problems in the parrot test suite is our lack of ability to measure
the test coverage of both code and spec. although smartlinks likely
won't offer us solid quantitative metrics, it will provide important
visual qualitative measures.
oh, one other thing--there was a comment about a perl 6 syntax for
smartlinks somewhere. that's outside the scope of this project, as all
the spec/design docs are written in perl 5 pod. it's something to
think about, but something we'll only address when we have a need
(perhaps when/if the spec docs are rewritten in perl 6 pod?)
~jerry
James Keenan via RT
> >
> parrot needs a way for us to measure spec coverage in our test suite.
> i started the current smartlinks code as an experiment in using moose,
> and as a reaction to the mess of smartlink code that's in the pugs
> repo. however, i'm not married to the code, so rip it out if you
> like--i never completed it, anyway.
>
>
> i'd *love* to see smartlinks working in parrot. one of the big
> problems in the parrot test suite is our lack of ability to measure
> the test coverage of both code and spec. although smartlinks likely
> won't offer us solid quantitative metrics, it will provide important
> visual qualitative measures.
Okay, here's what I propose we do:
1. I will examine the 12 unresolved tickets to see if there are any
which will not be automatically closable once my patch is applied.
2. I will apply a refined version of the patch. It will delete inline
comments referring to the deleted tickets. But I will leave to others
dealing with reference to smartlinks under languages/.
3. I will resolve/reject the unresolved tickets.
4. I will then open up a new RT of the [RFC] class. This ticket will
call for development of a specification of a way to visually display the
extent to which Parrot's tests cover the specification. I'll be quoting
from particle's post -- but I'm sure there will be additional questions
for Jerry. The spec will call for a way to test whatever code we
develop to meet the spec. So, rather than asking people to rush out to
write code, we'll focus first on determining what we want and need.
James Keenan via RT
>
> Okay, here's what I propose we do:
>
> 1. I will examine the 12 unresolved tickets to see if there are any
> which will not be automatically closable once my patch is applied.
>
Examination complete.
> 2. I will apply a refined version of the patch. It will delete inline
> comments referring to the deleted tickets. But I will leave to others
> dealing with reference to smartlinks under languages/.
>
Patch refined in nosmartlink branch. Am waiting for release before
merging to trunk.
> 3. I will resolve/reject the unresolved tickets.
>
Done.
> 4. I will then open up a new RT of the [RFC] class. This ticket will
> call for development of a specification of a way to visually display the
> extent to which Parrot's tests cover the specification. I'll be quoting
> from particle's post -- but I'm sure there will be additional questions
> for Jerry. The spec will call for a way to test whatever code we
> develop to meet the spec. So, rather than asking people to rush out to
> write code, we'll focus first on determining what we want and need.
>
TODO
James Keenan via RT
> comments referring to the deleted tickets. But I will leave to others
> dealing with reference to smartlinks under languages/.
Done, now that release has been cut.
>
>
> 4. I will then open up a new RT of the [RFC] class. This ticket will
> call for development of a specification of a way to visually display the
> extent to which Parrot's tests cover the specification. I'll be quoting
> from particle's post -- but I'm sure there will be additional questions
> for Jerry. The spec will call for a way to test whatever code we
> develop to meet the spec. So, rather than asking people to rush out to
> write code, we'll focus first on determining what we want and need.
>
Still TODO.
James Keenan via RT
> >
> > 4. I will then open up a new RT of the [RFC] class. This ticket will
> > call for development of a specification of a way to visually display the
> > extent to which Parrot's tests cover the specification. I'll be quoting
> > from particle's post -- but I'm sure there will be additional questions
> > for Jerry. The spec will call for a way to test whatever code we
> > develop to meet the spec. So, rather than asking people to rush out to
> > write code, we'll focus first on determining what we want and need.
> >
>
> Still TODO.
Done. So this RT is now resolved and superseded by # 58990.