Re: Referring to source code within Perldoc: the new A code
* Smylers ([EMAIL PROTECTED]) [070621 20:33]: Documentation, unlike code, doesn't have to be backwards compatible: if Perl 6.0.1 changes the API of a standard function that will break existing code; but if Perl 6.0.1 has documentation with a different structure from Perl 6.0.0, that won't break anything. When 6.0.1 changes the doc structure, then all 6.0.0 docs are unusuable, or need conversion. Although this doesn't cause code breaking, it does have maintenance and usability issues. Don't forget that Perl code is so compact that we (at least me) have more lines of doc than of code in our files. If you take documentation serious enough, you certainly do want (at least some) backwards compatibility too. And as much as possible automatic consistency checks/warrants. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Referring to source code within Perldoc: the new A code
Juerd wrote: This dedicated OO documentation must be core, because Perl itself is heavily OO. * Damian Conway ([EMAIL PROTECTED]) [070621 23:54]: Yes. I completely agree that such a tool not be standard and universally Do you mean must be i.s.o. not be? available. Just as the pod-to-whatever back-ends of the documentation chain must also be. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Referring to source code within Perldoc: the new A code
* Damian Conway ([EMAIL PROTECTED]) [070622 08:38]: And, no, I don't consider the pointers to your excellent module to be suitable specific examples of what we're not giving you...mainly because I believe that the Pod 6 documentation language I've designed (in conjunction with the ability for Perl 6 to parse Perl 6) *does* give you what you need to build such tools. Well, we tried to avoid the stale-mate discussion, but it's back again. IMO, POD6 should not provide the possibility to build such tools: it should *be* the tool. With a nice (compact) standard definition how to document each of the designed features in Perl6, and in attachment C some details which explain how Ben Smylers can live in anarchy ;-) So it seems we're still at an impasse. Nah, at least a lot more people are thinking about the subject now. I fully respect your decision not to attempt a full alternative design (if anything, your estimate of it only taking weeks is optimistic ;-), but unless someone is willing to step up and suggest some specific improvements to the current proposal, how can we move forward towards the best possible result? If you read it well, I say: it's a waste of time if the idea of orthogonalism (full code and doc separation) cannot be discussed. Because my plans are exactly the opposite: optimally merging doc and code. So, it is only a no when @Larry says no. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Referring to source code within Perldoc: the new A code
Mark Overmeer wrote: IMO, POD6 should not provide the possibility to build such tools: it should *be* the tool. With a nice (compact) standard definition how to document each of the designed features in Perl6 And this is a succinct statement of one half of our fundamental philosophical difference. The other half is that I still believe that Pod should be an enabler and medium for creating nice (compact) standard definitions of how to document Perl 6. I don't want to create One True Documentation scheme; I want to create a means to develop a range of True Documentation schemes...a range of schemes suited to different documentation goals, different paradigms, different source code structures, and different readers. Damian
Re: Referring to source code within Perldoc: the new A code
In article [EMAIL PROTECTED], Smylers [EMAIL PROTECTED] wrote: Juerd Waalboer writes: Smylers skribis 2007-06-21 21:33 (+0100): I disagree. perldoc.perl.org was started by JJ, gained popularity, and then got awarded the official blessing of the onion. Over the years there have many several sites with Perl documenation. That's not a way of documenting things, it's just an interface to existing documentation. There's no reason why it has to be. There are no barriers to anybody unofficially adding extra semantic information to the documentation and making it available on a website. The biggest barrier is that any work one does outside of the documentation source is likely to be wasted when new versions of the module comes out. Consider the Phalanx project for instance: they got a lot of people working to improve a lot of modules, and almost none of that work actually made it into the modules. The next biggest barrier is the size of the job. Who's going to go through all that documentation on CPAN and tag everything? I wouldn't even want to do it on all of my modules. There isn't a technical problem, but there is a huge social and pragmatic problem. It would be very nice if the documentation had a natural way to do this without extra-documentation clues from third parties.
Re: Referring to source code within Perldoc: the new A code
OK. After much thinking on the subject, here are my recommendations:
First: give Pod the ability to delimit blocks of ambient text, e.g.:
=text
class Foo {
has $bar;
}
=stop
'=text' and '=stop' would be considered to be separate but related
single-line Pod Sections, so Pod-stripping utilities would remove them
while leaving the lines between them intact. (I'm not sold on the
specific names for these tags; just the principles behind them.)
By default, 'A' searches backward from its current position within
the scope of the current ambient text block. This helps you catch
gotchas such as removing a piece of code and failing to remove the
documentation that was referencing it. Consider, for example,
documenting the first attribute of a class that follows another class.
The coder removes the attribute, but fails to remove the
documentation that references it. Suddenly, that documentation is
referencing the last attribute of the previous class. If each class
were encapsulated in a separate ambient text section, Pod would then
know to complain that there is no attribute to reference anymore.
--
Allow ambient text blocks to be named, and allow 'A' to choose a
named ambient text block to search. When you do this, the position of
the A tag relative to the ambient text block becomes irrelevant.
Example:
=begin pod
AFoo.has
=end pod
=text Foo
class Foo {
has $bar;
}
=stop Foo
You might also consider changing the rules when searching ambient text
blocks in this way, so that it searches for the first instance of the
prefix in the block instead of searching for the last one.
--
Let a pod section specify a default ambient code block, causing all
ambient references within its scope to automatically reference that
block:
=begin pod :AFoo
Ahas
=end pod
=text Foo
class Foo {
has $bar;
}
=stop Foo
--
Allow ambient text blocks to be nested:
=begin pod :AFoo
=ATTRIBUTE Ahas
=METHOD Amethod :Abaz
=NAME Aname
=RETURNS Areturn
=end pod
=text Foo
class Foo {
has $bar;
=text baz
method baz () returns Number { ... }
=stop baz
}
=stop Foo
--
Allow an optional array index for the prefix so that you can skip
over a given number of matches, rather than being limited to the first
one you find:
=begin pod :AFoo
Ahas[0]
Ahas[1]
=end pod
=text Foo
class Foo {
has $bar;
has $baz;
}
=stop Foo
--
Finally, there are cases where prefix handles won't be readily
available. Consider what happens when you try to document a C++
function:
extern void swap(int*, int*);
=NAME Avoid
=RETURN Aextern
How do you reference the 'extern' in that function definition?
Now let's say that the C++ programmer decides that he wants this
function to return a success flag:
extern int swap(int*, int*);
=NAME Aint
=RETURN Aextern
Note that he had to change 'void' to 'int' in two places: once in the
code, and once in the documentation. This, combined with the
distinctly unintuitive prefixes being used in the ambient references,
can lead to a real mess.
In cases such as these, it might be best to have Pod punt to an
'assistant parser' that returns the equivalent of a list of '=alias'
tags. I see this as being a case of All's fair if you predeclare,
and I was inspired by XML's Processor Instructions (conceptually) and
namespaces (syntactically). Using this, the above might be handled
as:
=parser C++ uri
...
=text swap :parsedC++
extern void swap(int*, int*);
=stop text
=for pod :Aswap
=NAME Aname
=RETURN Areturn
The '=parser' line tells Pod that some later ambient text sections
will be parsed using a C++ helper utility. It's assumed that Pod will
search for said helper utility, and will complain if it can't find it.
I'm assuming that the helper utility would return the equivalent of:
=alias name swap
=alias return void
when given the ambient text section in question. I'm also figuring
that these parser-generated aliases would take precedence over
prefix-based referencing, but that explicit '=alias' tags would take
precedence over them.
--
One ramification of Larry's earlier suggestion that Perl not handle
Pod sections exactly the same way that Pod does is that it's possible
for certain sections of Perl code to not register as ambient text in a
Pod Parser:
say qq:to(END)
=begin pod
oops
=end pod
END
=for pod
A=begin
To a Perl Parser, the code is as follows:
say qq:to(END)
=begin pod
oops
=end pod
END
To the Pod Parser, the ambient text is this:
say qq:to(END)
END
This wasn't a big deal when Pod was completely ignoring the ambient
text. But once it starts referencing ambient text, you're best off
keeping Perl code and Pod ambient text in sync with each other.
--
Jonathan Dataweaver Lang
Re: Referring to source code within Perldoc: the new A code
Mark Overmeer wrote: [...yet another honest and heartfelt plea for Pod 6 to be something entirely different from what it is currently designed to be.] The solution is simple, you know, Mark. Why not just write up your own alternate S26, redesigning Pod 6 the way you think it should work, and then publish your proposal for consideration here? After all, Larry's track record is clear: he's never once allowed someone's reputation or status (even his own!) to deter him from replacing an existing design with someone else's superior one. So, as you feel you have a better alternative, why not document it and put it before the community for consideration and assessment? If it is indeed better, I have no doubt we will happily steal it. Even if only parts of your proposal are better, your technological distinctiveness is sure to be assimilated. ;-) Damian
Re: Referring to source code within Perldoc: the new A code
In article [EMAIL PROTECTED], Damian Conway [EMAIL PROTECTED] wrote: Mark Overmeer wrote: [...yet another honest and heartfelt plea for Pod 6 to be something entirely different from what it is currently designed to be.] The solution is simple, you know, Mark. Why not just write up your own alternate S26, redesigning Pod 6 the way you think it should work, and then publish your proposal for consideration here? Couldn't most of this be figured out by making Pod6 extensible (or whatever the right term is). Pod6 would be more of the syntax and basic operation, but other people could have custom directives that their Pod6 translators and formatters could then use. That is, not all of this has to be in the spec if the spec has a way to make it possible later. :) And, as far as writing a new S26, does this mean that this really isn't open to discussion? That is, if we want something different than you want we have to have competing specs and there won't be any compromise?
Re: Referring to source code within Perldoc: the new A code
The outcome is that poddoc can be Pod6 pure and perldoc can be (as its name suggests) documentation for Perl. I failed to mention that it also has the benefit that developers can read the perldoc if they care about method details - or they could read poddoc if they only want a 7000 ft view (aka the executive summary). Paul
Re: Referring to source code within Perldoc: the new A code
The outcome is that poddoc can be Pod6 pure and perldoc can be (as its name suggests) documentation for Perl. Sorry to reply to myself twice. Making poddoc independent of Perl 6 opens the doors a little further for having pythondoc and phpdoc and yourlanguageheredoc which extract the POD tags ala poddoc and then add the inlined/introspectable documentation for that particular language. Now the only hard part is getting the other language designers to allow ignoring pod markup in their languages. All of the Parrot based variants could easily incorporate this feature. Paul
Re: Referring to source code within Perldoc: the new A code
Damian Conway writes: Here's the first draft (documented in Pod 6, of course ;-). Feedback and suggestions are most welcome. Note that C=alias is a fundamental Perldoc directive, like C=begin or C=for; it is Inot an instance of an Labbreviated block|#Abbreviated blocks. Hence there is no paragraph or delimited form of the C=encoding directive (just as there is no paragraph or delimited form of C=begin). I was with you right up until the mention of C=encoding; what's that got to do with anything? Smylers
Re: Referring to source code within Perldoc: the new A code
Smylers reported: I was with you right up until the mention of C=encoding; what's that got to do with anything? CP bug. Patched. Thanks! Damian
Re: Referring to source code within Perldoc: the new A code
Damian Conway writes: Here's the first draft (documented in Pod 6, of course ;-). =head3 Ambient aliases The CA formatting code specifies an Balias to an ambient antecedent. Please can you explain the reasoning for choosing antecedent, rather than successor? I'm not disagreeing with your choice, merely that it doesn't seem obvious to me that one is going to work better than t'other, so I'm open to being persuaded. In Perl 5 I generally intermingle Pod, such that when reading the source the description of a function or method comes before the code (so that by the time you've reached the code you already know what it's supposed to be doing) -- but I'm not adamant about continuing with this style. Smylers
Re: Referring to source code within Perldoc: the new A code
Juerd Waalboer writes: Damian Conway skribis 2007-06-21 11:45 (+1000): A dedicated OO documentation tool could certainly do a better job in that case, I heartily agree. I'm looking forward to using one. This dedicated OO documentation must be core, because Perl itself is heavily OO. That doesn't follow. If we are to ever have consistent, semantic, structured OO documentation throughout CPAN (and numerous in house projects), we must start with Perl itself, I disagree. perldoc.perl.org was started by JJ, gained popularity, and then got awarded the official blessing of the onion. Over the years there have many several sites with Perl documenation. Let the same thing happen with Perl 6: allow innovation, and if you, or Markov, or anybody creates a particularly fine site then people will admire it, use it ... and then perhaps it can be made official. There isn't really anything to be gained by pre-empting this and picking something initially. Documentation, unlike code, doesn't have to be backwards compatible: if Perl 6.0.1 changes the API of a standard function that will break existing code; but if Perl 6.0.1 has documentation with a different structure from Perl 6.0.0, that won't break anything. Also it's much easier for people to get the benefit of documentation improvements than of code improvements. If Perl 6.0.1 introduces a new feature then I need to upgrade from Perl 6.0.0 on all my computers to be able to use it; but if Perl 6.0.1 has improved documentation then I can read, browse, and search that documentation on its website without needing to upgrade any of my computers. Smylers
Re: Referring to source code within Perldoc: the new A code
Smylers skribis 2007-06-21 21:33 (+0100): That doesn't follow. It's an opinion. I disagree. perldoc.perl.org was started by JJ, gained popularity, and then got awarded the official blessing of the onion. Over the years there have many several sites with Perl documenation. That's not a way of documenting things, it's just an interface to existing documentation. It provides no semantic search featurewhatsoever, and can't, because Perl's documentation wasn't built like that. The documentation for CGI is very different from the documentation for IO::Socket::INET, although both are (can be) OO. That's okay if you read the things like a book, but structured documentation with structured interfaces allow readers to more easily use the documentation for reference. Let the same thing happen with Perl 6: allow innovation, and if you, or Markov, or anybody creates a particularly fine site then people will admire it, use it ... and then perhaps it can be made official. Sure, but it's a huge chicken-egg problem that doesn't have to exist. There isn't really anything to be gained by pre-empting this and picking something initially. I disagree very strongly. -- korajn salutojn, juerd waalboer: perl hacker [EMAIL PROTECTED] http://juerd.nl/sig convolution: ict solutions and consultancy [EMAIL PROTECTED]
Re: Referring to source code within Perldoc: the new A code
Juerd Waalboer writes: Smylers skribis 2007-06-21 21:33 (+0100): I disagree. perldoc.perl.org was started by JJ, gained popularity, and then got awarded the official blessing of the onion. Over the years there have many several sites with Perl documenation. That's not a way of documenting things, it's just an interface to existing documentation. There's no reason why it has to be. There are no barriers to anybody unofficially adding extra semantic information to the documentation and making it available on a website. Smylers
Re: Referring to source code within Perldoc: the new A code
Juerd wrote: Damian Conway skribis 2007-06-21 11:45 (+1000): A dedicated OO documentation tool could certainly do a better job in that case, I heartily agree. I'm looking forward to using one. This dedicated OO documentation must be core, because Perl itself is heavily OO. Yes. I completely agree that such a tool not be standard and universally available. Just as the pod-to-whatever back-ends of the documentation chain must also be. Damian
Re: Referring to source code within Perldoc: the new A code
brian asked: Couldn't most of this be figured out by making Pod6 extensible (or whatever the right term is). Pod6 would be more of the syntax and basic operation, but other people could have custom directives that their Pod6 translators and formatters could then use. That is, not all of this has to be in the spec if the spec has a way to make it possible later. :) Yes. That's exactly what we've done. Pod 6 has: =item a C=use directive that allows you to load behaviours for any user-defined blocks or formatting code you want =item a standard mechanism by which user-defined blocks are available (just make the block names mixed-case) =item a standard mechanism for adding new formatting codes (the M metacode) And, as far as writing a new S26, does this mean that this really isn't open to discussion? That is, if we want something different than you want we have to have competing specs and there won't be any compromise? Of course not. Indeed it's a *plea* for something more concrete to discuss, a suggestion of a way to get past the philosophical impasse of one group saying this does everything you want, without nailing down the specifics of how, whilst another says this isn't good enough, without clearly indicating what would be. What I was actually suggesting was that this design *isn't* set in stone, and that the best way to convince Larry that the existing design could be better is to actually offer a better design. Damian
Re: Referring to source code within Perldoc: the new A code
* Damian Conway ([EMAIL PROTECTED]) [070620 05:17]:
Feedback and suggestions are most welcome.
Clear and usable, in the boundaries you set to yourself.
Just my thoughts. A lot of questions and speculation, you do
not need to answer all. I'll try to only comment on this design,
and not restart our usual discussion.
role Transaction {
=alias class Arole
state Int $trans_counter;
=alias Vmy Int Astate Int
=DESCRIPTION
The Amy Int variable is used to track the total number of transactions
active at any one time. The value of Amy Int is incremented by the
Aclass CBUILD submethod and decremented by the Aclass destructor.
This is exactly the form of documentation you do *not* want the
user to write, for various reasons:
* it is stylish quite bad to repeat words like 'variable', 'class',
or 'method' in nearly every sentence. It makes manual-pages
painfully unpleasant.
* The explicit naming of the class name in method and attribute
descriptions is in general a bad idea: by inheritance, you get
sub-classes which also provide this method. In the people's
mind (I mean normal people, not our perl guru), this
requires continuous translations which distracts from the message.
h1class Transaction/h1
pThe transaction class defines the following methods and attributes./p
pThe $trans_counter variable is used to track the total number of
transactions active at any one time. The value of $trans_counter is
incremented by the Transaction BUILD submethod and decremented by
the Transaction destructor./p
pThe $max variable reports the number of Transaction objects which
are allowed to be processed in parallel. This is a constant value,
which defaults to 10./p
and so on. For many pages long. What, IMO, you want is a clean
and condensed way of expressing. At least I would prefer output
in this shape:
h1class Transaction/h1
pThe transaction class defines the following methods and attributes./p
ul
dtprivate attribute $trans_counter/dd
ddtracks the number of transactions actions active at any one time. The
value is incremented by BUILD() and decremented at Transaction
destruction./dd
dtpublic attribute $max (read-only, default 10)/dt
ddthe number of transactions are allowed to be processed in
parallel./dd
Concise, correct, and complete.
Of course, adapted to the features of the output channel, using
templates and style-sheets in the document generating tools.
* How do you see this syntactically work in combination with the
item list? At least the POD(5) needed that. I need a combined
example.
* Having aliases is pratical, for referencing. However, in this
latter example it is used to help the programmer to shoot himself
in the foot. If you allow people to say class each time they
mean role, or function where it is method, then on the long
run people will start making avoidable programming mistakes.
In the chosen approach, this abuse cannot be avoidable. But it
may be a wise not to promote it by using it as example.
* Using ambient back-references this way probably requires a
two-pass document generator. AFAIK this is not required for the
design of POD6 so far.
* the A(..) syntax is nice, but has a few dangers. Serious
problems. Your examples are a bit brief. A little larger:
method eat(Food $meal) {...}
=for DESCRIPTION
The Amethod() method has the following argument list: A(..)
Now the method gets implemented:
method eat(Food $meal) {
if($manger.isFull) { $manger.clean }
}
=for DESCRIPTION
The Amethod() method has the following argument list: A(..)
Oops... now the argument list became (without warning)
$manger.isFull So, either you impose a strict doc order, forcing
people into your style, or people have to use an alias everywhere,
bulking the file. More subtle examples of this problem can be
created, for instance when the method defines a return type
* In the manual-page of my sub-class, I want to refer to the
documentation of specific attributes and methods. How?
Can I also refer to elements in distributions which are not
mine, so where I cannot add X or such? For instance,
when I inherit from a core Perl class?
* In my sub-class, I want to enlist automatically the methods
and attributes which are inherited. Automatically of course,
because I want to avoid mistakes. In case of multi-level
inheritance, some way I need to know and show where each is
defined. How?
For instance, if your look at IO::File in Perl5, it defines
some own method, but then simply says: see also IO::Handle
and IO::Seekable. IO::Handle says: see also perlfunc and
perlvar. The more extended your OO model is, (Perl6's
structure is probably much more extended), the more levels
of hierarchy you get. Are users able to
Referring to source code within Perldoc: the new A code
Here's the first draft (documented in Pod 6, of course ;-).
Feedback and suggestions are most welcome.
(But please don't bother explaining to me this feature won't suffice
as the high-level automatic code-to-documentation mechanism that Markov
has been championing. I promise that I'm very well aware of that fact.
This new formatting code isn't intended to replace such advanced
autodocumentation tools...only to make such tools unnecessary in the
simple cases and--in the non-simple cases--to make such tools easier to
create, by providing a symbolic intermediate-level representation for
interwoven code and Pod.)
Damian
-cut--cut--cut--cut--cut-
=head3 Ambient aliases
The CA formatting code specifies an Balias to an ambient antecedent.
This is like a Lplacement link|#Placement links, except
that the text that is inserted to replace the CA formatting code is
some portion of the Lambient section(s)|#General syntactic structure
of the current document, rather than the entire contents of some
external document.
Hence, the CA code makes it possible to incorporate pieces of
ambient text (typically source code) into Pod documentation.
Specifically, the CA code is replaced by searching backwards through
all preceding non-Pod parts of the document, to locate the nearest prior
substring that matches the contents of the CA code.
The contents of an CA code can specify a back-reference of this type
in one of two ways:
=item as a Iprefix keyword, or
=item as a Idelimited text range.
By default, CA aliases are keyword oriented. That is, the contents
of an CA block are treated as a keyword or prefix that introduces
the desired text. That text is located by searching backwards from the
location of the CA code, to find the nearest preceding instance of
the specified prefix in any previous ambient block. The text that is
then used to replace the CA is the first symbol following that
located prefix. In this context, a symbol is defined as a sequence of
non-whitespace characters terminated by a transition from an identifier
character to a non-identifier character.
For example, in the following:
=begin code
class Pet {
has $name;
=DESCRIPTION
The class Aclass provides a Ahas attribute.
=end code
the CAclass formatting code would be replaced by Pet, since that
is the sequence of non-whitespace characters that immediately follows
class in the preceding ambient source code. Likewise, the CAhas
formatting code would be replaced by $name, because that is the
longest sequence of non-whitespace characters that follows a has and
terminates in an identifier-to-nonidentifier boundary.
=begin para
=config C :allowR
In other words, any formatting code of the form CARprefix
is replaced by the substring of the nearest preceding
ambient block that matches the pattern:
=end para
=for code :allowR
/ .* Rprefix \s* ( \S*? \w ) [\W | $] /
This default is designed to work well for the commonest kind of
back-reference in ambient text: a reference to a code construct that
was defined using a prefix keyword and whose name ends in an identifier.
The second and more general way of specifying an alias is to specify
both a prefix and a postfix delimiter for the replacement text. If the
contents of an CA formatting code include a range marker (C..),
the sequence before the C.. is treated as the left delimiter of the
replacement text, and the sequence after the C.. is the right
delimiter. In this case, there are no other constraints on the
replacement text. In particular, it may contain any number of non-
identifier or whitespace characters. For example:
class Pet {
method eat(Food $meal) {...}
=for DESCRIPTION
The Amethod() method has the following argument list: A(..)
This would be interpreted as:
The eat() method has the following argument list: Food $meal
because the CA(..) specifies an alias to the closest preceding ambient
text that is left-delimited by a '(' and right-delimited by a ')'.
To specify an alias in which the sequence C.. is itself
a left- or right-delimiter (rather than the separator between the two),
use a CV code:
constant @range = 0..99;
=para
The maximum value is AV;
=head4 Explicit aliasing
The replacement strings for CA formatting codes are normally
specified implicitly, by the closest preceding ambient text that matches
the contents of the CA code.
However, it is possible to override this behaviour and create an
Iexplicitly defined alias, using the C=alias directive:
class Agent {...}
=alias component Agent
class Transaction is Activity {
=DESCRIPTION
The Aclass class represents a transaction activity between two
Acomponent objects.
In the preceding example, CAclass is a normal keyword alias
(which would be replaced by the closest preceding prefixed match:
Transaction). However, CAcomponent is a defined alias
(which would be replaced by the explicitly
