Carl observed:
Partly that is because documentation isn't at the forefront of things
that need to be implemented for Perl 6 to be useful, so it's kind of
lagging behind the rest.
Partly it's because Damian is the "owner" of that synopsis, and he
practices a kind of "drive-by-updating" to it. As a case in point of
this latter effect, the extensive changes made by Damian in August
*still* haven't hit the Pugs repo.
The latter is entirely true but, fortunately, also very easily remedied.
I hereby disclaim all present and future "ownership" of S26. :-)
By all means put the latest update on the repo (or maybe remove S26
entirely), and start redesigning it collaboratively.
Please note that I am not in any way upset, angry, petulant, or
otherwise disaffected. I only want the very best for every aspect of
Perl 6. If the experience of respected and active developers suggests
that Pod 6 isn't a step in the right direction, I can only feel
disappointed in myself, apologize for my failure, and gratefully turn
the task over to those with better ideas and more time and energy to
devote to the problem.
As regards Pod vs Pandoc (which is pretty clearly the leading
contender of the structured text notations), I do think Pod has some
decided advantages. For example, I feel it's better to have four basic
metasyntaxes (X<>, =IDENT, :OPTION, #=) and most with identifier-based
labels, than to have over two dozen (plus embedded HTML and TeX) all
with symbolic labels.
I guess I feel that Pandoc/Markdown/ReST/etc. are optimized for writing
documentation "source", whereas Pod is optimized for reading
documentation "source". I'm not sorry I aimed for the latter, whatever the
deficiencies in the result.
Carl also suggested:
I think that the future of S26 is very much dependent on whether it'll
be able to respond to the needs of Perl 6 developers. Right now it
doesn't respond to much of anything.
Outwardly this is self-evidently true. One need only look at the (lack of)
commit log for S26. :-(
Inwardly, something else entirely is happening. A design(er) can only
respond effectively when subjected to a clear net force pushing or
pulling in some well-defined direction. The redesign of Pod has been
subject to an enormous number of such forces. Unfortunately they push
and pull it in every possible mutually contradictory direction, thereby
producing very little overall impetus.
So I would encourage those of you who are going to collectively take
over the shepherding of this synopsis to go back through the p6l
archives and review the many many posts commenting on and requesting
features for Perl 6 documentation.
In particular, please look carefully at the very different needs of
those who document OO code, procedural code, frameworks, modules,
applications, design documents, presentations, and Perl itself. You will
find that many of these contributors ignore, discount, or actively
disparage the needs of their fellow users.
For example, in this very thead:
I'm not writing a book, I'm writing code. And if I was writing a book,
I wouldn't be dumb enough to write it in POD.
Yet what is the Perl documentation itself but a series of book chapters?
And surely that documentation is the largest single use of Pod anywhere?
Should we not write Perl's own documentation in Perl's own documentation
notation? Should we really discourage the use of standard headings to
consistently mark the common components of these (and most other)
Perl-related documents?
I sincerely hope that the future community of designers of Perl 6 's
documentation format will find a way to honour and support the very
different needs of *all* the creators and users of Perl, not just the
needs of the most prominent, or the needs of the most experienced, or
the needs of the most loquacious.
I have always thought that was the *real* challenge
of post-modern language design.
Damian
