On Sun Sep 14 12:17:51 2008, szbalint wrote: > 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. Thank you very much. kid51
