* Richard Hainsworth ([EMAIL PROTECTED]) [070702 17:06]:
> Having read this posting, I find it VERY hard to understand exactly how
> Damian and Mark differ fundamentally. They both seem to be after the
> same thing in the end.
Damain defines a markup language, and says that "tools" (to be defined)
will do the actual work. I try to define the needs to create good tools
first. The unspoken conclusion from my list must be that POD6 is not
bringing us closer to the goal than POD(5) does, because most of the
needs are not answered in that design.
> A rhetorical question of my own and an answer.
> Q) what is the real difference between comments and documentation?
> - Syntactically for the perl parser they are both white space.
> - Both are used to explain the code.
Docs are for end-users, which do want to use the code but were
the internal organization is a black box. Comments explain code
where it is not obvious for maintainers, looking at the guts.
> Questions:
> 1) Would it be possible to unify all comments and documentation into a
> single paradigm, such as a sort of bracketting convention with optional
> extra information for other tools to use, eg., layout information,
> grouping information, context (viz., for a tutorial, or reference)
> information?
All are forms of text, so yes. However, probably you loose more than
you win, because, as you said yourself: their purpose is very different.
When you forcefully merge unrelated things, you add complexity.
> 2) Would it be possible for the brackets to have different 'opacities'
> for the perl parser, so that code can be recognised both as code and as
> documentation with extra information? In this way, code would be
> included in some forms of documentation (eg., function signatures in
> reference manuals) just by placing "transparent" documentation brackets
> around them.
Actually, for commenting code you probably already use invisible brackets:
you put comments on seperate lines before a piece of code, and when the
next comment block starts, the previous ends.
> 3) Would it be possible for the brackets to have 'opacities' for the
> perl parser that can be set by the value of some variable, hence
> debugging / tracing code could be switched on by setting that variable
> in the code?
Are you merging the idea of assertions with documentation here?
> 4) Is there a means for specifying the way documentation is reassembled,
> eg., a means for defining for say a tutorial a different structure than
> the linear structure of the documentation strings within the software?
I would like to put this responsibility in the back-ends, with a
big "YES".
> c) Am I wrong in thinking that implementing the suggestions in the
> questions should not require a substantial redesign of perl6?
There is no need for any redesign.
> d) If what I have suggested can already be done with Pod, could some
> examples be shown.
I have asked for more extensive demonstrations how POD6 would
be used, but uptill now only saw very small documentation fragments.
But IMO, POD6 is not the problem: it's just not the solution.
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
