* Damian Conway ([EMAIL PROTECTED]) [070621 01:45]:
> Mark Overmeer wrote:
> >This is exactly the form of documentation you do *not* want the
> >user to write, for various reasons:
> Well, I agree it is the form that "you" (singular, specific) do not want;
> but I'm not sure it's bad for "you" (plural, generic) to write in all
> cases. ;-)
My idea was "you" as lazy Perl programmers (most of us), against
"you" as orthodox orthogonalists :-b
> > * 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.
> A dedicated OO documentation tool could certainly do a better job in that
> case, I heartily agree. I'm looking forward to using one.
OODoc achieves this with POD(5)syntax with extra logical markup tags.
It's a simple tool, with simple syntax. So, I would say: try it!
Read OODoc::Parser::Markov first.
It sounds as if you think that OO/Grammar will be rarely used. That
there is no need to help users document it.
> > * 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.
> I'm not sure I understand what you're asking here. Can you describe the
> example you'd like to see?
In POD(5) you do
=over 4
=item myfunction1
some description
=item myfunction2
some description
=back
How would this small example (blanks removed) work in POD6?
> > * 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.
>
> Actually a two-pass generator is already required for Pod. A second pass is
> always necessary whenever there are any forward-targetted L<#local link>
> formatting codes in a document.
The is a simple strategy to avoid a second pass in this case. Probably
you (signular form) found a special case that this does not work.
> > method eat(Food $meal) {
> > if($manger.isFull) { $manger.clean }
> > =for DESCRIPTION
> > The A<method>() method has the following argument list: A<(..)>
> > Oops... now the argument list became (without warning) "$manger.isFull"
>
> Sure. But this is true of any scheme that doesn't do full parsing of the
> ambient source code. Which Pod isn't going to do
That's doesn't make this less of a problem. I think it is a wide open
user trap.
> > * 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?
>
> This is not possible, using this mechanism, due to the lexical scoping of
> the aliases. An automatic documentation-generator tool (that produces Pod)
> is more appropriate for this task.
Of course, I can make OODoc produce POD6. However, in a new
generation of the documentation syntax, I would really have liked
to have higher level features, for instance with which we can
produce docs with many links (like HTML), not poor section references
like traditional manual pages.
> > * In my sub-class, I want to enlist automatically the methods
> > and attributes which are inherited.
>
> An automatic documentation-generator tool is more appropriate for
> this task too.
For each little bit more complicated than the straight-forward task,
you say: let some external tool do that. Each of these spots is
a weak point in your orthodox orthogonal approach, where you ask
people to install and learn more tools, adding needless complications
to the development process.
The major disadvantage of external tools is, of course, their
incompatible results. Perl's set of manual-pages will continue
to be messy.
> =Definition
> method eat(Food $meal) {...}
>
> But with that slight change in syntax you could then use the standard Pod
> parser to segment your document into mark-up and ambient code, search the
> resulting object tree for 'Definition' nodes, grab the immediately
> following ambient code block, parse it using Perl 6's own grammar, then
> autogenerate content for the next 'DESCRIPTION' node in whatever form you
> would like it to be, using information extracted from the parsed code.
Wow, sounds really simple to implement. No.
> Or, since the Perl 6 grammar can preserve Perl comments in the parse tree,
> you could even create a tool that understood an abbreviated notation such
> as:
> method eat(Food $meal) {...} #=Definition=#
Oh yes! Now you gave me a way to implement my idea!
> method eat(Food $meal) {...}
#= let a human empty his/her plate
Introspection to produce the manual pages, piece of cake... no
interactive user tools needed. Maybe some macro which s/^\s\`/#= /
and all my needs are implemented!
> The point is: the design of Pod allows you to use *any* of those
> alternatives. It does that by providing a simple and extensible mark-up
> notation, an efficient parser for that notation, and good integration with
> Perl itself, so you can build whatever kind of documentation tools you find
> most useful.
Now I have to disagree: if you explain how to compile parts of Perl6
to collect the info to produce my man-pages, then I do not think that
POD6 is to be prized for its contribution.
....by providing a simple certainly not the simpelest
and extensible mark-up yes, sure
an efficient parser probably, but not needed: runs once
good integration with Perl no, certainly not IMO
so you can build whatever kind of documentation tools you find most useful.
... so everyone is left on their own to fix the features
> In other words, in designing Pod I'm attempting to create something at the
> abstraction level of RTF or LaTeX or XHTML,
Yes, just another syntax to do get the same possibilities and limitation.
> ... not something analogous to MS Word or Maple or HyperCard.
That would be a shame.
> That is: something that you can use directly
> for simple tasks, and something you can also build tools on top of...to
> handle more sophisticated requirements.
... and then we are back again to the old story: in my believe, the
structural consistency that POD6 offers is too little to create
really nice documents from.
> >In this case, the Perl and POD are using the text in the file
> >in an overlapping way, but still the Perl6 and POD6 parsers are
> >fully separate.
>
> That's not the case. As Larry has confirmed recently, to each parser (perl6
> or Perl6::Pod::Parser) everything in a source file will be either Perl or
> Pod (and never both). And the only place where the two parsers will
> disagree is inside a Perl string that happens to contain a Pod block.
Well, that is just a choice; the choice you defend as well. It is
nothing more than a choice. It is not a necessity. Even a strong
religious groups like Python is not this orthodox: they have their
__doc__ attribute in their syntax tree, and """ where I use ` / #=
This choice make life much harder to everyone (IMO, of course)
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
