[perl6/specs] c2d66a: Try to fix pod

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: c2d66a5cb73506230130ba4d99374bfafe8942b5
  
https://github.com/perl6/specs/commit/c2d66a5cb73506230130ba4d99374bfafe8942b5
  Author: Zoffix Znet 
  Date:   2017-07-09 (Sun, 09 Jul 2017)

  Changed paths:
M v6d.pod

  Log Message:
  ---
  Try to fix pod

[perl6/specs] 030df4: Fix POD error

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 030df46f1254c88878a51f12e44314155f779a6a
  
https://github.com/perl6/specs/commit/030df46f1254c88878a51f12e44314155f779a6a
  Author: Zoffix Znet 
  Date:   2017-07-05 (Wed, 05 Jul 2017)

  Changed paths:
M v6d.pod

  Log Message:
  ---
  Fix POD error

[perl6/specs] 845eb7: Typos and POD fixes in S02

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 845eb79ae24bcf36c968c541231d66efd281551f
  
https://github.com/perl6/specs/commit/845eb79ae24bcf36c968c541231d66efd281551f
  Author: Lucas Buchala 
  Date:   2014-11-03 (Mon, 03 Nov 2014)

  Changed paths:
M S02-bits.pod

  Log Message:
  ---
  Typos and POD fixes in S02

[perl6/specs] d8869f: Pod would be an IO::Handle, not an IO::Path

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: d8869f83c605d9e6f5a0e91fadd744be5a0a605c
  
https://github.com/perl6/specs/commit/d8869f83c605d9e6f5a0e91fadd744be5a0a605c
  Author: Elizabeth Mattijsen 
  Date:   2014-10-05 (Sun, 05 Oct 2014)

  Changed paths:
M S02-bits.pod

  Log Message:
  ---
  Pod would be an IO::Handle, not an IO::Path


  Commit: a5df488e95515f034982d7a5d844a0c322c5afa2
  
https://github.com/perl6/specs/commit/a5df488e95515f034982d7a5d844a0c322c5afa2
  Author: Elizabeth Mattijsen 
  Date:   2014-10-05 (Sun, 05 Oct 2014)

  Changed paths:
M S16-io.pod

  Log Message:
  ---
  Add indir/tmpdir/homedir to overview


Compare: https://github.com/perl6/specs/compare/37874f2cb41c...a5df488e9551

[perl6/specs] ceebcf: Add "splat"; Fix some POD errors and long lines.

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: ceebcfa60a45cd7a2c804eaf4d10f25dcff945a3
  
https://github.com/perl6/specs/commit/ceebcfa60a45cd7a2c804eaf4d10f25dcff945a3
  Author: Salve J. Nilsen 
  Date:   2014-08-04 (Mon, 04 Aug 2014)

  Changed paths:
M S99-glossary.pod

  Log Message:
  ---
  Add "splat"; Fix some POD errors and long lines.

[perl6/specs] 5aed9c: Fix some minor POD errors

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 5aed9c8b968a6a83de795125817c0af2695409c7
  
https://github.com/perl6/specs/commit/5aed9c8b968a6a83de795125817c0af2695409c7
  Author: Anthony Parsons 
  Date:   2014-08-04 (Mon, 04 Aug 2014)

  Changed paths:
M S17-concurrency.pod
M S28-special-names.pod
M S32-setting-library/IO.pod
M S99-glossary.pod

  Log Message:
  ---
  Fix some minor POD errors

Stops perldoc complaining about missing encodings and parser confusion.


  Commit: 03abe1fd328c8547968c38e160c9931887e9df47
  
https://github.com/perl6/specs/commit/03abe1fd328c8547968c38e160c9931887e9df47
  Author: Anthony Parsons 
  Date:   2014-08-04 (Mon, 04 Aug 2014)

  Changed paths:
M contents.pod

  Log Message:
  ---
  Refresh contents.pod

This looked pretty out of date, so I've re-ran the script that generates it.


Compare: https://github.com/perl6/specs/compare/ceebcfa60a45...03abe1fd328c

[perl6/specs] 8c901d: Refer to .content method for Pod blocks rather tha...

[GitHub]

  Branch: refs/heads/S26
  Home:   https://github.com/perl6/specs
  Commit: 8c901dcd5254f07ed76c8363cf3a71c4dbe68c50
  
https://github.com/perl6/specs/commit/8c901dcd5254f07ed76c8363cf3a71c4dbe68c50
  Author: Rob Hoelz 
  Date:   2014-07-15 (Tue, 15 Jul 2014)

  Changed paths:
M S26-documentation.pod

  Log Message:
  ---
  Refer to .content method for Pod blocks rather than .contents

[perl6/specs] 64799d: Fixing pod errors in S05

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 64799da9a68deb938fb3729e1f0ff4cd8640f4cd
  
https://github.com/perl6/specs/commit/64799da9a68deb938fb3729e1f0ff4cd8640f4cd
  Author: grondilu 
  Date:   2014-05-14 (Wed, 14 May 2014)

  Changed paths:
M S05-regex.pod

  Log Message:
  ---
  Fixing pod errors in S05

nested lists were messed up around line 2270

[perl6/specs] 1446a9: Remove some more pod-based authoritative info

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 1446a9428530092dc95cad7569c7859c4a222eee
  
https://github.com/perl6/specs/commit/1446a9428530092dc95cad7569c7859c4a222eee
  Author: Elizabeth Mattijsen 
  Date:   2014-03-13 (Thu, 13 Mar 2014)

  Changed paths:
M S11-modules.pod

  Log Message:
  ---
  Remove some more pod-based authoritative info

[perl6/specs] 800d9f: Remove pod tags as a source of meta-information

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 800d9f6512bbbf88e0345994ceff7cc487db90e0
  
https://github.com/perl6/specs/commit/800d9f6512bbbf88e0345994ceff7cc487db90e0
  Author: Elizabeth Mattijsen 
  Date:   2014-03-13 (Thu, 13 Mar 2014)

  Changed paths:
M S19-commandline.pod

  Log Message:
  ---
  Remove pod tags as a source of meta-information

Meta-information of a compilation unit will need to be specified in the
(currently being specced) META.info file of a distribution.

[perl6/specs] 3e8a4d: Use pod compunit credentials as defaults only

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 3e8a4d4a29824ce54a67d01d285c4cd8f4dbeecb
  
https://github.com/perl6/specs/commit/3e8a4d4a29824ce54a67d01d285c4cd8f4dbeecb
  Author: Elizabeth Mattijsen 
  Date:   2013-12-04 (Wed, 04 Dec 2013)

  Changed paths:
M S11-modules.pod

  Log Message:
  ---
  Use pod compunit credentials as defaults only

Leave all the nitty gritty to the actual implementation on the "install"
interface.

[perl6/specs] 6af26e: s/Pod6::/Pod::/g to match Rakudo and Niecza

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 6af26e329dd77cfe65f8c5656f05c35b387d9b62
  
https://github.com/perl6/specs/commit/6af26e329dd77cfe65f8c5656f05c35b387d9b62
  Author: Anthony Parsons 
  Date:   2013-08-27 (Tue, 27 Aug 2013)

  Changed paths:
M S26-documentation.pod

  Log Message:
  ---
  s/Pod6::/Pod::/g to match Rakudo and Niecza

[perl6/specs] f6636e: [S21] Fixed some POD formatting errors.

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: f6636e2df9e2465290d01d480de078d17a5e74ea
  
https://github.com/perl6/specs/commit/f6636e2df9e2465290d01d480de078d17a5e74ea
  Author: lue 
  Date:   2012-11-23 (Fri, 23 Nov 2012)

  Changed paths:
M S21-calling-foreign-code.pod

  Log Message:
  ---
  [S21] Fixed some POD formatting errors.

The errors were mainly problems with item lists and missing whitespace
around directives.

[perl6/specs] a95049: [S02] fix POD error

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: a950494055c2d18665754c58cb10112409e617ce
  
https://github.com/perl6/specs/commit/a950494055c2d18665754c58cb10112409e617ce
  Author: Moritz Lenz 
  Date:   2012-04-09 (Mon, 09 Apr 2012)

  Changed paths:
M S02-bits.pod

  Log Message:
  ---
  [S02] fix POD error

Re: [perl6/specs] 6ef69b: pod vars are now lowercase as seen in 3e1a9a5a576b...

[Damian Conway]

> Thank you damian, i will apply that patch,

Much appreciated, Herbert!

Damian

[perl6/specs] 46a599: removing "antiquities" regarding Pod, applying pat...

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 46a5991de5977b8613894fac00424717ab707ed6
  
https://github.com/perl6/specs/commit/46a5991de5977b8613894fac00424717ab707ed6
  Author: Herbert Breunung 
  Date:   2012-04-05 (Thu, 05 Apr 2012)

  Changed paths:
M S02-bits.pod

  Log Message:
  ---
  removing "antiquities" regarding Pod, applying patch by damian


  Commit: a65c854a075054fedb5524b8897d11ecd0936333
  
https://github.com/perl6/specs/commit/a65c854a075054fedb5524b8897d11ecd0936333
  Author: Herbert Breunung 
  Date:   2012-04-05 (Thu, 05 Apr 2012)

  Changed paths:
M S03-operators.pod

  Log Message:
  ---
  Merge branch 'master' of https://github.com/perl6/specs


Compare: https://github.com/perl6/specs/compare/f0f29e7...a65c854

Re: [perl6/specs] 6ef69b: pod vars are now lowercase as seen in 3e1a9a5a576b...

[herbert breunung]

Thank you damian, i will apply that patch,


> Herbert Breunung asked:
> 
>> what was you rational behind this decision.
>> I like it visually but my brain refuses to find any logic why only there
>> special vars should be different.
> 
> This change stems from another change that we made after discussions at
> YAPC Riga last year. That change was to convert the =DATA and =END
> markers to =data and =finish.
> 
> The rationale for that change was as follows...
> 
> In the original redesign for Pod6, every built-in directive (=begin,
> =head1, =item, =table, etc.) was lower-case...except for =DATA and =END,
> which retained their vestigal upper-casing, in analogy to Perl 5's
> __DATA__ and __END__.
> 
> And in the original Pod6 design, every upper-case directive (=SYNOPSIS,
> =AUTHOR, =COPYRIGHT, etc.) was a "semantic block"except for =DATA
> and =END, which were built-ins.
> 
> In other words, =DATA and =END were violating both the syntax for
> built-ins (should be lower-case, but aren't) and the semantics
> of upper-case (should be semantic blocks, but aren't).
> 
> So we changed them to what the syntax and semantics were telling us they
> should be: lower-case.
> 
> But this change broke the one-to-one mapping between Pod sections and
> Pod-access variables. Previously it was:
> 
> =pod<->   $=pod
> =UserDef<->   $=UserDef
> =SYNOPSIS   <->   $=SYNOPSIS
> =DATA   <->   $=DATA
> 
> But, after the Riga discussions it became:
> 
> =pod<->   $=pod
> =UserDef    <->   $=UserDef
> =SYNOPSIS   <->   $=SYNOPSIS
> =data   <->   $=DATA   (oops!)
> 
> Now, this second change simply restores balance to the Force:
> 
> =pod<->   $=pod
> =UserDef<->   $=UserDef
> =SYNOPSIS   <->   $=SYNOPSIS
> =data   <->   $=data
> 
> 
> Note too that, under the current notion that *any* Pod block
> (say: =foo or =BAR) is available under a variable of its own name
> (i.e. $=foo and $=BAR), then $=DATA is still a valid variable. It does
> not, however, access the built-in "data block" named =data. Instead, it
> accesses the (potential) semantic block named =DATA...which is an
> entirely different beastie.
> 
> 
> BTW, S02 still has remnant mentions of $=POD and $=DATA, as well as some
> other "antiquities" regarding Pod variables. I have attached a proposed
> docpatch.
> 
> 
> Damian

Re: [perl6/specs] 6ef69b: pod vars are now lowercase as seen in 3e1a9a5a576b...

[Damian Conway]

Herbert Breunung asked:

> what was you rational behind this decision.
> I like it visually but my brain refuses to find any logic why only there
> special vars should be different.

This change stems from another change that we made after discussions at
YAPC Riga last year. That change was to convert the =DATA and =END
markers to =data and =finish.

The rationale for that change was as follows...

In the original redesign for Pod6, every built-in directive (=begin,
=head1, =item, =table, etc.) was lower-case...except for =DATA and =END,
which retained their vestigal upper-casing, in analogy to Perl 5's
__DATA__ and __END__.

And in the original Pod6 design, every upper-case directive (=SYNOPSIS,
=AUTHOR, =COPYRIGHT, etc.) was a "semantic block"except for =DATA
and =END, which were built-ins.

In other words, =DATA and =END were violating both the syntax for
built-ins (should be lower-case, but aren't) and the semantics
of upper-case (should be semantic blocks, but aren't).

So we changed them to what the syntax and semantics were telling us they
should be: lower-case.

But this change broke the one-to-one mapping between Pod sections and
Pod-access variables. Previously it was:

=pod<->   $=pod
=UserDef<->   $=UserDef
=SYNOPSIS   <->   $=SYNOPSIS
=DATA   <->   $=DATA

But, after the Riga discussions it became:

=pod<->   $=pod
=UserDef<->   $=UserDef
=SYNOPSIS   <->   $=SYNOPSIS
=data   <->   $=DATA   (oops!)

Now, this second change simply restores balance to the Force:

=pod<->   $=pod
=UserDef<->   $=UserDef
=SYNOPSIS   <->   $=SYNOPSIS
=data   <->   $=data


Note too that, under the current notion that *any* Pod block
(say: =foo or =BAR) is available under a variable of its own name
(i.e. $=foo and $=BAR), then $=DATA is still a valid variable. It does
not, however, access the built-in "data block" named =data. Instead, it
accesses the (potential) semantic block named =DATA...which is an
entirely different beastie.


BTW, S02 still has remnant mentions of $=POD and $=DATA, as well as some
other "antiquities" regarding Pod variables. I have attached a proposed
docpatch.


Damian


S02.patch
Description: Binary data

Re: [perl6/specs] 6ef69b: pod vars are now lowercase as seen in 3e1a9a5a576b...

[herbert breunung]

Dear Damian Conway,
what was you rational behind this decision.
I like it visually but my brain refuses to find any logic why only there
special vars should be different.

thank you very much.
herbert


Am 03.04.2012 23:05, schrieb GitHub:
>   Branch: refs/heads/master
>   Home:   https://github.com/perl6/specs
>   Commit: 6ef69b98d8afb6e33a271a466fb8e1beb7142eb8
>   
> https://github.com/perl6/specs/commit/6ef69b98d8afb6e33a271a466fb8e1beb7142eb8
>   Author: Herbert Breunung 
>   Date:   2012-04-03 (Tue, 03 Apr 2012)
> 
>   Changed paths:
> M S28-special-names.pod
> 
>   Log Message:
>   ---
>   pod vars are now lowercase as seen in 
> 3e1a9a5a576b90e9eeabdb7083d16431513513f2
> 
> 
> 

[perl6/specs] 6ef69b: pod vars are now lowercase as seen in 3e1a9a5a576b...

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs
  Commit: 6ef69b98d8afb6e33a271a466fb8e1beb7142eb8
  
https://github.com/perl6/specs/commit/6ef69b98d8afb6e33a271a466fb8e1beb7142eb8
  Author: Herbert Breunung 
  Date:   2012-04-03 (Tue, 03 Apr 2012)

  Changed paths:
M S28-special-names.pod

  Log Message:
  ---
  pod vars are now lowercase as seen in 3e1a9a5a576b90e9eeabdb7083d16431513513f2

[perl6/specs] 3ac109: Disallow Pod blocks inside of Formatting Codes.

[noreply]

  Branch: refs/heads/master
  Home:   https://github.com/perl6/specs

  Commit: 3ac10981f10ec46adb5dbc6f54aed6a628711150
  
https://github.com/perl6/specs/commit/3ac10981f10ec46adb5dbc6f54aed6a628711150
  Author: Tadeusz Sośnierz 
  Date:   2011-08-21 (Sun, 21 Aug 2011)

  Changed paths:
M S26-documentation.pod

  Log Message:
  ---
  Disallow Pod blocks inside of Formatting Codes.


  Commit: bf64672f51ab45faa3059eb428532551bcb4ea74
  
https://github.com/perl6/specs/commit/bf64672f51ab45faa3059eb428532551bcb4ea74
  Author: Tadeusz Sośnierz 
  Date:   2011-08-21 (Sun, 21 Aug 2011)

  Changed paths:
M S26-documentation.pod

  Log Message:
  ---
  Clarify the implicit ending of formatting codes


Compare: https://github.com/perl6/specs/compare/1baf5fe...bf64672

[perl6/specs] a68bbb: [S19] break up unintentional pod formatting code

[noreply]

Branch: refs/heads/master
Home:   https://github.com/perl6/specs

Commit: a68bbb14c052ef1acc0fc7edaa1787bc69836128

https://github.com/perl6/specs/commit/a68bbb14c052ef1acc0fc7edaa1787bc69836128
Author: Fitz Elliott 
Date:   2011-01-29 (Sat, 29 Jan 2011)

Changed paths:
  M S19-commandline.pod

Log Message:
---
[S19] break up unintentional pod formatting code


Commit: e144eacb2967f40a782e439d527a65cc0a577f8e

https://github.com/perl6/specs/commit/e144eacb2967f40a782e439d527a65cc0a577f8e
Author: Fitz Elliott 
Date:   2011-01-29 (Sat, 29 Jan 2011)

Changed paths:
  M S32-setting-library/Containers.pod

Log Message:
---
[S32:Containers] fix broken link to Type Declarations, now in S29

Re: How are unrecognized options to built-in pod block types treated?

[Carl Mäsak]

Darren (>):
> Read what I said again.  I was proposing that the namespace comprised of
> names matching a pattern like this:
>
>  /^ <[A..Z]>+ | <[a..z]>+ $/

/^ [<[A..Z]>+ | <[a..z]>+] $/

// Carl

Re: How are unrecognized options to built-in pod block types treated?

[Aaron Sherman]

On Wed, Aug 4, 2010 at 10:05 PM, Damian Conway  wrote:

> Darren suggested:
>
> > Use namespaces.
>
> The upper/lower/mixed approach *is* a
> namespace approach.
>

It's a very C-like approach, but yes, it's certainly a crude sort of
namespace. Perl already has a more robust and modern namespace system,
however. Using it would seem wise.



> > Explicit versioning is your friend.
> >
> > Can I get some support for this?
>
> Not from me.  ;-)
>
> I think it's a dreadful prospect to allow people to
> write documentation that they will have to rewrite when
> the Pod spec gets updated.


I would hope... really, desperately hope that the POD spec changing would be
the least of anyone's worries. If you're writing documentation, it's a
foregone conclusion that it has to be maintained, just like any other part
of your software. If the POD spec is adding new config options at a rate
that isn't several orders of magnitude less than the frequency with which
your code changes then either you're documenting the Magna Carta or we have
a problem with our documentation system.

If the latter is the case, then the right solution is to provide new
documentation features via modules and allow the user to select which new
features they desire, automatically resolving the problem, since old docs
simply won't pull in newer features.

This could go both ways, as well. "use v6" might get you the default
first-pressing documentation features of Perl 6.0.0 while "use v6.1" might
get you the default features of 6.1. Then you could mix it up:

 use v6;
 use Docs::SectionImage;



> Or, alternatively, to require all
> Pod parsers to be infinitely backwards compatible across
> all versions. :-(
>

If you never want documentation to break, then that's your only option.
Someday we're going to decide to make an incompatible change to Perl's
documentation system, and we'll have a very good reason to do so, I'd
imagine. The right thing to do will be to make sure that we roll it out
carefully and with all due warning.

-- 
Aaron Sherman
Email or GTalk: a...@ajs.com
http://www.ajs.com/~ajs

Re: How are unrecognized options to built-in pod block types treated?

[David Green]

On 2010-08-04, at 7:43 pm, Darren Duncan wrote:
> A parallel solution would be that POD can declare a version, similarly to how 
> Perl code can declare a Perl version, whose spec it is expected to be 
> interpreted according to.

I thought that was more or less how it worked anyway.  You can make Pod do 
anything you want by extending or replacing the grammar (just like [any other 
part of] Perl 6).  So an unrecognized directive should be an error like an 
unrecognized method or rule, but presumably you'd be using whatever modules are 
necessary to recognize them.

On 2010-08-04, at 8:05 pm, Damian Conway wrote:
>> I think it's a dreadful prospect to allow people to write documentation that 
>> they will have to rewrite when the Pod spec gets updated. Or, alternatively, 
>> to require all Pod parsers to be infinitely backwards compatible across all 
>> versions. :-(

But nobody will have to rewrite anything, any more than you have to rewrite all 
your old code. Nor create a mega-parser that combines all possible versions.  
Just continue to use the original modules it was designed for, which, with 
proper versioning, will happen automatically.  Isn't handling such versioning 
worries one of the best features of P6? (After all, docs aren't special to Perl 
— it's all just "code" that it will parse and process any way you tell it to.)

Darren:
> Explicit versioning is your friend.

Yes, always!


-David

Re: How are unrecognized options to built-in pod block types treated?

[Darren Duncan]

Brandon S Allbery KF8NH wrote:

On 8/4/10 21:26 , Darren Duncan wrote:

jerry gay wrote:

are there codepoints in unicode that may be either upper-case or
lower-case, depending on the charset?  if so, then there's ambiguity
here, depending on the user's locale.  i suspect not, but languages
are strange beasts, and i don't know the answer.



Just say that names consisting entirely of either ASCII-range uppercase
letters or ASCII-range lowercase letters are reserved, and that names having
either both of those or any of those plus non-ASCII letters are not reserved.

The only way I see this being a problem is if we forsee that we might want
to have official names going out of the ASCII repertoire, which I would
recommend we don't.


For the first, you're also excluding scripts that lack the notion of case:
Hebrew and Arabic, and all of the ideograms, etc.

As to the latter, Perl 6 already has «» and ASCII equivalent <<>>; I would
expect similar would be possible and supported in this context.

(Yes, I know, I'm not helping.  Only thing that occurs to me is something
like "x-foobie:".)


Read what I said again.  I was proposing that the namespace comprised of names 
matching a pattern like this:


  /^ <[A..Z]>+ | <[a..z]>+ $/

... be reserved for official use and the complementary namespace be available 
for users to define names in.  So users can use anything with non-ASCII 
characters plus those with mixed-case ASCII.


So users aren't excluded from using Hebrew or Arabic characters due to what I 
said, but only that official names wouldn't use them.


-- Darren Duncan

Re: How are unrecognized options to built-in pod block types treated?

[Brandon S Allbery KF8NH]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 8/4/10 21:26 , Darren Duncan wrote:
> jerry gay wrote:
>> are there codepoints in unicode that may be either upper-case or
>> lower-case, depending on the charset?  if so, then there's ambiguity
>> here, depending on the user's locale.  i suspect not, but languages
>> are strange beasts, and i don't know the answer.
> 
> Just say that names consisting entirely of either ASCII-range uppercase
> letters or ASCII-range lowercase letters are reserved, and that names having
> either both of those or any of those plus non-ASCII letters are not reserved.
> 
> The only way I see this being a problem is if we forsee that we might want
> to have official names going out of the ASCII repertoire, which I would
> recommend we don't.

For the first, you're also excluding scripts that lack the notion of case:
Hebrew and Arabic, and all of the ideograms, etc.

As to the latter, Perl 6 already has «» and ASCII equivalent <<>>; I would
expect similar would be possible and supported in this context.

(Yes, I know, I'm not helping.  Only thing that occurs to me is something
like "x-foobie:".)

- -- 
brandon s. allbery [linux,solaris,freebsd,perl]  allb...@kf8nh.com
system administrator  [openafs,heimdal,too many hats]  allb...@ece.cmu.edu
electrical and computer engineering, carnegie mellon university  KF8NH
-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.10 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkxaNEIACgkQIn7hlCsL25VyawCeJDcFIYePVqVXs/ICYOXPTdCM
4EsAnAl4FWfDNVXBrBEyVkcRLRdrUq+X
=9TYE
-END PGP SIGNATURE-

Re: How are unrecognized options to built-in pod block types treated?

[Damian Conway]

Darren suggested:

> Use namespaces.

The upper/lower/mixed approach *is* a
namespace approach.


> Explicit versioning is your friend.
>
> Can I get some support for this?

Not from me.  ;-)

I think it's a dreadful prospect to allow people to
write documentation that they will have to rewrite when
the Pod spec gets updated. Or, alternatively, to require all
Pod parsers to be infinitely backwards compatible across
all versions. :-(

Damian

Re: How are unrecognized options to built-in pod block types treated?

[Darren Duncan]

There's also potentially another simple solution, which in some ways is 
superior, and means we can avoid the whole thing about upper/lowercase being 
significant, that case thing honestly seems like a cludge.


Use namespaces.

In the generic sense, we could say that all names are in at least one level of 
namespace.  Perl just reserves a namespace for itself for official names, and 
the other namespaces are available for use by others.


For brevity, the namespace qualifier may be omitted when referring to the 
Perl-reserved namespace, and so any names that appear unqualified are assumed to 
be there by default.


This is somewhat analogous to the main:: namespace for Perl code.

A parallel solution would be that POD can declare a version, similarly to how 
Perl code can declare a Perl version, whose spec it is expected to be 
interpreted according to.


If POD declares that it is written to a particular version of the POD spec, then 
any unqualified names are taken as reserved ones iff that version of the POD 
spec included them, and they are taken as user-defined otherwise.


I really think that's the way to go.

It can also be documented that the official POD spec will likely just use 
all-uppercase or all-lowercase ASCII words, but that isn't a promise and rather 
is a convention; there may be a good reason to change later.


Explicit versioning is your friend.

Can I get some support for this?

-- Darren Duncan

Re: How are unrecognized options to built-in pod block types treated?

[Damian Conway]

Aaron wrote:

> I dislike "reserved" in this context, but understand why the namespace has
> to be shared. For config options, I'd say anything should go, but people
> inventing their own config options should be aware that across N release
> cycles, new options may be introduced.

...which means that sensible people will avoid those namespaces anyway,
so they might as well be reserved...which then enables us to warn any
not-so-sensible people that their choice of an all-lower- or all-upper-case
option name is brittle and likely to end in tears.

BTW, I also like Darren's suggestion to restrict the reserved space for
standard typenames and option names to the ASCII range.

Dåmîäñ

Re: How are unrecognized options to built-in pod block types treated?

[Darren Duncan]

jerry gay wrote:

On Wed, Aug 4, 2010 at 15:56, Damian Conway  wrote:

Specifically, I think it would be easiest to be consistent and say
that all purely lowercase and all purely uppercase config option names
are reserved, and that unrecognized reserved config options generate
at least a warning when they are parsed. Mixed-case config options
should be freely available to users and the parser should simply
accept them without complaint and include them in the internal data
structure it builds, whereupon they will be available to user-defined
Pod extensions.


are there codepoints in unicode that may be either upper-case or
lower-case, depending on the charset?  if so, then there's ambiguity
here, depending on the user's locale.  i suspect not, but languages
are strange beasts, and i don't know the answer.


There's a simple solution to that.

Just say that names consisting entirely of either ASCII-range uppercase letters 
or ASCII-range lowercase letters are reserved, and that names having either both 
of those or any of those plus non-ASCII letters are not reserved.


The only way I see this being a problem is if we forsee that we might want to 
have official names going out of the ASCII repertoire, which I would recommend 
we don't.


-- Darren Duncan

Re: How are unrecognized options to built-in pod block types treated?

[Aaron Sherman]

On Wed, Aug 4, 2010 at 6:00 PM, Carl Mäsak  wrote:

> Straight to an example:
>
>=for head1 :image
>Steaming hot C loops
>

Interesting that this comes up right as I was composing my "help" email ;)


>
> I went looking for whether this is allowed or not. Is this allowed?
> S26 only tells me this about config options:
>
> "Pod predefines a small number of standard configuration options that
> can be applied uniformly to any built-in block type."
>
> To me, "predefines" could mean either "we made these for you; use only
> those" or "we made these for you; go wild and invent your own too if
> you wish".
>


I see no reason for it to not simply store any additional values away for
potential future use.


>
> It also has this to say about block types:
>
> "Typenames that are entirely lowercase (for example: C<=begin head1>)
> or entirely uppercase (for example: C<=begin SYNOPSIS>) are reserved."
>
> But it's clear from the context of that sentence that this only
> pertains to blocks. There's no indication that this goes for the
> config options as well.
>

I dislike "reserved" in this context, but understand why the namespace has
to be shared. For config options, I'd say anything should go, but people
inventing their own config options should be aware that across N release
cycles, new options may be introduced.

THAT in turn means that we need a way to add config options in a point
release in order to push out new features in reasonable time, and that means
they need their own namespace.

I'd suggest:

=for head1 :reserved('image=foo.jpg')

which is identical to:

=for head1 :image('foo.jpg')

except for the fact that any unrecognized option of the first form is an
error and any unrecognized option of the second form is allowed. That way,
new features can be added to :reserved and migrated over time to stand-alone
options after being listed in the release notes for a couple of cycles.

-- 
Aaron Sherman
Email or GTalk: a...@ajs.com
http://www.ajs.com/~ajs

Re: How are unrecognized options to built-in pod block types treated?

[jerry gay]

On Wed, Aug 4, 2010 at 15:56, Damian Conway  wrote:
> Carl proposed:
>
>> The other path that seems reasonable to me would be to use the same
>> naming scheme as for the block types, i.e. reserve all-upper and
>> all-lower forms (and die if an unrecognized one of this form is
>> encountered), and let the custom ones live in the namespace of
>> mixed-case identifiers. That sounds sane to me as well; the only
>> question is whether that much structure is needed for config options.
>
> I did not consider this issue when designing S26, but in considering
> it now, I think Carl's suggestion is entirely sensible and in line with
> what I intended.
>
> Specifically, I think it would be easiest to be consistent and say
> that all purely lowercase and all purely uppercase config option names
> are reserved, and that unrecognized reserved config options generate
> at least a warning when they are parsed. Mixed-case config options
> should be freely available to users and the parser should simply
> accept them without complaint and include them in the internal data
> structure it builds, whereupon they will be available to user-defined
> Pod extensions.
>
> Damian
>
are there codepoints in unicode that may be either upper-case or
lower-case, depending on the charset?  if so, then there's ambiguity
here, depending on the user's locale.  i suspect not, but languages
are strange beasts, and i don't know the answer.

~jerry

Re: How are unrecognized options to built-in pod block types treated?

[Damian Conway]

Carl proposed:

> The other path that seems reasonable to me would be to use the same
> naming scheme as for the block types, i.e. reserve all-upper and
> all-lower forms (and die if an unrecognized one of this form is
> encountered), and let the custom ones live in the namespace of
> mixed-case identifiers. That sounds sane to me as well; the only
> question is whether that much structure is needed for config options.

I did not consider this issue when designing S26, but in considering
it now, I think Carl's suggestion is entirely sensible and in line with
what I intended.

Specifically, I think it would be easiest to be consistent and say
that all purely lowercase and all purely uppercase config option names
are reserved, and that unrecognized reserved config options generate
at least a warning when they are parsed. Mixed-case config options
should be freely available to users and the parser should simply
accept them without complaint and include them in the internal data
structure it builds, whereupon they will be available to user-defined
Pod extensions.

Damian

How are unrecognized options to built-in pod block types treated?

[Carl Mäsak]

Straight to an example:

=for head1 :image
Steaming hot C loops

As far as parsing goes, that's valid Perl 6 Pod. You're perhaps more
used to seeing it as '=head1', but S26 asserts the equivalence of
these two forms. The reason I'm using the paragraph block form here is
that the abbreviated block form doesn't take config options, and my
question is about those.

S26 doesn't mention the config option :image in connection with
'=head1'. (As it shouldn't, I'm using it for my own nefarious
purposes.)

I went looking for whether this is allowed or not. Is this allowed?
S26 only tells me this about config options:

"Pod predefines a small number of standard configuration options that
can be applied uniformly to any built-in block type."

To me, "predefines" could mean either "we made these for you; use only
those" or "we made these for you; go wild and invent your own too if
you wish".

It also has this to say about block types:

"Typenames that are entirely lowercase (for example: C<=begin head1>)
or entirely uppercase (for example: C<=begin SYNOPSIS>) are reserved."

But it's clear from the context of that sentence that this only
pertains to blocks. There's no indication that this goes for the
config options as well.

Unless I missed the place, S26 simply doesn't specify whether
unrecognized config options to built-in blocks should cause the parser
to blow up or not. Should it?

I guess one could make this question really interesting by throwing in
issues of forward-compatibility and such. Should we expect to be able
to parse Pod "from the future", i.e. using versions of the Perl 6 spec
with more Pod options defined for the built-in blocks?

I'm not savvy enough to attack that last question, but apart from
that, I think allowing/ignoring unrecognized config options seems
reasonable.

The other path that seems reasonable to me would be to use the same
naming scheme as for the block types, i.e. reserve all-upper and
all-lower forms (and die if an unrecognized one of this form is
encountered), and let the custom ones live in the namespace of
mixed-case identifiers. That sounds sane to me as well; the only
question is whether that much structure is needed for config options.

// Carl

POD classes -- a suggestion

[Aaron Sherman]

I'd really like to be able to assign a class to POD documentation. Here's an
example of why:

 class Widget is Bauble
 #= A widget is a kind of bauble that can do stuff
 {
   has $.things; #= a collection of other stuff
   #==XXX{
 This variable needs to be replaced for political reasons
   }
 }

When extracting the documentation for this class, it should appear as such:

 class Widget
   base class: Bauble
   A widget is a kind of bauble that can do stuff
   Attributes:
 $.things (simple scalar) -- a collection of other stuff

But when extracted with a flag requesting class XXX documentation, it should
include the additional line:

 This variable needs to be replaced for political reasons

This has many uses:


   - Keeping customer-visible and internal documentation in the same file
   - Allowing easy access to just the documentation bits that you might be
   interested in
   - Could be extended to allow for injecting documentation into other
   modules that are being extended, but in a way that allows access to the
   original documentation on its own
   - This might expose the implementation of features used to control
   debugging, warnings (e.g. the equivalent of "no strict", but with
   documentation as to why) and lint-like facilities
   - One of my usual gripes about doc systems is that they document elements
   of a program or library and not its function. Given this feature it would be
   easy to distinguish between the two and perhaps even require either or both
   depending on what's being parsed (e.g. a program might require only
   functional documentation where a library might require both functional and
   element-level docs).

Re: More flexible POD

[Mark Overmeer]

Being on holidays, it is not easy to follow threads closely, so if
I repeat things other people have said already, I apologize beforehand.
My responses may b late as well.

Two years ago, I discussed various options, which compared POD to features
in to other languages and suggested various syntaxes:
http://www.nntp.perl.org/group/perl.perl6.language/2007/07/msg27894.html

What I did not really find back in the (swift) scan of the whole debate
gongin on at the moment, is the need to maintain *error free*, *complete*,
and *consistent* documentation with *minimal effort*.  So: the purpose of
documentation.  This must be clear before syntax is being discussed.

"Error free" is simpler in Perl5, because subs have simple parameter
   prototypes and we have no strict types.  In Perl6, when the user
   has more power in the parameter list, it is harder to document it
   correctly by hand.
   I have experiences converting two large existing modules from
   'POD at the end' into 'intermixing POD and code'.  I found many,
   many mistakes in the POD probably because when changing the code
   later, people do not see where the docs which need to be updated
   are located.
   POD at the end of the code to allow a logical flow of the docs has
   some advantanges.  IMO however, you mix two different needs of use
   for documentation: you wish to teach the user and you need to describe
   the API.
   So, why not seperate those two purposes more clearly?  My code
   always has a rather short DESCRIPTION chapter, then the "use often"
   detailed METHOD or FUNCTION description (interleaved with code)
   and then a DETAILS (maybe a bad name) which is the training bit:
   how everything interacts without going into the disturbing API
   nitbits.

"Complete" is covered only partially by the "POD::Coverage".  Of
   course, it is detectable whether all methods/subs/rules are
   described, but can you also check whether all parameters are
   described in full?

"Consistent" documentation is something Perl5 lacks: have a look at
   the way different (Core) modules describe their API. One of the
   poorest parts is the complete lack of inheritance support for
   documenting Perl.  If you only write distributions with a single
   functional package in them, then POD(5) suffices.  When you do
   more complex stuff (like the IO:: modules with inheritance etc)
   then people start manually maintain lists of inherited methods and
   named parameters in higher level man-pages.  This is very hard to
   maintain an stupid!!

"minimal effort" is crucial: when you want people to write documentation,
   then it must create the most useful/beautiful result with minimal
   effort.  The need to rewrite method call parameters is one the of
   useless and error-prone parts of the current POD design. Of course,
   there must be a way to overrule the prototype when needed.
   As example: my Mail::Box set of modules contain (with depedencies)
   about 140 packages with 1150 documented methods and 200 error messages.
   I use OODoc to improve PODs limitations which saves me the typing
   of 700,000 characters(!) which pure POD would require.

The discussion with Damian, two years ago, is whether POD is a
second class sitizen, where it is a burdon to have it and code the only
important thing, or a first class sitizen.  IMO (which is not generally
accepted in the Perl community, but in common in other languages) it is
the latter. IMO programming is solving a problem in a good way, which
means: it is only solved when "it works and is usable". 
   "it works"
  . it does what we need it to do in our application
  . it has regression tests to guarantee that the API works
   "is usable"
  . algorithmic documentation (where the code is unclear)
  . api documentation

Code is IMHO not more important that docs or tests; they are different
view on the same problem. And most of use spend much more lines of text
on docs and tests than on the code (I guess three times as many lines
on docs as on code) So:we need a very light syntax for POD!

There are a few sources which could be used for POD:
  1) information from the code
  2) information from tests
  3) interleaved documentation
  4) end-of-file documentation
  5) Separate file documentation
  6) author, license, SEE ALSO, distribution, version facts
We need to have a standard way of translating those into a "document
tree".  Then we can have different implementations to serialize that
into MAN, HTML etc.  That latter part does not need an obligatory spec.
I use a template system for it.  The current Perl6 specs do not follow
this model sufficiently.
   
If you agree that DOCs are first class language sitizens, then it must
be clear that the "short notation for often used syntax" rule applies.
   #{{ or #{  are visually screaming far too loud.  I would prefer a

Fwd: More flexible POD

[Matthew Walton]

Woops - forgot to reply all (I'm on an irritating mixture of lists
which set reply-to and don't, and I never remember which is which).
Sorry!


-- Forwarded message --
From: Matthew Walton 
Date: Tue, Aug 11, 2009 at 7:10 AM
Subject: Re: More flexible POD
To: Jon Lang 


I'm not sure what it should be, but I do believe that there should be
a solution which allows elegant mixing of code and Pod. I want to
document my APIs by attaching the documentation to the methods in
question, otherwise the documentation won't get updated when the code
does (and if the code at work is anything to go by, won't get updated
at all anyway, but you can at least make it as easy as possible for
the people who do remember).

Attaching blocks of documentation to bits of code is something that
Javadoc's syntax gets very right.

The trouble is, if we just allow arbitrary whitespace before the start
of a Pod block:

class A {
 =head2 foo()
 Frobnicates the widget.
 =end
 method foo() { ... }
}

(modulo accurate Pod directives - I'm a bit hazy on how it works now,
I keep thinking I should be able to say '=method', but maybe that's a
matter for the Pod extractor).

Do we run the risk of causing problems if somebody does this:

my ($several, $lengthily-named, $variables)
 = something-which-produces-a-list();

and the parser thinks 'hang on a sec, that's Pod'. This is
particularly bad for programmers who don't put spaces around their
binary operators (hah! We could enforce it!) and may cause
confuzzlement.

I don't think footnote-like references in the code would help
programmers keep the documentation up to date or help them in reading
it to comprehend the code when they come to maintain it, which I think
are the two key reasons to put your documentation right there in the
code. If you did do it though, you'd have to use named references
(probably valid Perl 6 identifiers), because numbers are just a
nightmare.

Matthew

More flexible POD

[Jon Lang]

Masak's Journal[1] identifies a couple of problems involving the
interaction of POD with block-form classes - one in the article
itself, and another in the comments that follow.  The first is that a
mixture of indented block-form classes and non-indented POD is
visually very ugly.  The second is that mixing POD and code is in
general problematic.  In the latter case, a recommendation is made
that good practice would put all of the POD together at the end of the
file, rather than interspersed throughout.

These two issues seem to operate at cross-purposes: on the one hand,
if all of the POD is consolidated at the end of the file, then you
don't have to worry about how ugly it is to mix POD and indented code.
 OTOH, do we really want to punish programmers for trying to mix the
two?

Assuming that we want to make life easier on programmers who like to
intersperse code and POD, one way to do this would be to replace the
"start of line only" rule for POD with an indenting rule not unlike
what is used with block quotes: if there's any leading whitespace on
the opening line of a POD section, then every line in that section
must start with equivalent whitespace.  This complicates the POD
extractor, but not by much.

In terms of placing all of the POD at the end: one of the strongest
reasons for mixing POD with code is that you can easily identify what
code to which a given section of POD refers. Putting all of the POD at
the end lacks that ability.  One possible solution would be to provide
some means for you to specify a "POD footnote" in the code, not unlike
the URL reference that I've got in this email: in the code itself, you
place an anchor (e.g., '#{{=[1]}}') which can then be referenced later
on by a POD section (e.g., '=[1] start ...').  This would provide an
easy way to switch back and forth between the POD and the related
code.  Mind you, I'm not at all enamored with the specific syntax
suggested above.  It's a quick-and-dirty hack intended strictly to
illustrate the concept.

-- 
Jonathan "Dataweaver" Lang

[1] http://use.perl.org/~masak/journal/39334

Re: pod variables?

[Timothy S. Nelson]

On Fri, 27 Feb 2009, Darren Duncan wrote:


Jon Lang wrote:

Under the section about twigils in S02, "$=var" is described as a "pod
variable".  I'm not finding any other references to pod variables;
what are tey, and how are they used?  (In particular, I'm wondering if
they're a fossil; if they aren't, I'd expect further information about
them to be in S26.)


The principle of pod variables as I recall them discussed a few years ago is 
that it is a way for code to programmatically access its own documentation, 
such as, for example code introspecting a routine could also print out the 
documentation for that routine, I suppose.  Whatever it was, it sounded 
useful at the time. -- Darren Duncan


	To further clarify, I put this exact question to Larry, and he 
basically said that the clarification of POD variables will happen as Damian 
continues work on S26-Documentation.


:)


-
| 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: pod variables?

[Darren Duncan]

Jon Lang wrote:

Under the section about twigils in S02, "$=var" is described as a "pod
variable".  I'm not finding any other references to pod variables;
what are tey, and how are they used?  (In particular, I'm wondering if
they're a fossil; if they aren't, I'd expect further information about
them to be in S26.)


The principle of pod variables as I recall them discussed a few years ago is 
that it is a way for code to programmatically access its own documentation, such 
as, for example code introspecting a routine could also print out the 
documentation for that routine, I suppose.  Whatever it was, it sounded useful 
at the time. -- Darren Duncan

pod variables?

[Jon Lang]

Under the section about twigils in S02, "$=var" is described as a "pod
variable".  I'm not finding any other references to pod variables;
what are tey, and how are they used?  (In particular, I'm wondering if
they're a fossil; if they aren't, I'd expect further information about
them to be in S26.)

-- 
Jonathan "Dataweaver" Lang

Re: Perl 6 pod processor in Perl 5

[Mark Overmeer]

* Gabor Szabo (szab...@gmail.com) [090212 06:44]:
> As an experiment to check how we could reuse CPAN to distribute Perl 6
> packages.
> 
> Not surprisingly neither of them can handle the perl pod.
> I contacted both maintainers asking to look into it suggesting
> to use Perl6::Perldoc of Damian but it is quite old.

The reason for that may be that (after a very long discussion) Damian
promissed me to have a serious look at a more powerful documentation
systems, like there is in python or Java.  And he never found time to
look into that.
-- 
Regards,
   MarkOv


   Mark Overmeer MScMARKOV Solutions
   m...@overmeer.net  soluti...@overmeer.net
http://Mark.Overmeer.net   http://solutions.overmeer.net

Perl 6 pod processor in Perl 5

[Gabor Szabo]

As an experiment to check how we could reuse CPAN to distribute Perl 6 packages
I uploaded Perl6::Conf
The code itself is not interesting, my main interest is the "distribution".

One of the issues I encountered is the display on the two search engines:

http://search.cpan.org/dist/Perl6-Conf/
http://kobesearch.cpan.org/dist/Perl6-Conf

Not surprisingly neither of them can handle the perl pod.
I contacted both maintainers asking to look into it suggesting
to use Perl6::Perldoc of Damian but it is quite old.

Is there any other module written in Perl 5 that could parse a perl 6
file, recognize the pod and help with the display?

Gabor

S*.pod edits submissions

[John M. Dlugosz]

I have changed files at  
waiting for someone in authority to merge.

Re: POD in the test suite

[Larry Wall]

On Fri, Jan 18, 2008 at 10:54:11AM +0100, Moritz Lenz wrote:
: I noticed that many test files contain "old" POD like this:
: 
: =pod
: 
: some description here
: 
: =cut
: 
: 
: Should that all be replaced by the new POD?
: 
: =begin description
: 
: text here
: 
: =end description

Jah, so glaube ich.

Larry

POD in the test suite

[Moritz Lenz]

I noticed that many test files contain "old" POD like this:

=pod

some description here

=cut


Should that all be replaced by the new POD?

=begin description

text here

=end description



-- 
Moritz Lenz
http://moritz.faui2k3.org/ |  http://perl-6.de/



signature.asc
Description: OpenPGP digital signature

Re: Some Things I'd Like To Do With Pod

[Piers Cawley]

On 22/06/07, brian d foy <[EMAIL PROTECTED]> wrote:

===Per class documentation, not per file documentation

Related to the one above, I'd like to have NAME, SYNOPSIS, etc. for
each class, not just per file. Well, what I really want is the
Smalltalk class and method browsers, but I know I'm not going to get
those.


I'm sure it's going to be great deal easier to implement such a tool
in Perl 6 than it is in Perl 5 though. It's just not going to be in
the core. And even if it's not going to be easy, I can think of at
least one person who is going to have a bloody good go at implementing
it.

With apologies if I'm teaching my grandma to suck eggs here.

Some Things I'd Like To Do With Pod

[brian d foy]

I have a feeling we've sorta assumed some use cases for whatever Pod
design we're advocating, so I thought I'd write down what I'd like to
do with Pod. At this level, I don't care how it gets done, which model
it uses, or anything else.

This isn't a fantasy wishlist of anything I think I might want. These
are things that I've wanted for a couple years. I'm not trying to start
an RFC process, but think about how to motivate some of the things we
are debating. These are just use cases, not really feature requests:

==Pull out the docs for a single method.in a class

I want perldoc -f for modules. That works for perlfunc because there is
a simple structure to the file where all the =item represent a function
(and similarly for perldoc -q and the perlfaq).

I'm not thinking ahead to what the method docs would look like. If I
had this I'd be happy just to get plain text.

==Know which class the Pod is in

One of the failings of Pod::Coverage right now is that it assumes that
there is only one class per file and the filename represents the class.
This means I can't use Pod::Coverage or Test::Pod::Coverage when Ihave
a design that doesn't do that (e.g. a convenience class that's private
and only a screen long).

I'd really like a Pod parser to know what class it is in, and which
class the documentation belongs to.

===Per class documentation, not per file documentation

Related to the one above, I'd like to have NAME, SYNOPSIS, etc. for
each class, not just per file. Well, what I really want is the
Smalltalk class and method browsers, but I know I'm not going to get
those. It's a major missing feature from my perlbrowser tool (on CPAN).
Part of that means, though, that if I want that docs for Foo::Bar which
live in Foo.pm, then perldoc6 has to know how to find that class.
That's a much larger issue than just the Pod format.

If I put more than one class in a file, I'd like to be able to extract
it's documentation separately. Of course, this leads to huger problems
making it work, so I'm not holding my breath. It's more likely I'll
have to live with separate files :)

Private docs

There's documentation for module users, and there is documentation for
module developers. I'd like to document the private methods too, but
without something to tell perldoc6 that you want the secret docs, you
don't see them. The secret docs are for the people working inside the
code of the class (creators, maintainers, whatever), and those docs are
just like the user docs in structure.

Re: Pod 6: ease of implementation vs easy of use

[Mark Overmeer]

* Damian Conway ([EMAIL PROTECTED]) [070616 23:21]:
> I will, however, take a moment to answer the accusation that I appear to
> have redesigned Pod the way I did in order to make implementation
> easier...

The opposit: your work is known to seek the corners of the language
which hurt most.  So please ignore those callers in the dark, which are
apparently poorly informed.

Recently, I also had a few encounters with grumpy mongers, which, simply
based on the fact that they feel more important, feel the need to insult
or ignore other people.  Especially, the word "Freedom" is used a lot in
these flames, although the interpretation of that term is quite different,
World-wide.  What is acceptable for the sake of "Freedom"?
-- 
   MarkOv


   Mark Overmeer MScMARKOV Solutions
   [EMAIL PROTECTED]  [EMAIL PROTECTED]
http://Mark.Overmeer.net   http://solutions.overmeer.net

Pod 6: ease of implementation vs easy of use

[Damian Conway]

I'm not going to argue about the design of Pod 6 any more. As both Mark
and brian have pointed out, this really comes down to philosophical
differences that no amount of discussion is going to resolve. In any
case, I'm sure that Larry now has plenty of "grist" from which to mill a
final specification of how the Perl 6 documentation mechanism will work.

I will, however, take a moment to answer the accusation that I appear to
have redesigned Pod the way I did in order to make implementation
easier...and at the expense of making life harder for programmers and
educators.


It's hard to believe anyone could think I would ever do that. It's
almost as if the they don't know me at all.

From the very first day I became part of the Perl community (August 18,
1998, when I presented Getopt::Declare and Lingua::EN::Inflect at the
Second Perl Conference), my entire philosophy and purpose has been to
make things *easier* for users of Perl, no matter what that did to the
complexity of the implementation.

Every serious module I've ever written over the subsequent decade has
had that same characteristic and intended function: Attribute::Handlers,
Class::Contract, Class::Multimethods, Class::Std, Config::Std,
Contextual::Return, Filter::Simple, Getopt::Euclid, IO::Prompt,
Module::Starter, NEXT, Parse::RecDescent, Regexp::Common,
Smart::Comments, Switch, Text::Autoformat...etc., etc.

Indeed the term "a Damian module" is now widely used to mean "software
that makes your life easier...until you actually try to read the source
or understand the implementation". :-)

I've always been quite proud of that...since that description is pretty
much the definition of the perl interpreter itself. I always felt that
meant I was doing my job right.

I've also lectured and taught academic and professional classes on
interface design for several decades now, and always with that same
basic message: make life easier for the user, no matter how much that
complicates the implementor's job.

Certainly, anyone who has sat in on a Perl 6 design meeting will tell
you that I've consistently argued that way; frequently to the point of
aggravating those courageous souls who are charged with the task of
implementing Perl 6.


So it actually *hurts* me that people might think I would ever
compromise on usability, just to facilitate implementability. Please
read what I wrote again. I *did* claim that "easier to implement" was a
nice side-benefit of my design...but only because I was directly
responding to brian's question about Pod 6's adaptability to other
programming languages.

I *never* said ease-of-implementation was a major consideration, of a
motivation for, or even a significant argument in favour of, the
original design. My entire argument for separated Pod is based on
promoting the prominence and readability of Pod documentation by
distinguishing it lexically, rather than syntactically.


Enough. I will now get back to designing the new A<> formatting code
('A' for *A*lias to *A*mbient *A*rtifact), which I'll preview early
next week. Though I'm sure people won't like that new feature either,
since it's going to be designed using the same "separated model"
philosophy. ;-)

Damian

Re: POD <-> Code entanglement

[John Beppu]

For what it's worth, I'm a fan of the notation that NaturalDocs uses.

  Function: Multiply

  Multiplies two integers.

  Parameters:

 x - The first integer.
 y - The second integer.

  Returns:

 The two integers multiplied together.

  See Also:

 


http://www.naturaldocs.org/   (...which happens to be written in Perl.)


On 6/14/07, Mark Overmeer <[EMAIL PROTECTED]> wrote:


* Thom Boyer ([EMAIL PROTECTED]) [070614 15:49]:
> the existing S26, say things like:
>
> =Method the method synopsis goes here
> =begin Parameters
> =item foo is the fooiest parameter
> =item bar is the barstest parameter
> =end Parameters

Where is the link with the code?  That's the point: there is no
automatic checking/avoidance of repetition.  Besides, your example
is not defined by S26: one can decide to use the tags, someone
else chooses other names, and they then cannot be combined into
one nice homogeneous set of pages.  That's a horror!

And if you really like above syntax, why not define
  =method the method synopsis goes here
  =option   foo is the fooiest parameter
  =default  foo 10
  =requires bar is the barstest parameter
Which is close to how OODoc is extending POD for Perl5.
IMO We can (should) do better for Perl6.
--
   MarkOv


   Mark Overmeer MScMARKOV Solutions
   [EMAIL PROTECTED]  [EMAIL PROTECTED]
http://Mark.Overmeer.net   http://solutions.overmeer.net

Re: POD <-> Code entanglement

[Mark Overmeer]

* Thom Boyer ([EMAIL PROTECTED]) [070614 15:49]:
> the existing S26, say things like:
> 
> =Method the method synopsis goes here
> =begin Parameters
> =item foo is the fooiest parameter
> =item bar is the barstest parameter
> =end Parameters

Where is the link with the code?  That's the point: there is no
automatic checking/avoidance of repetition.  Besides, your example
is not defined by S26: one can decide to use the tags, someone
else chooses other names, and they then cannot be combined into
one nice homogeneous set of pages.  That's a horror!

And if you really like above syntax, why not define
  =method the method synopsis goes here
  =option   foo is the fooiest parameter
  =default  foo 10
  =requires bar is the barstest parameter
Which is close to how OODoc is extending POD for Perl5.
IMO We can (should) do better for Perl6.
-- 
   MarkOv


   Mark Overmeer MScMARKOV Solutions
   [EMAIL PROTECTED]  [EMAIL PROTECTED]
http://Mark.Overmeer.net   http://solutions.overmeer.net

Re: POD <-> Code entanglement

[Moritz Lenz]

Thomas Wittek wrote:
> Moritz Lenz:
>> =begin pod
>> 
>> =head3 C
>> [..]
>> =end pod
>> 
>> method from_string(Str $s){
>>  # implementation of that method here
>> }
>> 
>> Since method signatures are very expressive in Perl 6, there should be a
>> way of accessing them in the POD without copy & paste.
> 
> As I read "=head 3 method..." I also had the idea that semantically more
> meaningful directives might be a good idea.

That may be my fault, I didn't care to look if there was a more semantic
way to describe it.

> I mean POD uses constructs like headlines, lists, blocks, italic etc.
> which all describe _how it looks like_ and not _what it is_.

Headlines, lists and blocks are IMHO semantic markup.
If I'd say "Huge font in bold" that'd be descriptive rather than
semantic markup.

> A head3 might be the headline of a method documentation as well as one
> introducing the contact information for the author of a module.
> The directive doesn't have much semantics.

That doesn't make a headline worthless. It just shouldn't be abused the
way I did it ;)



-- 
Moritz Lenz
http://moritz.faui2k3.org/ |  http://perl-6.de/



signature.asc
Description: OpenPGP digital signature

Re: POD <-> Code entanglement

[Thom Boyer]

Thomas Wittek wrote:
> I mean POD uses constructs like headlines, lists, blocks, italic etc.
> which all describe _how it looks like_ and not _what it is_.

I think Damian would take exception to that statement. He worked quite 
hard to make sure that POD describes _meaning_ rather than _appearance_.
He even renamed B<> from "bold" to "basis", I<> from "italic" to 
"important", and U<> from "underline" to "unusual". All of those are 
fairly odd choices, with the possible exception of "important", but they 
were clearly made with an eye to backwards compatibility of POD while 
changing people's focus from how it looks to what it is.


> A head3 might be the headline of a method documentation as well as one
> introducing the contact information for the author of a module.
> The directive doesn't have much semantics.
> Other people might use head2 for documenting methods, what leads to a
> pretty inconsistent look of the documentation.

Well, I'd argue that head3 has plenty of semantics. It's a level-3 
header. How that's rendered is decided elsewhere.


I think the issue is not that head3 is insufficiently semantic, it's 
just that you want something that's even more specific. And POD 6 was 
designed with exactly that kind of thing in mind. You can, according to 
the existing S26, say things like:


=Method the method synopsis goes here
=begin Parameters
=item foo is the fooiest parameter
=item bar is the barstest parameter
=end Parameters

Furthermore, the Perl parser actually *keeps* the POD chunks, so you can 
access all that information in the context of the Perl parse. Damian and 
Larry were clearly laying the groundwork for exactly the sort of 
javadoc-ish features you are asking for.


=thom
-
The supreme irony of life is that hardly anyone gets out of it alive.
--Robert A. Heinlein [Job: A Comedy of Justice]

Re: POD <-> Code entanglement

[Ruud H.G. van Tol]

Mark Overmeer schreef:

> The nicest thing would be that the semantic docs become part of the
> parse tree, which then (using standard introspection) can be used to
> generate manual pages, natively into POD, roff, HTML, whatever.

I like to call them: lexical comments. 

-- 
Groet, Ruud

Re: POD <-> Code entanglement

[Aankhen]

On 6/14/07, Thomas Wittek <[EMAIL PROTECTED]> wrote:

It's a bit like HTML<->XML, where the former lacks most of the semantics
and makes the information processing - not to speak about a consistent
look over several documents - a lot harder.


Actually, that's incorrect.  HTML is a markup language with a
particular set of elements, some of which have semantic meaning
attached and some of which don't.  XML, on the other hand, is a means
of writing your own markup languages; this has two consequences in
this context:

1. It is just as easy—if not easier—to have an XML dialect containing
elements with absolutely no meaning.
2. Even if the dialect contains only elements with well-defined
semantics, it's still completely meaningless to a generic XML parser.
A parser must be intimately familiar with the dialect to understand
that any element has semantic meaning.

If you were referring to XHTML vs. HTML, I would like to point out
that XHTML 1.0 is merely a reformulation of HTML 4.01 in XML.  The
elements and their semantics are unchanged.  XHTML 1.1 modularizes the
DTD and adds a few Ruby (annotation, obviously, not language)
elements, in addition to a few other minor changes.  As for XHTML 2.0,
that's still a long way off. :-)
--
Aankhen
(We have no branches.)

Re: POD <-> Code entanglement

[Juerd Waalboer]

Thomas Wittek skribis 2007-06-14 17:18 (+0200):
> So maybe directives like method, sub, attribute, class etc. might be a
> better choice regarding semantics.

Yes, a better choice indeed. But I would still not be happy with it,
because there would still be a lot of code duplication.

method foo (:$bar = 5) { ... }

I don't want to have to mention *again* that the thing is a "method",
and that it is called "foo", that it has a "named argument" identified
as "$bar", which defaults to 5.

This is why I (long time ago) suggested "is documented". Like Mark, I do
not really care about the actual syntax much:

method foo is documented("Foos its argument interactively")
(
:$bar = 5 is documented("Object to be fooed"),
# I'm not sure about the precedence of "is".
) {
...
}

The backtick is rather cute and saves a lot of typing. It's like a
comment (#), but ends up as *external* documentation. That's nice.

> Semantics are very useful in documentation, why throw them away?

Why not have both? With normal POD as suggested by Damian, you could
still generate it from something else. A few macros could help ignore
the inline documentation.
-- 
korajn salutojn,

  juerd waalboer:  perl hacker  <[EMAIL PROTECTED]>  <http://juerd.nl/sig>
  convolution: ict solutions and consultancy <[EMAIL PROTECTED]>

Re: POD <-> Code entanglement

[Mark Overmeer]

* Thomas Wittek ([EMAIL PROTECTED]) [070614 15:18]:
> So maybe directives like method, sub, attribute, class etc. might be a
> better choice regarding semantics.

See OODoc::Parser::Markov

> It's a bit like HTML<->XML, where the former lacks most of the semantics
> and makes the information processing - not to speak about a consistent
> look over several documents - a lot harder.

In HTML, you have logical markup as well: EM, STRONG, KEY, CODE, etc
With id and class, you can make any annotation you like:

  
 my_method OPTIONS
 This is the description of a method.
  

I love the power of CSS.

> I could imagine a semantic documentation in Perl6, that could be
> translated to XML/HTML+CSS or to POD(6) for formatting it.

The nicest thing would be that the semantic docs become part of the parse
tree, which then (using standard introspection) can be used to generate
manual pages, natively into POD, roff, HTML, whatever.

I see no reason why entangled docs are so hard to parse for Perl6,
as Damian arguments.  Even it being difficult is not a good reason to
make the life of all programmers harder.
-- 
   MarkOv


   Mark Overmeer MScMARKOV Solutions
   [EMAIL PROTECTED]  [EMAIL PROTECTED]
http://Mark.Overmeer.net   http://solutions.overmeer.net

Re: POD <-> Code entanglement

[Thomas Wittek]

Moritz Lenz:
> =begin pod
> 
> =head3 C
> [..]
> =end pod
> 
> method from_string(Str $s){
>   # implementation of that method here
> }
> 
> Since method signatures are very expressive in Perl 6, there should be a
> way of accessing them in the POD without copy & paste.

As I read "=head 3 method..." I also had the idea that semantically more
meaningful directives might be a good idea.

I mean POD uses constructs like headlines, lists, blocks, italic etc.
which all describe _how it looks like_ and not _what it is_.
A head3 might be the headline of a method documentation as well as one
introducing the contact information for the author of a module.
The directive doesn't have much semantics.
Other people might use head2 for documenting methods, what leads to a
pretty inconsistent look of the documentation.

So maybe directives like method, sub, attribute, class etc. might be a
better choice regarding semantics.
Of course those semantics are directly given in the code, so why not use
them as MarkOv proposed?

It's a bit like HTML<->XML, where the former lacks most of the semantics
and makes the information processing - not to speak about a consistent
look over several documents - a lot harder.

I could imagine a semantic documentation in Perl6, that could be
translated to XML/HTML+CSS or to POD(6) for formatting it.

A semantic documentation could also be very useful in IDEs, where the
IDE could clearly (without guessing) determine the documentation for a
certain element.
Also you could automatically test if every method/class/.. has been
documented etc.

Semantics are very useful in documentation, why throw them away?
-- 
Thomas Wittek
http://gedankenkonstrukt.de/
Jabber: [EMAIL PROTECTED]

POD <-> Code entanglement (was: Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn)

[Moritz Lenz]

Mark Overmeer wrote:
> We had a private discussion about this already three years ago: I
> fully disagree!  If the code and the documentation are not entangled,
> why do you want to put them in the same file?  Why do you put them in
> the same distribution even?
> 
> No, the documentation is all about the code. The docs present everything
> what the user should know about the code.  The docs are the user's view
> of the implementation, and the code is the computer's view on the same.

I agree.
And while writing a class in Perl 6 the other day I noticed that copied
& pasted the signature of method to the pod:

=begin pod

=head3 C

initialize the Sudoku from a string C<$s>, with a 0 denoting an empty cell
and a number between 1 and 9 a clue.

Note that there is currently no way to use this function for sizes bigger
than 9x9 overall length.

=end pod

method from_string(Str $s){
# implementation of that method here
}

Since method signatures are very expressive in Perl 6, there should be a
way of accessing them in the POD without copy & paste. If you don't
think that's necessary: try it out for yourself. Write a class and
document it properly. I'm sure you'll end up doing the same as I did.

ATM I don't know that should be implemented, but perhaps somebody else
can think of a good way.

-- 
Moritz Lenz
http://moritz.faui2k3.org/ |  http://perl-6.de/



signature.asc
Description: OpenPGP digital signature

Re: multi-line comments, C macros, & Pod abuse

[markjreed]

I think this is not even a metaprogramming issue so much as a
programming environment one.  I mean, if your editor doesn't make it
easy to stick a # at the beginning of a bunch of lines with one
action, and likewise remove them later, you need to get a new editor.
:)

On 8/21/06, Joshua Hoblitt <[EMAIL PROTECTED]> wrote:

On Mon, Aug 21, 2006 at 12:06:36AM +0100, Andrew Suffield wrote:
> On Sun, Aug 20, 2006 at 03:55:56PM -0600, Luke Palmer wrote:
>
> > Why would you care about introducing a new lexical scope?  You would
> > care about that if you used a variable you declared in the commented
> > code in the code below it, which is broken.
>
> Typically because you have several versions that you want to switch
> between, and you'd rather add a few characters of comment rather than
> spend the time rearranging the code to use ifs or subs or
> something. It's something you might do when debugging or experimenting
> (especially under time pressure) - at least, that's how I use '#if 0'
> in C.

The more I think about this issue the more I realize that this is really
a very simple case of metaprogramming.  Which got me thinking about more
sophisticated compile time flow control.  I imagine that defining
something like a compile time switch switch statement is possible with
the existing macros.  Would anyone like to take a shot at defining a
macro to do this?  Is it possible to jump to something outside of a
macros input that is also evaluated at compile time?

> Using <<'#END' (or rather, q:to'#END') is actually not that bad an
> idea... it'd work in most places where #{} would give trouble. Unless
> anybody has any better ideas, that could be a useful idiom to
> remember.

Using heredocs for commenting code out is slightly undesirable as it
would create a branch that has to be tested at runtime.  One would hope
that the compiler would note the conditional on a constant and throw the
heredoc out as dead code but it certainly feels untidy.

-J

--





--
Mark J. Reed <[EMAIL PROTECTED]>

Re: multi-line comments, C macros, & Pod abuse

[Joshua Hoblitt]

On Mon, Aug 21, 2006 at 12:06:36AM +0100, Andrew Suffield wrote:
> On Sun, Aug 20, 2006 at 03:55:56PM -0600, Luke Palmer wrote:
> 
> > Why would you care about introducing a new lexical scope?  You would
> > care about that if you used a variable you declared in the commented
> > code in the code below it, which is broken.
> 
> Typically because you have several versions that you want to switch
> between, and you'd rather add a few characters of comment rather than
> spend the time rearranging the code to use ifs or subs or
> something. It's something you might do when debugging or experimenting
> (especially under time pressure) - at least, that's how I use '#if 0'
> in C.

The more I think about this issue the more I realize that this is really
a very simple case of metaprogramming.  Which got me thinking about more
sophisticated compile time flow control.  I imagine that defining
something like a compile time switch switch statement is possible with
the existing macros.  Would anyone like to take a shot at defining a
macro to do this?  Is it possible to jump to something outside of a
macros input that is also evaluated at compile time? 

> Using <<'#END' (or rather, q:to'#END') is actually not that bad an
> idea... it'd work in most places where #{} would give trouble. Unless
> anybody has any better ideas, that could be a useful idiom to
> remember.

Using heredocs for commenting code out is slightly undesirable as it
would create a branch that has to be tested at runtime.  One would hope
that the compiler would note the conditional on a constant and throw the
heredoc out as dead code but it certainly feels untidy.

-J

--


pgpCLflaAtQID.pgp
Description: PGP signature

Re: multi-line comments, C macros, & Pod abuse

[Andrew Suffield]

On Sun, Aug 20, 2006 at 03:55:56PM -0600, Luke Palmer wrote:
> >The important question here is this one:
> >
> > - when 'uncommented', is it a no-op?
> >
> >Which isn't true for #{}/{}, because {} introduces new lexical
> >scope.

> Why would you care about introducing a new lexical scope?  You would
> care about that if you used a variable you declared in the commented
> code in the code below it, which is broken.

Typically because you have several versions that you want to switch
between, and you'd rather add a few characters of comment rather than
spend the time rearranging the code to use ifs or subs or
something. It's something you might do when debugging or experimenting
(especially under time pressure) - at least, that's how I use '#if 0'
in C.

Using <<'#END' (or rather, q:to'#END') is actually not that bad an
idea... it'd work in most places where #{} would give trouble. Unless
anybody has any better ideas, that could be a useful idiom to
remember.

Re: multi-line comments, C macros, & Pod abuse

[Luke Palmer]

On 8/20/06, Luke Palmer <[EMAIL PROTECTED]> wrote:

Well, I think you are being too picky.

[snip snarky sarcastic rant]


Hmm, perhaps I'm feeling edgy.  Or maybe some of the comments reminded
me of those rediculously long, whiny threads.  Anyway, that was
un-called-for.

Luke

Re: multi-line comments, C macros, & Pod abuse

[Luke Palmer]

On 8/20/06, Andrew Suffield <[EMAIL PROTECTED]> wrote:

On Sun, Aug 20, 2006 at 10:50:31AM -1000, Joshua Hoblitt wrote:
> > #{
> >if $baz {
> >$foo.bar
> >}
> > }
> >
> > To uncomment, remove the # before the {.
>
> This is exactly the type of construct that I had in mind.  A couple of
> questions. Is code inside of a #{}:
>
> - parsed and required to be syntacticly correct?
> - does it still appear in emitted code?
> - what happens when a goto tries to enter into this block
>   or a nested sub is invoked?
> - will the optimizer spend time on this block?

The important question here is this one:

 - when 'uncommented', is it a no-op?

Which isn't true for #{}/{}, because {} introduces new lexical
scope. It's still a pretty good idea, but it's not as good as the C
preprocessor. if (0) has the same problem. Pod doesn't. Anybody able
to think up a non-pod construct that doesn't affect the code it wraps?
(Solutions which involve complicated modules are acceptable, so long
as the usage is not complicated and there is no run-time penalty)


Well, I think you are being too picky.

Why would you care about introducing a new lexical scope?  You would
care about that if you used a variable you declared in the commented
code in the code below it, which is broken.  If you are still not
satisfied, you might try:

   <<'#EOC';
   .. commented out code ..
   #EOC

And put the code back into effect by commenting out the <<'#EOC' line.
Of course, that changes the last statement evaluated, which isn't
good because the code above it (which is supposed to have code below
it making it forget about its last statement evaluated) must maintain
its last statement evaluated.

You can't use Pod, because you have to insert two characters instead
of changing one to uncomment some code.

And, since you are open to using complicated modules, I suppose using
a module like:

   use C::Preprocessor::IfZero;

is out of the question because its implementation would only be a
couple of lines.

Yep, I think we need to add a feature to perl to support commenting
and uncommenting code easily.

Luke

Re: multi-line comments, C macros, & Pod abuse

[Larry Wall]

On Sun, Aug 20, 2006 at 10:50:31AM -1000, Joshua Hoblitt wrote:
: On Sat, Aug 19, 2006 at 02:26:28AM +, Luke Palmer wrote:
: > On 8/19/06, Aaron Crane <[EMAIL PROTECTED]> wrote:
: > >You don't actually need a macro in that case:
: > >
: > >if 0 { q<
: > >...
: > >> }
: > 
: > Which, of course, eliminates the original desire to have a
: > code-commenting construct where "you just change the 0 to a 1".  After
: > all, we already have #{}.  Incidentally, you could consider that the
: > desired construct, because it balances, and a closure at statement
: > level executes itself:
: > 
: > #{
: >if $baz {
: >$foo.bar
: >}
: > }
: > 
: > To uncomment, remove the # before the {.

The idiom would probably want to be \#{ to avoid falling afoul of the
rule that says a # in the first column is always a line-ending comment.
That's because some people would rather let their editor comment out a
block of code like this:

#{
#if $baz {
#$foo.bar
#}
#}

That has the benefit of making all the lines look like comments, and if
you're editor supports it, it's not difficult to change back.  Anyway,
we're trying to support both approaches, so use \#{...} if you want the
brackets to do the delimiting.  Maybe people will just get in the habit
of using \#{...} for all embedded comments.  I suppose we could even go
as far as to require it, but maybe that's overkill.

: This is exactly the type of construct that I had in mind.  A couple of
: questions. Is code inside of a #{}:
: 
: - parsed and required to be syntacticly correct?
: - does it still appear in emitted code?
: - what happens when a goto tries to enter into this block
:   or a nested sub is invoked?
: - will the optimizer spend time on this block?

It's a comment, so it's all just whitespace as far as the parser
is concerned.

Larry

Re: multi-line comments, C macros, & Pod abuse

[Andrew Suffield]

On Sun, Aug 20, 2006 at 10:50:31AM -1000, Joshua Hoblitt wrote:
> > #{
> >if $baz {
> >$foo.bar
> >}
> > }
> > 
> > To uncomment, remove the # before the {.
> 
> This is exactly the type of construct that I had in mind.  A couple of
> questions. Is code inside of a #{}:
> 
> - parsed and required to be syntacticly correct?
> - does it still appear in emitted code?
> - what happens when a goto tries to enter into this block
>   or a nested sub is invoked?
> - will the optimizer spend time on this block?

The important question here is this one:

 - when 'uncommented', is it a no-op?

Which isn't true for #{}/{}, because {} introduces new lexical
scope. It's still a pretty good idea, but it's not as good as the C
preprocessor. if (0) has the same problem. Pod doesn't. Anybody able
to think up a non-pod construct that doesn't affect the code it wraps? 
(Solutions which involve complicated modules are acceptable, so long
as the usage is not complicated and there is no run-time penalty)

Re: multi-line comments, C macros, & Pod abuse

[Mark J. Reed]

On 8/20/06, Joshua Hoblitt <[EMAIL PROTECTED]> wrote:

This is exactly the type of construct that I had in mind.  A couple of
questions. Is code inside of a #{}:

- parsed and required to be syntacticly correct?


No.  It's a comment. # followed by one or more open bracket characters
creates a comment that lasts until the matching closing bracket
character(s).   It is otherwise exactly treated as single-line
comments.  So:


- does it still appear in emitted code?


Not sure what you mean here.



- what happens when a goto tries to enter into this block


It fails because the label it's referencing doesn't exist.


  or a nested sub is invoked?


Ditto.


- will the optimizer spend time on this block?


No.


Note, however, that Luke's example is incorrect according to S02.  A
line beginning with #{ doesn't start a bracketed comment; it's treated
as a single-line comment.  You need to put something before the # on
the line.

--
Mark J. Reed <[EMAIL PROTECTED]>

Re: multi-line comments, C macros, & Pod abuse

[Joshua Hoblitt]

On Sat, Aug 19, 2006 at 02:26:28AM +, Luke Palmer wrote:
> On 8/19/06, Aaron Crane <[EMAIL PROTECTED]> wrote:
> >You don't actually need a macro in that case:
> >
> >if 0 { q<
> >...
> >> }
> 
> Which, of course, eliminates the original desire to have a
> code-commenting construct where "you just change the 0 to a 1".  After
> all, we already have #{}.  Incidentally, you could consider that the
> desired construct, because it balances, and a closure at statement
> level executes itself:
> 
> #{
>if $baz {
>$foo.bar
>}
> }
> 
> To uncomment, remove the # before the {.

This is exactly the type of construct that I had in mind.  A couple of
questions. Is code inside of a #{}:

- parsed and required to be syntacticly correct?
- does it still appear in emitted code?
- what happens when a goto tries to enter into this block
  or a nested sub is invoked?
- will the optimizer spend time on this block?

-J

--


pgpBcbDq8OUQ3.pgp
Description: PGP signature

Re: multi-line comments, C macros, & Pod abuse

[Daniel Hulme]

> "Stuart Cook" schreef:
> > Larry Wall:
> 
> >> if 0 {
> >> ...
> >> }
> >
> > The one disadvantage of that approach is that it will break if the
> > "commented-out" code temporarily fails to compile.
> 
> How frequent does that happen?
All the time. I often comment out bits of code while I'm refactoring or
such, because I've removed some functions or that the code depends on
s.t. it won't compile any more, I want to compile it to check that the
bits I've done work, and I want the commented-out code visible to remind
me to rewrite it later.

> And in that case s/if 0/\#/, as Luke mentioned.
> And if the compile failure has to do with {}, use other braces.
As you say, alternatives are available.

> But would the following work?
> 
> 0 or q:to/END42/
>   ...
> END42
Shouldn't it be C<0 and> if you don't want the RHS (or C<1 or>, I
suppose)? In either case, wouldn't this have the side-effect of setting
the last-evaluated value, which might also be undesired.

-- 
I will take my life into my hands And I will use it.'MacArthur Park'
I will win the worship in their eyes And I will lose it.  Jimmy Webb
I will have the things that I desire(( http://surreal.istic.org/
And my passion flow like rivers to the sky  (( It's like a DEATH CIRCUS!


pgpsHubb64lJ2.pgp
Description: PGP signature

Re: multi-line comments, C macros, & Pod abuse

[Dr.Ruud]

"Stuart Cook" schreef:
> Larry Wall:

>> if 0 {
>> ...
>> }
>
> The one disadvantage of that approach is that it will break if the
> "commented-out" code temporarily fails to compile.

How frequent does that happen?

And in that case s/if 0/\#/, as Luke mentioned.
And if the compile failure has to do with {}, use other braces.


But would the following work?

0 or q:to/END42/
  ...
END42

-- 
Affijn, Ruud

"Gewoon is een tijger."

Re: multi-line comments, C macros, & Pod abuse

[Nicholas Clark]

On Sat, Aug 19, 2006 at 02:26:28AM +, Luke Palmer wrote:
> On 8/19/06, Aaron Crane <[EMAIL PROTECTED]> wrote:
> >You don't actually need a macro in that case:
> >
> >if 0 { q<
> >...
> >> }
> 
> Which, of course, eliminates the original desire to have a
> code-commenting construct where "you just change the 0 to a 1".  After
> all, we already have #{}.  Incidentally, you could consider that the
> desired construct, because it balances, and a closure at statement
> level executes itself:
> 
> #{
>if $baz {
>$foo.bar
>}
> }
> 
> To uncomment, remove the # before the {.

Or in the same vein

if 0 { q<

# > }


To uncomment the real code, add # before the if.

Although it is visually complex.

Nicholas Clark

Re: multi-line comments, C macros, & Pod abuse

[Luke Palmer]

On 8/19/06, Aaron Crane <[EMAIL PROTECTED]> wrote:

You don't actually need a macro in that case:

if 0 { q<
...
> }


Which, of course, eliminates the original desire to have a
code-commenting construct where "you just change the 0 to a 1".  After
all, we already have #{}.  Incidentally, you could consider that the
desired construct, because it balances, and a closure at statement
level executes itself:

#{
   if $baz {
   $foo.bar
   }
}

To uncomment, remove the # before the {.

Luke

Re: multi-line comments, C macros, & Pod abuse

[Aaron Crane]

Stuart Cook writes:
> On 8/19/06, Larry Wall <[EMAIL PROTECTED]> wrote:
> >if 0 {
> >...
> >}
> 
> The one disadvantage of that approach is that it will break if the
> "commented-out" code temporarily fails to compile.  If that's a
> problem, though, you could always write your own macro.

You don't actually need a macro in that case:

if 0 { q<
...
> }

And if you have unbalanced quote-delimiting brackets in the "...", you can
switch to different bracketing characters (including arbitrary Ps/Pe or
bidi-mirroring Unicode pairs), or simply add more brackets:

if 0 { q
... # >>> with unmatched pointies
 }

-- 
Aaron Crane

Re: multi-line comments, C macros, & Pod abuse

[Stuart Cook]

On 8/19/06, Larry Wall <[EMAIL PROTECTED]> wrote:


if 0 {
...
}


The one disadvantage of that approach is that it will break if the
"commented-out" code temporarily fails to compile.  If that's a
problem, though, you could always write your own macro.


Stuart Cook

Re: multi-line comments, C macros, & Pod abuse

[Larry Wall]

On Fri, Aug 18, 2006 at 11:58:20AM -1000, Joshua Hoblitt wrote:
: It occurred to me that other day that in our "in house" C code we
: somewhat frequently use an idiom that's not easily translated into Perl
: 5.  Our rule is that if your commenting out more then 1 or 2 lines of
: code that you wrap it in a CPP if statement.  The logic being that
: if you haven't deleted the code then it must have some reason of hanging
: around (and you may actually want to use it again someday).  This is most
: often the case with specialized debugging code. E.g.
: 
: #if 0
: ...
: #endif

if 0 {
...
}

: The great thing about this is that the you only have to flip the 0 to 1
: to re-enable the code. E.g.
: 
: #if 1
: (magic now happens)...
: #endif

if 1 {
(magic now happens)...
}

Larry

multi-line comments, C macros, & Pod abuse

[Joshua Hoblitt]

It occurred to me that other day that in our "in house" C code we
somewhat frequently use an idiom that's not easily translated into Perl
5.  Our rule is that if your commenting out more then 1 or 2 lines of
code that you wrap it in a CPP if statement.  The logic being that
if you haven't deleted the code then it must have some reason of hanging
around (and you may actually want to use it again someday).  This is most
often the case with specialized debugging code. E.g.

#if 0
...
#endif

The great thing about this is that the you only have to flip the 0 to 1
to re-enable the code. E.g.

#if 1
(magic now happens)...
#endif

The best equivalent I've been able to come up with in Perl 5 is:

=for off
...
=cut

&

#=for off
(magic now happens)...
=cut

Except that now this requires all sorts of weird voodoo to keep the Pod 
formatting from breaking.

This thread seems to suggest the situation isn't going to change much if
at all in Perl 6:

http://groups.google.com/group/perl.perl6.language/browse_thread/thread/45f5be3ca97d1d82/cd5f1daa256be9b9?lnk=gst&q=multiline+comments&rnum=1#cd5f1daa256be9b9

I guess the point I'm trying to make here is that multi-line comments
about the code and disabled chunks of code are or should be distinct
functionalities.  One can make the argument that any code you want to
disable in the manner I've described should be factored out into it's
own function, so that just the call to the function can be commented
out.  The hard reality is that it's not always so easy or desirable to
do that.  Is there any hope of getting some equivalent "disabled code
chunk" functionality in the perl6 core?

Cheers,

-J

--


pgp86uJCumyZZ.pgp
Description: PGP signature

Re: Linking Synopses to corresponding pod-files?

[Markus Laire]

On 5/4/06, Juerd <[EMAIL PROTECTED]> wrote:

Markus Laire skribis 2006-05-04 14:55 (+0300):
> When reading Synopses, I sometimes notice some mistakes or typos,
> which I'd like to submit a patch for, but it's not easy to do so as I
> don't know where to get the source.

Have you tried s/html/pod/? :)


Thanks :)

--
Markus Laire

Re: Linking Synopses to corresponding pod-files?

[Juerd]

Markus Laire skribis 2006-05-04 14:55 (+0300):
> When reading Synopses, I sometimes notice some mistakes or typos,
> which I'd like to submit a patch for, but it's not easy to do so as I
> don't know where to get the source.

Have you tried s/html/pod/? :)


Juerd
-- 
http://convolution.nl/maak_juerd_blij.html
http://convolution.nl/make_juerd_happy.html 
http://convolution.nl/gajigu_juerd_n.html

Linking Synopses to corresponding pod-files?

[Markus Laire]

When reading Synopses, I sometimes notice some mistakes or typos,
which I'd like to submit a patch for, but it's not easy to do so as I
don't know where to get the source.

Could each Synopsis include a link to the corresponding .pod (if it's
available in Internet, that is), so that submitting patches would be
easier?

--
Markus Laire

Re: S05.pod

[Trey Harris]

In a message dated Mon, 17 Apr 2006, Sean Sieger writes:


from

There are no C or C modifiers (changes to the meta-characters
replace them - see below).

to

There are no C or C modifiers (change to the meta-characters
that replace them - see below).


I don't think so  There are no meta-characters that replace /s and /m 
one-for-one, so it can't be an imperative command to change.  It's the 
plural noun "changes", as in, "they are replaced with changes to the 
meta-characters".  The original is correct.


Trey

S05.pod

[Sean Sieger]

from

There are no C or C modifiers (changes to the meta-characters
replace them - see below).

to

There are no C or C modifiers (change to the meta-characters
that replace them - see below).

Re: [PATCH] Re: apo/A06.pod: spelling error(s)?

[Patrick R. Michaud]

On Wed, Apr 20, 2005 at 08:13:20PM +0200, Steven Philip Schubiger wrote:
> On 20 Apr, Luke Palmer wrote:
> : Steven Philip Schubiger writes:
> :> In
> :> macro circumfix:(*...*) () is parsed(/.*?/ { "" }
> :> 
> :> is the second enclosing part of the "parsed" parentheses omitted
> :> by intention? If not, I'd volunteer to provide a patch.
> : 
> : Fixed.  Thanks.
> : 
> : Luke
> 
> You missed some.

Fixed some.  Thanks!

Pm

[PATCH] Re: apo/A06.pod: spelling error(s)?

[Steven Philip Schubiger]

On 20 Apr, Luke Palmer wrote:
: Steven Philip Schubiger writes:
:> In
:> macro circumfix:(*...*) () is parsed(/.*?/ { "" }
:> 
:> is the second enclosing part of the "parsed" parentheses omitted
:> by intention? If not, I'd volunteer to provide a patch.
: 
: Fixed.  Thanks.
: 
: Luke

You missed some.

Steven

--- perl6/doc/trunk/design/apo/A06.pod  Wed Apr 20 20:03:19 2005
+++ perl6/doc/trunk/design/apo/A06.pod  Wed Apr 20 20:05:32 2005
@@ -3004,12 +3004,12 @@
 interpolated with a special C< ... > marker, which is considered part
 of the name:
 
-macro circumfix:(*...*) () is parsed(/.*?/ { "" }
+macro circumfix:(*...*) () is parsed(/.*?/) { "" }
 
 [Update: That's now solved by use of existing slice syntax:
 
-macro circumfix:<(* *)> () is parsed(/.*?/ { "" }
-macro circumfix:{'(*', '*)'} () is parsed(/.*?/ { "" }
+macro circumfix:<(* *)> () is parsed(/.*?/) { "" }
+macro circumfix:{'(*', '*)'} () is parsed(/.*?/) { "" }
 
 That's so convenient that we'll discard the special rule about
 splitting symmetrically in favor of requiring a two element slice.]

Re: apo/A06.pod: spelling error(s)?

[Luke Palmer]

Steven Philip Schubiger writes:
> In
> macro circumfix:(*...*) () is parsed(/.*?/ { "" }
> 
> is the second enclosing part of the "parsed" parentheses omitted
> by intention? If not, I'd volunteer to provide a patch.

Fixed.  Thanks.

Luke

apo/A06.pod: spelling error(s)?

[Steven Philip Schubiger]

In
macro circumfix:(*...*) () is parsed(/.*?/ { "" }

is the second enclosing part of the "parsed" parentheses omitted
by intention? If not, I'd volunteer to provide a patch.

Steven

Re: [PATCH] apo/A06.pod: spelling error(s)

[Patrick R. Michaud]

On Sun, Apr 17, 2005 at 02:52:27PM +0200, Steven Philip Schubiger wrote:
> A spelling mistake and a word, that supposedly has been forgotten.
> 
> Steven

Applied, thanks!

Pm



> --- apo/A06.pod   Sun Apr 17 14:34:16 2005
> +++ apo/A06.pod   Sun Apr 17 14:42:37 2005
> @@ -2021,7 +2021,7 @@
>  
>  All blocks are considered closures in Perl 6, even the blocks
>  that declare modules or classes (presuming you use the block form).
> -A closure is just an anonymous subroutine that has access its lexical
> +A closure is just an anonymous subroutine that has access to its lexical
>  context.  The fact that some closures are immediately associated
>  with names or have other kinds of parameter declarations does not
>  change the fact that an anonymous bare block without parameters is
> @@ -3509,7 +3509,7 @@
>  
>  On the other hand, this means that any unrecognized word followed by
>  a list may unambiguously be taken to be a multimethod being called
> -as a list operaotr.  After all, we don't know when someone will be
> +as a list operator.  After all, we don't know when someone will be
>  adding more multimethods.  I currently think this is a feature, but
>  I could be sadly mistaken.  It has happened once or twice in the past.
>  

[PATCH] apo/A06.pod: spelling error(s)

[Steven Philip Schubiger]

A spelling mistake and a word, that supposedly has been forgotten.

Steven

--- apo/A06.pod Sun Apr 17 14:34:16 2005
+++ apo/A06.pod Sun Apr 17 14:42:37 2005
@@ -2021,7 +2021,7 @@
 
 All blocks are considered closures in Perl 6, even the blocks
 that declare modules or classes (presuming you use the block form).
-A closure is just an anonymous subroutine that has access its lexical
+A closure is just an anonymous subroutine that has access to its lexical
 context.  The fact that some closures are immediately associated
 with names or have other kinds of parameter declarations does not
 change the fact that an anonymous bare block without parameters is
@@ -3509,7 +3509,7 @@
 
 On the other hand, this means that any unrecognized word followed by
 a list may unambiguously be taken to be a multimethod being called
-as a list operaotr.  After all, we don't know when someone will be
+as a list operator.  After all, we don't know when someone will be
 adding more multimethods.  I currently think this is a feature, but
 I could be sadly mistaken.  It has happened once or twice in the past.
 

Re: [PATCH] apo/A05.pod: spelling error

[Patrick R. Michaud]

On Thu, Apr 07, 2005 at 11:13:42PM +0200, Steven Schubiger wrote:
> Attached is a patch that fixes a minor spelling error
> in apocalypse 5.

Applied, thanks!

Pm

[PATCH] apo/A05.pod: spelling error

[Steven Schubiger]

Attached is a patch that fixes a minor spelling error
in apocalypse 5.

Steven

--- A05.pod.origThu Apr  7 22:59:16 2005
+++ A05.pod Thu Apr  7 22:59:56 2005
@@ -2179,7 +2179,7 @@
 tree of objects.
 
 Matching against such boundaries or metadata would not be possible
-unless ether the regex engine is aware that it is matching against an
+unless either the regex engine is aware that it is matching against an
 array, or the string emulation provides visibility through the abstract
 string into the underlying array. The latter may be preferable, since
 (by the rules of the C<=~> matrix discussed in Apocalypse 4) C<@array

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Sam Vilain]

Damian Conway wrote:
[No, I'm not back; I'm just passing by. But I feel that I need to 
comment on this whole issue]
Thanks!  This message has lots of useful information that I would have 
otherwise probably missed.

It seems that the basic premise of the POD document object model gels 
well with that early design document, so I look forward to being able to 
flesh out the details.

Using ^=\s to delimit a line starting with a = will interfere with the 
Kwid method of:

 = Heading
 foo
Which I was imagining would be converted to a DOM tree that when 
represented in the "Normative XML" would look like:

 
   Heading
   foo
 
That's sort of DocBook style, and in fact I was thinking that for the 
internal representation, DocBook node names could be used where there is 
no other better alternative.  Of course, non-documentation things like 
Test fragments or inclusions of external entities, like UML diagrams 
won't have a representation in DocBook :-).

The uses of a leading = in a paragraph are fairly uncommon.  For 
instance, when quoting POD you would simply indent it a bit to make it 
verbatim and there is no issue.

I see a middle ground; that is, `=` quoting is only is allowed if it 
directly follows the initial POD marker;

 =head1 Foo
 =
 = =head1
 = =
 = = =head1 That's just getting ridiculous
Which I see as represented by;
 
   Foo
   =head1
 =
 = =head1 That's just getting ridiculous
 
Which of course would lose the ='s.  But that's OK, because if you 
wanted verbatim you could have just indented the block.

If you wanted to lead a normal paragraph with it, you'd just use the 
normally implicit =para (equivalent to =pod):

 =para
 =
 = = This is what a Kwid =head1 looks like
As for going with =kwid to denote the starting of kwid, I have so far 
been pessimistically assuming that something like `=dialect kwid`, or 
`=use kwid` (as described in the design doc you attached) would be 
required.  However, we could allow `=unknown`, where `unknown` is an 
unknown keyword, to try to load Pod::Dialect::unknown, and hope like 
hell it provides the Role of Pod::Dialect.

While the `^=` escaping is “active”, the presence or absence of 
whitespace following the initial `=` will delimit breaks in paragraphs. 
 This has to be so, otherwise the previous example would have been:

 
   Foo
 =head1
 =
 = =head1 That's just getting ridiculous
 
 
Which is just plain silly.  This follows what people are used to with 
POD - blank lines must be empty, not just no non-whitespace characters 
(an increasingly vague concept these days).

So, the POD processing happens in 3 levels (note: the first isn't really 
mentioned in perlpodspec.kwid, which is a bug);

=list
- chunkification from the original source, into POD paragraphs, which 
may or may not include an initial `^=foo` marker.  At *this* level, the 
only escaping that happens is the `^=` escaping.

That's all that needs to happen while the code is being read, and for 
most code that is how the POD will remain, in memory, somewhere 
intermingled with the Parse Tree for the code, so that the code can 
still be spat back out by the P6 equivalent of `B::Deparse`

- parsing of these raw chunks into a real POD DOM.  Please, tired XML 
veterans, please don't get upset by the use of the term "DOM", I think 
the last thing anyone wants is to have studlyCaps functions like 
`getElementById` and `createTextNode`.  It is the tree concept itself 
which is important, and this pre-dates XML anyway.

Strictly speaking, this step actually converts POD paragraph chunk 
events into POD DOM events.  These can be used to build a real DOM, for 
instance if you need to do an XPath style query for a link (I was amazed 
that someone's actually gone and built Pod::XPath!), or they might 
simply be passed onto the next stage by an output processor with no 
intermediate tree being built.

So, at this point, dialects get hooks to perform custom mutation of POD 
paragraph events into DOM events, and the arbitrator of this process 
ensures that the output events are well "balanced" by spitting out 
closing tags where it has to.  They can store state in their parser 
object, but none of this state will be preserved past the parsing state.
However, the nodes that they "spit out" after this point may still not 
be "core" POD, such as for includes or out-of-band objects.  These hooks 
will be sufficient to allow them to hijack subsequent chunks that would 
otherwise be served to other dialects, ie, they can choose to 
"arbitrate" subsequent chunks.

I'm aiming to make it so that it is possible for dialects to be "round 
trip safe", by being able to go back from this DOM state to the original 
POD paragraph chunks.  This would require dialects to "play nice" of 
course, but is a potential option to help make things like smart text 
editors be able to

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Damian Conway]

Oh, and I forgot to mention:
In the contents of any block, any line with '=' in column zero and a 
whitespace character in column 1, has those two characters removed when the 
contents are extracted. So you can write:

=begin data POSSIBLE_POD_DIRECTIVES
=
= =doh -- Oh, dear! Oh frikking dear!
= =ray -- A ravening beam of destruction
= =me  -- A name I call my invocant
= =far -- A long, long way to Australia
= =sew -- What I do with contention
= =LA  -- A place to follow trends
= =tee -- I pipe to double streams
=
=end data
To create the inline data:
=doh -- Oh, dear! Oh frikking dear!
=ray -- A ravening beam of destruction
=me  -- A name I call my invocant
=far -- A long, long way to Australia
=sew -- What I do with contention
=LA  -- A place to follow freaks
=tee -- I pipe to double streams
Damian

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Damian Conway]

[No, I'm not back; I'm just passing by. But I feel that I need to comment on 
this whole issue]

Even before Brian announced Kwid, I was privately suggesting to Larry that 
Markdown (http://daringfireball.net/projects/markdown/) was an excellent 
evolution of mark-up notations and might be well suited to Perl 6. At 
least...as a second allowable syntax.

And, in my view, Kwid kicks Markdown's butt in terms of its suitability for 
Perl documentation. POD itself is brilliant and we should certainly not 
abandon it, but it's critical to remember that POD is just an *interface* (or 
B, if you prefer ;-) to Perl's built-in documentation systems. I 
strongly believe that Kwid is, for many purposes, a cleaner and less-intrusive 
interface, and I for one will be using it (even if I have to build a kwid2pod 
translator).

But frankly, I'd rather just be able to write:
=kwid
in place of
=pod
within standard Perl 6.
As for the larger issue of redoing pod, I've appended my notes on where the 
Design Team left their discussions when last we discussed it. This might spark 
some ideas (but note that I will not be able to respond to them any time soon 
-- alas, bread-winning must, for the moment, take precedence over most of my 
public activities).

Damian
-cut--cut--cut--cut--cut-
There would be a single consistent rule that says that every POD block
(except raw text blocks) has one of the following three equivalent
syntactic forms:
=begin  TYPE  OPTIONAL_MULTIWORD_LABEL_TO_END_OF_LINE
BLOCK_CONTENTS_START_HERE_AND_CONTINUE_OVER_MULTIPLE_LINES_UNTIL...
=end  TYPE  OPTIONAL_SAME_MULTIWORD_LABEL
or:
=for  TYPE  OPTIONAL_MULTIWORD_LABEL_TO_END_OF_LINE
BLOCK_CONTENTS_START_HERE_AND_CONTINUE_OVER_MULTIPLE_LINES_UNTIL...

or:
=TYPE  BLOCK_CONTENTS_START_HERE_AND_CONTINUE_OVER_MULTIPLE_LINES_UNTIL...

For example:
=begin table Table of Contents
Constants   1
Variables   10
Subroutines 33
Everything else 57
=end table
=begin list
=begin item *
Doh
=end item
=begin item *
Ray
=end item
=begin item *
Me
=end item
=end list
=begin comment
This is the most verbose way to write all this
=end comment
Or equivalently:
=for table Table of Contents
Constants   1
Variables   10
Subroutines 33
Everything else 57
=begin list
=for item *
Doh
=for item *
Ray
=for item *
Me
=end list
=for comment
This is a less verbose way to write all this
Or also equivalently:
=for table Table of Contents
Constants   1
Variables   10
Subroutines 33
Everything else 57
=for list
=item * Doh
=item * Ray
=item * Me
=comment This is the least verbose way to write all this
POD formatters could then be simply and consistently implemented by
inheriting from a standard Pod::Base class, which would provide a
C<.parse_pod> method that sequentially extracts each block construct (from
whichever of the three syntaxes), including raw text blocks (which are
actually just unlabelled C<=for body> blocks), and raw code blocks
(which are actually just unlabelled C<=for verbatim> blocks).
C<.parse_pod> would be something like:
multi method parse_pod ($self: Str $from_str) {
# Get sequence of POD blocks to be parsed
# Using standard rules...
my @blocks = $self.extract_pod($from_str);
# Dispatch each block to be processed by the
# appropriate method...
for @blocks -> $block {
my ($type, $label, $contents) = $block;
$self.$type($label, $contents);
}
}
When each C<.$type()> method is called, both the label and contents would
passed as simple strings (either of which might, of course, be empty if
the corresponding component had been omitted from the block). The
(multi)method thus selected would then be responsible for
formatting/processing/whatevering the label and contents passed to it:
method head1 ($label, $contents) {...}
method head2 ($label, $contents) {...}
method list ($label, $contents) {...}
method item ($label, $contents) {...}
# etc.
Note that under this scheme the Perl5 syntax for:
=head1 Title here
=head2 Subtitle here
=head3 Subsubtitle here
=head4 Subsubsubsubtitle here
=item  Bullet  Item text
=cut
=pod
would mostly all continue to work (though, of course, C<=cut> and
C<=pod> would actually be dealt with directly within C<.extract_from>).
The most noticable change would be that something like:
=item Bullet
Text of item here
would now have to be written either as:
=item  Bullet  Text of item here
(an improvement, I suspect), 

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[David Storrs]

On Thu, Mar 17, 2005 at 05:04:53PM -0500, Aaron Sherman wrote:
> On Thu, 2005-03-17 at 12:28, Brian Ingerson wrote:
> 
> > The interesting thing to me is that all 3 syntaxes map over the same
> > data model and thus are easily interchangable. 
> 
> It is, however, contrary to the spirit of POD for you or me to continue
> much further down this road (see below).
> 
> > Sam "mugwump" Vilain [...]
> > is working on more formally defining the common model or "AST" that
> > these dialects map to.
> 
> My effort here was to try to PREVENT the proliferation (e.g. by Kwid and
> POD butting heads and ending up in a stalemate). 
>
> I'll continue only as far as is needed to propose this in full as an
> example parser / converter, and then I'm going to stop. 


If Brian is correct about the fundamental interchangeability of these
dialects (and I have no reason to think he isn't), may I suggest that
the simple answer is to have a program which can translate from one
dialect to another--just like we distribute pod2man, pod2html, and
pod2text, we would now distribute pod2kwid and ajskwid2pod.

--Dks
-- 
[EMAIL PROTECTED]

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[gcomnz]

On Thu, 17 Mar 2005 16:16:00 -0700, gcomnz <[EMAIL PROTECTED]> wrote:
Brent 'Dax' Royal-Gordon <[EMAIL PROTECTED]> wrote:
 >By the way, I think I've seen a few people suggest some sort of
 >syntax-switching mechanism for "Pod6".  The day people have to think
 >about what dialect of Pod they're using is the day Pod dies as a
 >useful documentation language.
 
1. TMTOWTDI
 
2. Competition will help, not hinder. I for one would very much like
 to see a more Wiki and less POD like syntax. But that's a matter of
 taste. I will say though that I've never heard of anyone suffering
 because of how wide or narrow the [ and ] characters are in Wiki
 markup ;-).  And MediaWiki's format is a beautiful example of a markup
 that has taken off and vastly simplified page creation and editing for
 over 100,000 editors at Wikipedia.
 
 3. A format like I  or C is just plain ugly and verbose. I
 can't imagine why anyone defends that as something too keep. In
 understand there's a lot of love/hate emotion when it comes to Wiki's,
 but if we step back and ignore for a moment what the alternatives are
 will we really still want to keep that ugly inline syntax? (No
 disrespect intended, POD clearly predates of lot of other ideas about
 simple markups.)
 
 Marcus

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Sam Vilain]

Aaron Sherman wrote:
Sam "mugwump" Vilain refers to each of these syntaxes as /Pod dialects/.
He is working on more formally defining the common model or "AST" that
these dialects map to.
Why? Seriously, why on earth do you want to encourage the proliferation
of variant markup languages?! There aren't enough?
My effort here was to try to PREVENT the proliferation (e.g. by Kwid and
POD butting heads and ending up in a stalemate). The only problem is
that, presented with a compromise, the Kwid folks seem to be content to
ADD it to the list of variants rather than, in fact, compromise and
collapse the list.
I'll continue only as far as is needed to propose this in full as an
example parser / converter, and then I'm going to stop. My goal is not
to proliferate the number of markups further, and I'd MUCH rather see
Perl 6 rely on POD than fragment the SINGLE MOST IMPORTANT TASK in
creating code to share with the world: documentation.
Well, I don't think anyone wants to see as many POD dialects as there
are wiki text formats (BBCode, anyone?).  Maybe there will be something
very close to the original POD, but with a verbose way of making tables,
and an enhanced linking syntax.  But otherwise identical to the original
Perl 5 POD.
Note that POD dialects, and differing POD conventions already exist in
Perl 5 and are in common use.  They were designed in the original POD
with the =for tag.  At the moment, tools like `pod2html' have to be
heavily aware of the POD dialect, which I think is sub-optimal when it
comes to some of the really interesting things people have achieved
with POD.  Look at MarkOv's OODoc, or Test::Inline, for instance.
All I'm trying to do is giving these beasts a name, and defining a
mechanism by which they can be used by tools that only know how to deal
with "standard" documents - thus giving users the freedom to define a
local convention if one of them doesn't quite fit their needs.
Using a local Subversion repository, and Request Tracker, and want to
be able to put hyperlinks in POD to refer to these entities?  No
problem, just extend the dialect and add a link style.  Then select
from a dozen output tools or variants to see which one works for you.
Sam.

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Aaron Sherman]

On Thu, 2005-03-17 at 17:07, Brent 'Dax' Royal-Gordon wrote:
> Aaron Sherman <[EMAIL PROTECTED]> wrote:

> > and the hacks in
> > pod syntax (e.g. C<< < >>) to get around this are glaring anti-
> > huffmanisms.
> 
> Whatever bracketing character we decide to use, there will always be
> occasions where we need to use it in an unbalanced way within a
> formatting code.

Absolutely yes. See C[...] vs C{...} vs C[\]]

I'm pointing out that the ROUTINE case is to need < and > in unbalanced
ways. Hence we have names for them that to not involve the words "open",
"close", "left" or "right". We could name "[", "fobit", but then people
would automatically call "]" a "right-fobit" or a "close-fobit". We look
at a piece of code or documentation that contains an un-balanced fobit
and we get a little chill because it's WRONG somehow. THAT is the kind
of balanced operator you want to tie your documentation to.

> > > The most common use of them in Perl 5--method call/dereference--is
> > > going away in Perl 6
> > 
> > Hmm, I remain unconvinced of that as the most common use, especially
> > with the copious use of =>. Still, in my local source tree you're right,
> > though by < a factor of 2.
> 
> Are you looking at your entire source tree, or just the Pod in it? 
> The code in Pod--and especially the short snippets of code typically
> included in a C<> construct--is very different from arbitrary Perl
> code.

I EXPLICITLY ignored POD. I don't have the find+perl that I used handy
any more, but I was counting state every time I saw an "^=[hoib]" and
decrementing state every time I saw an "^=cut" so that I only counted
code... I probably caught some strange gunk after __END__ and __DATA__
tags, but not enough to throw the stats that far off.

It was 23k vs. 44k.

> > Perl 6 also adds new uses of E and E for pipelining, and further
> > expands the usefulness of the => operator as a pair constructor. Rules
> > also add new uses of these characters, but those are balanced, so
> > improving POD with a real grammar specification would solve for that.
> 
> I definitely support intelligently defining the way Pod handles angle
> brackets which aren't part of a formatting code.  I also think writing
> a reference grammar would be an excellent idea.

Already done, see my previous message. It's still brain-dead in some
places, and I need to re-work it to correctly handle nested operations
(e.g. B[I[...]]), but I'll have that soon. It will also, I've decided,
parse POD. Just as Perl 6 parses Perl 5 by recognizing the first few
statements, AJS Kwid will recognize "=head.*" as an indication that POD
is being used, and parse it into KwidData internally so that the same
tools could be used.

I'm stopping once it works. I'm not looking to fork POD. If people don't
like the proposal, once they can play around with it, then I'll drop it.

-- 
Aaron Sherman <[EMAIL PROTECTED]>
Senior Systems Engineer and Toolsmith
"It's the sound of a satellite saying, 'get me down!'" -Shriekback

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Brent 'Dax' Royal-Gordon]

Aaron Sherman <[EMAIL PROTECTED]> wrote:
> > Specifically, I like the use of angle brackets in Pod.  Angle brackets
> > are simple, distinctive shapes; they remain wide in variable-width
> 
> This is aesthetic preference. I could cite the reasons that I have an
> aesthetic preference for the other syntax, but the reality is that angle
> brackets aren't angle brackets; they are less-than (E) and greater-
> than signs (E). We ignore this fact at our peril, 

Only in name.  Years of HTML and Perl have trained me to treat these
as bracketing constructs, and Perl 6 is set to increase that use.

> and the hacks in
> pod syntax (e.g. C<< < >>) to get around this are glaring anti-
> huffmanisms.

Whatever bracketing character we decide to use, there will always be
occasions where we need to use it in an unbalanced way within a
formatting code.  (Though I do admit that angle brackets are more
likely to be unbalanced than other characters.)

The problem I have with square brackets specifically is that they get
lost really easily, especially in variable-width fonts.  Gmail, for
example, displays e-mail in a sans-serif font, and virtually all such
fonts have narrow square brackets.  The square brackets in your
examples were visually lost in the surrounding text--without spaces,
square brackets are invisible.  That's okay when you're subscripting,
because your brain doesn't really need them to understand what's going
on, but it's not when you're applying and reading formatting codes.

Further, although Perl 6 is the time to make such a change, I'm not
convinced the change is really necessary.  We might be able to avoid a
few uses of C<< >>, but is that a big enough win to change *yet
another* aspect of Perl?  Especially an aspect programmers can--and
traditionally did--ignore?

> > The most common use of them in Perl 5--method call/dereference--is
> > going away in Perl 6
> 
> Hmm, I remain unconvinced of that as the most common use, especially
> with the copious use of =>. Still, in my local source tree you're right,
> though by < a factor of 2.

Are you looking at your entire source tree, or just the Pod in it? 
The code in Pod--and especially the short snippets of code typically
included in a C<> construct--is very different from arbitrary Perl
code.

> Perl 6 also adds new uses of E and E for pipelining, and further
> expands the usefulness of the => operator as a pair constructor. Rules
> also add new uses of these characters, but those are balanced, so
> improving POD with a real grammar specification would solve for that.

I definitely support intelligently defining the way Pod handles angle
brackets which aren't part of a formatting code.  I also think writing
a reference grammar would be an excellent idea.

> Thanks Brent, I'm not sure if you intended your mail as an endorsement,
> but other than one sticking point, you and I appear to be on the same
> page. Thank you for your message.

I intended my e-mail to be an endorsement of Pod as it exists, with
extensions rather than a redesign.  I think you have mostly the right
idea, but I really don't think switching to square brackets is
necessary.


By the way, I think I've seen a few people suggest some sort of
syntax-switching mechanism for "Pod6".  The day people have to think
about what dialect of Pod they're using is the day Pod dies as a
useful documentation language.

-- 
Brent 'Dax' Royal-Gordon <[EMAIL PROTECTED]>
Perl and Parrot hacker

"I used to have a life, but I liked mail-reading so much better."

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

[Aaron Sherman]

On Thu, 2005-03-17 at 12:28, Brian Ingerson wrote:

> The interesting thing to me is that all 3 syntaxes map over the same
> data model and thus are easily interchangable. The other interesting
> thing is that all three could be supported without affecting the Perl5
> or Perl6 syntax proper.

If any of the above was news to you, then I suggest you take another
look at why POD (and more generally, any abstract markup language)
exists. If any of the above were NOT true, it would be contrary to the
entire point of an abstract, layout-neutral markup language.

It is, however, contrary to the spirit of POD for you or me to continue
much further down this road (see below).

> Sam "mugwump" Vilain refers to each of these syntaxes as /Pod dialects/.
> He is working on more formally defining the common model or "AST" that
> these dialects map to.

Why? Seriously, why on earth do you want to encourage the proliferation
of variant markup languages?! There aren't enough?

My effort here was to try to PREVENT the proliferation (e.g. by Kwid and
POD butting heads and ending up in a stalemate). The only problem is
that, presented with a compromise, the Kwid folks seem to be content to
ADD it to the list of variants rather than, in fact, compromise and
collapse the list.

I'll continue only as far as is needed to propose this in full as an
example parser / converter, and then I'm going to stop. My goal is not
to proliferate the number of markups further, and I'd MUCH rather see
Perl 6 rely on POD than fragment the SINGLE MOST IMPORTANT TASK in
creating code to share with the world: documentation.

If I'm left on a desert island with POD, then the only part I'll lament
is the desert island.

-- 
Aaron Sherman <[EMAIL PROTECTED]>
Senior Systems Engineer and Toolsmith
"It's the sound of a satellite saying, 'get me down!'" -Shriekback