Re: Gripes about Pod6 (S26)
a) How many of the gripes are affected by Damian's new draft ? I found many of my pet irritations were eliminated by the new one. b) I suggest that Damian's new draft is committed as S-26 forthwith and development begin on it. c) Some of the comments in threads on documentation have been more aggressive than any of the other perl6 development discussion. More courtesy would be more productive. d) The S-26 document - I think - needs a section at the beginning stating the design goals for the documentation system. Documentation can be written for more than one purpose and not all purposes can be catered for at the same time with a simple specification. By stating goals, it will be clear why and where compromises have to be made. Richard Damian Conway wrote: 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
Re: Gripes about Pod6 (S26)
Damian (), Carl (): 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. :-) Thank you. I do want to stress that I, despite my doubts and criticisms in this thread, appreciate all the time and effort you've put into S26. It is *because* I want the best for that synopsis that I brought up the above. Whether the ownership thing was actual or perceived -- and your email indicates the latter -- it did put S26 very much outside of the flow of piecemeal improvements that we take for granted in the other spec files. By all means put the latest update on the repo (or maybe remove S26 entirely), and start redesigning it collaboratively. I now put the latest update on the repo. 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. Again, thanks for your efforts so far. The discussions over the years have shown at least me what an ungrateful task it is to be redesigning Pod for Perl 6. // Carl
Re: Gripes about Pod6 (S26)
On Fri, Feb 12, 2010 at 14:57, Carl Mäsak cma...@gmail.com wrote: Again, thanks for your efforts so far. The discussions over the years have shown at least me what an ungrateful task it is to be redesigning Pod for Perl 6. Yep, thanks, Damian! Fortunately, doing _whatever_ for Perl 6 seems to be mostly a grateful task, AFAICT. -- Jan
Re: Gripes about Pod6 (S26)
On Wednesday 10 February 2010 at 13:49, Patrick R wrote: Actually, it's worth noting that (a slightly modified version of) Perl 5 POD has indeed been used to write several substantial books. I'd be very sad if (Perl 6) POD couldn't be easily used or converted into something that can be used to generate manual pages and reference documentation. I've written and edited several of these books. I'm happy to discuss features and misfeatures and scaffolding I've used to make POD suitable for writing and editing books. Perl 5 POD isn't too far off, but it does lack some important features. For the curious, the Modern Perl Github repository has a book in progress; see the tools/ directory for some hint of the necessary scaffolding: http://github.com/chromatic/modern_perl_book/ (Writing a book isn't too far different from writing documentation; many similar concerns apply.) -- c
Re: Gripes about Pod6 (S26)
On Wed, 10 Feb 2010, Jon Lang wrote: John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That's one of the things that's always annoyed me with Markdown; I think it should be *bold*, /italic/, and _underline_. :) - | Name: Tim Nelson | Because the Creator is,| | E-mail: wayl...@wayland.id.au| I am | - BEGIN GEEK CODE BLOCK Version 3.12 GCS d+++ s+: a- C++$ U+++$ P+++$ L+++ E- W+ N+ w--- V- PE(+) Y+++ PGP-+++ R(+) !tv b++ DI D G+ e++ h! y- -END GEEK CODE BLOCK-
Re: Gripes about Pod6 (S26)
On Feb 12, 2010, at 19:57 , Timothy S. Nelson wrote: On Wed, 10 Feb 2010, Jon Lang wrote: John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That's one of the things that's always annoyed me with Markdown; I think it should be *bold*, /italic/, and _underline_. There's a school of thought, common among printing/publishing types, that insists that underline was intended solely to replace italics when they couldn't be represented (i.e. no fonts, as with ASCII terminals and printers). Thus Markdown's use of _italic_. (See also nroff.) -- brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu electrical and computer engineering, carnegie mellon universityKF8NH PGP.sig Description: This is a digitally signed message part
Re: Gripes about Pod6 (S26)
On Fri, 12 Feb 2010, Brandon S. Allbery KF8NH wrote: On Feb 12, 2010, at 19:57 , Timothy S. Nelson wrote: On Wed, 10 Feb 2010, Jon Lang wrote: John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That's one of the things that's always annoyed me with Markdown; I think it should be *bold*, /italic/, and _underline_. There's a school of thought, common among printing/publishing types, that insists that underline was intended solely to replace italics when they couldn't be represented (i.e. no fonts, as with ASCII terminals and printers). Thus Markdown's use of _italic_. (See also nroff.) I'm aware of that idea, and don't use underlining myself for that reason. But since /italic/ looks like italic, and _underline_ looks like underline, why are we using the thing that looks like underline for italics? I mean, sure, I'm happy to get rid of _underline_ if that's what people want, but using _ for italic is just ... well, I don't see any sense in it. :) - | Name: Tim Nelson | Because the Creator is,| | E-mail: wayl...@wayland.id.au| I am | - BEGIN GEEK CODE BLOCK Version 3.12 GCS d+++ s+: a- C++$ U+++$ P+++$ L+++ E- W+ N+ w--- V- PE(+) Y+++ PGP-+++ R(+) !tv b++ DI D G+ e++ h! y- -END GEEK CODE BLOCK-
Re: Gripes about Pod6 (S26)
On Fri, Feb 12, 2010 at 10:12 PM, Timothy S. Nelson wayl...@wayland.id.auwrote: There's a school of thought, common among printing/publishing types, that insists that underline was intended solely to replace italics when they couldn't be represented (i.e. no fonts, as with ASCII terminals and printers). Thus Markdown's use of _italic_. (See also nroff.) I'm aware of that idea, and don't use underlining myself for that reason. But since /italic/ looks like italic, and _underline_ looks like underline, why are we using the thing that looks like underline for italics? I mean, sure, I'm happy to get rid of _underline_ if that's what people want, but using _ for italic is just ... well, I don't see any sense in it. If I recall correctly, this was a limitation of typewriters. Typewriters were incapable of displaying italics so underlining was taught as a replacement, though italics are/were considered the professional format. I somehow doubt that Markdown chose the _ for italics for that reason, though I will say that wayland's suggestion just makes more sense. -Jason s1n Switzer
Re: Gripes about Pod6 (S26)
Austin ():
I've been doing a bunch of NQP and PIR coding, where Pmichaud++ has been
trying to support some kind of POD syntax. With the release of the S26
draft, he has tightened the parsing to follow more of the rules laid out in
the spec, and after a few months, I've noticed that the trend (for
not-quite-pod) is definitely getting worse. POD 6 isn't very nice. It
certainly isn't an improvement on POD 5.
To be clear, by not an improvement on POD5 what I mean is I have
abandoned POD6 in favor of block comments.
I read your email and thought wow, this is very much like an email
thread I hoped to start on p6l.
[...] Far
better to write #={ despite how ridiculous that is to type, than to consider
using (or better yet ''' which isn't shifted).
Having used the #={ syntax consistently through one of my projects
(Druid), I can only agree wholeheartedly. Look:
http://github.com/masak/druid/blob/2c02e2a26a5fff6ec1d2f47b2c28d7ad2435e359/lib/Druid/Game.pm
It was an interesting thing to try, and I'd love if doing it like that
would somehow produce an HTML file à la JavaDoc, but right now there's
only disadvantages to writing doc-comments like that: it looks
jarring, both from the combination of of characters -- a complaint I
don't normally have in Perl -- and the syntax highlighter (in vim as
well as on Github) goes haywire. I can look at the comment syntax in
other languages and say that they fit in with the rest of the
language. I cannot say that about #={} in Perl 6.
Taking a step back, I think that S26 suffers from being at a stage
where much of the rest of the specification was in about 2005. It
contains a lot of good ideas, but also many rough edges stemming from
non-obvious corner cases and things that simply don't work in
practice. It's in need of a bit of a killing of darlings.
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. (The same situation can be seen with
S17-concurrency, S19-commandline and S22-package-format, to name a
few.)
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.
http://www.nntp.perl.org/group/perl.perl6.language/2009/08/msg32352.html
http://perlcabal.org/syn/S26.html
As a consequence, whereas many of the other synopses are happily
ticking along, getting small improvements on a daily basis, S26 just
sits there in a kind of limbo. It doesn't get one bit of feedback from
the things people learn from actually using it. That's just a pity.
Austin, many of the rest of your point went above my head, either
because I don't have the same knowledge about other documentation
formats as you do, or because I don't share the exact same practical
experience in writing Pod 6. But 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. I hope that changes.
// Carl
Re: Gripes about Pod6 (S26)
Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ My plan is to keep writing my own various docs in Pandoc Markdown (regardless of what programming language I'm working in at the moment), and if I *really* need POD5 or POD6, just use Pandoc to convert them to html, and then find a module on the CPAN to convert the resulting html to POD5 or POD6 (Pandoc doesn't currently convert directly to either Pod). I encourage others to do the same. It's funny; the Python folks left their previous doc format (LaTeX), and went (IMO) in the right direction, but ended up going with the less attractive [reST] rather than Markdown. [reST]: http://docutils.sourceforge.net/rst.html ---John
Re: Gripes about Pod6 (S26)
* John Gabriele (jmg3...@gmail.com) [100209 14:31]: [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ [reST]: http://docutils.sourceforge.net/rst.html Or, more Perl like: [OODoc] http://perl.overmeer.net/oodoc/ http://perl.overmeer.net/oodoc/html/jump.cgi?OODoc_Parser_Markov62 -- MarkOv Mark Overmeer MScMARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Gripes about Pod6 (S26)
On Wed, Feb 10, 2010 at 8:50 AM, Mark Overmeer m...@overmeer.net wrote: * John Gabriele (jmg3...@gmail.com) [100209 14:31]: [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ [reST]: http://docutils.sourceforge.net/rst.html Or, more Perl like: [OODoc] http://perl.overmeer.net/oodoc/ http://perl.overmeer.net/oodoc/html/jump.cgi?OODoc_Parser_Markov62 It's interesting to me that language implementations very often have their own NIH doc markup formats. For example: * Perl 5: POD * Perl 6: Pod * Python: reST * Ruby: rdoc * PLT Scheme: Scribble * Java: Javadoc I think Haskell may have something that their Haddock program uses. Also, IIRC, C and C++ users often use doxygen (though I realize that tool can be use with other languages as well). I used to wonder why these languages just don't use some generally accepted generic standard, such as LaTeX, Texinfo, or Docbook, or maybe even the MoinMoin wiki syntax (which is fairly common among wikis). After having used almost all of those tools, what I found was that: * it's tiresome to have to re-learn each different format if going back to edit old docs (or other people's docs) * it's a bother to have to set up my editor for every different format (and syntax highlighting doesn't always work right) * I tended to always come back to the simplest (and prettiest) thing that worked (Pandoc's Markdown) * I often ended up looking at my docs in `less` instead of taking the time to convert them to some other format for better viewing * many forums and blogs already use Markdown, most people already know it, many often use it without even knowing it Also though, interesting aside: Parrot is already at v2.0.0. It supports many languages. It's possible that someone might want to contribute docs to more than one of its hosted language implementations, so, using a common doc format might be desirable. Parrot also is often thought of as being very Perl-centric. Having it's biggest most sophisticated project use a common simple doc format might help shed that perception. ---John
Re: Gripes about Pod6 (S26)
On Tue, Feb 9, 2010 at 9:31 AM, John Gabriele jmg3...@gmail.com wrote:
Personally, I've always thought that Perl has a very natural feel to
{snip}
Gah. Sorry for the quasi-double-post. I posted on google groups, it
didn't show up, then I jumped the gun and posted a similar message to
the ML.
---John
Re: Gripes about Pod6 (S26)
John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That said, Markdown doesn't go far enough in this regard, even with the Pandoc revisions: for instance, there's nothing equivalent to C or R in Markdown. I'm very much in favor of revising Perl 6's documentation system to more closely resemble Markdown; but I'd strongly recommend going through the list of Pod 6 inline tags and seeing how much of that can be reasonably implemented in a Markdown-like fashion. And Markdown gives you nothing in terms of determining how to go about embedding documentation within a code file: for that, you'd still need something along the lines of Pod 6's =begin/=end, =for, and even #=. That said, if a Markdown-like syntax were to get implemented, it might be possible to do away with documentation-specific delimiters, relying instead on the standard comments. I have more thoughts on this; but they'll have to wait for a bit. -- Jonathan Dataweaver Lang
Re: Gripes about Pod6 (S26)
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
Re: Gripes about Pod6 (S26)
On Fri, Feb 05, 2010 at 03:43:04PM -0500, Austin Hastings wrote: Second, POD is not XML, and it definitely isn't DOCBOOK. Why do I need magic reserved words like TOC and APPENDIX? 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. Actually, it's worth noting that (a slightly modified version of) Perl 5 POD has indeed been used to write several substantial books. I'd be very sad if (Perl 6) POD couldn't be easily used or converted into something that can be used to generate manual pages and reference documentation. Pm
Re: Gripes about Pod6 (S26)
Personally, I've always thought that Perl has a very natural and
well-worn feel to it, and deserves a doc markup format that also feels
natural. What works very well for me is [Markdown] (and [Pandoc]'s
Markdown has mostly just the right additions, IMO).
[Markdown]: http://daringfireball.net/projects/markdown/
[Pandoc]: http://johnmacfarlane.net/pandoc/
(Note: Pandoc is written in Haskell. For anyone who's interested, I
put up some quick notes on installing Haskell + Pandoc specifically
onto Ubuntu 9.04 at
http://unexpected-vortices.com/docs/doc-notes/installing-pandoc.html.)
My own plan is to keep writing my docs in Pandoc Markdown (regardless
of what language I'm working in at the moment), and if I *really* need
POD or Pod, I'll just use Pandoc to convert them to some intermediate
format, and then find a module on the CPAN to convert *that* to POD or
Pod. I encourage others to do the same.
Further, for API-style docs, I've been experimenting with extracting
specifically-marked markdown-formatted code comments and then passing
them through pandoc. For example, maybe something like this:
#
# forage
# --
#
# This function will hunt around for any
# nuts that may or may not be present on
# the system.
#
# *Warning:* Not compatible with most
# squirrel-related modules.
#
# Args:
#
# * search-radius: default is 5 meters
# * default behaviour if confronted by cat ...
#
#
sub forage {
# ...
}
It's funny; the Python folks left their previous doc format (LaTeX),
and went in the right direction (IMO), but ended up going with the
less attractive [reST], rather than Markdown.
[reST]: http://docutils.sourceforge.net/rst.html
---John
Gripes about Pod6 (S26)
Howdy,
I've been doing a bunch of NQP and PIR coding, where Pmichaud++ has been
trying to support some kind of POD syntax. With the release of the S26
draft, he has tightened the parsing to follow more of the rules laid out
in the spec, and after a few months, I've noticed that the trend (for
not-quite-pod) is definitely getting worse. POD 6 isn't very nice. It
certainly isn't an improvement on POD 5.
To be clear, by not an improvement on POD5 what I mean is I have
abandoned POD6 in favor of block comments.
I don't have a rewritten S26 to offer - sorry - but I do have some
thoughts on why.
There are a couple of things about POD5 that I didn't like. The biggest
one, by far, was extra newlines. That got better over time, either
because I changed my writing style or because the parser got smarter - I
never tried to figure out which. The other big thing was no tables,
which is definitely fixed (-ish) in POD6.
That said, POD5 was a lightweight, easily understood format. It was easy
to figure out that there was text mixed with the code, and the
delimiters were cute little = signs with some semantics attached to
them, rather than just /* ... */.
But /* ... */ would work - as it does for Javadoc and Doxygen.
With S26, there are definitely some things I am happy to see. Tables.
Tables! Paragraph blocks. Attributes and out-of-band stuff. But there's
an awful lot of bad, too.
First, POD is not HTML. I absolutely hate =end tags. I can understand
the need for a general purpose multi-line comment, but as things
currently stand =begin/=end happens too much. Worse, for the kind of
short-but-multiple-paragraph comments that get attached to function and
methods, the extra-newlines tax gets pretty high.
In general, I think I'd like some way for POD to be in sticky mode --
that is, like POD5, it should either stay in POD, or stay in a
particular block type, until told otherwise. This might be a block
attribute -- that is, something I can configure separately:
=config default :likepara
=config para :sticky
Second, POD is not XML, and it definitely isn't DOCBOOK. Why do I need
magic reserved words like TOC and APPENDIX? 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. If @Larry wants to prove something by writing books in
POD, let them type =begin or =for or =whatever in front of their chapter
markers -- leave my namespace alone.
Third, I think that S26 is trying to approach a couple of pretty
important new(-ish) concepts in software -- inline documentation, and
annotations -- from a POD standpoint. I'm willing to listen, but I'm not
entirely convinced that it's possible, or that it's a good idea.
There was a flurry of discussion right after Damian posted his S26 draft
about short syntax for documenting syntax elements. The focus seemed to
be on making it something that POD could grab.
I'm not sure I accept that focus, especially since P6-language seems to
have some kind of bias against admitting anybody ever did any syntax
right after 1979. Docblocks have been around for a long time, but nobody
even considered literal-string-after-{ or as being valid ways to
indicate them. Far better to write #={ despite how ridiculous that is to
type, than to consider using (or better yet ''' which isn't shifted).
Overall, my impression of S26 is that it's not Perly enough. The idea of
paragraph blocks (=for...) is pretty clearly a compromise between
single-line and multi-paragraph, and it's a step in the right direction.
But I think there needs to be a better consideration of the needs of the
people writing the POD, expressed maybe as explicitly reserved bits with
known behaviors. (For example, some set of contexts where POD5-style
parse until I tell you to stop allows omission of =end markers, and
lets =foo stand for =begin foo.)
Also, =for just doesn't scan in a lot of places. Maybe a better way
would be to depend on the text, or to add an =.
=for para
blah blah blah
=config para :modeparagraph
=para
blah blah blah
=para -- no text means para mode?
blah blah blah
==para -- == means para mode?
blah blah blah
One thing I have noticed in NQP is that usually I write a function
signature, and it's right. That is, I can write the signature and it
corresponds with how the caller will use it. In that case, I want my
inline docs to be quick, too:
method unsort()
--- Unsorts (randomizes) the array.
{...}
method sort(:order?)
''' Sorts the array.
=param order?A function that takes two arguments (items in the
array) and
returns a number less than, equal to, or greater than zero,
depending if the first
argument should be considered less than, equal to, or greater than
the second
argument in the desired ordering.
'''
{ ... }
The nice thing about this arrangement is that I get to leave the
declaration in place at
