Re: S02 questions and comments

[Larry Wall]

On Sun, Mar 30, 2008 at 04:35:56PM -, John M. Dlugosz wrote:
: Meta-question 2: Does this belong on a different mailing list?  I'm also 
including the documented file maintainer as a direct recipient.

This is the right list.  There is no need to cc the maintainers,
since they all read this list (or if they do not, are not really the
maintainers any more...)

: 4: "Whitespace is not allowed between a variable name and its subscript. 
However, there is a corresponding dot form of each subscript"
: The use of "however" looks like it is meant to imply that the dot form allows 
you to add space.  I think this wording is leftover from the "long dot" 
explanation, but now is out of place.  I suggest dropping the "However," from 
the sentence.

Fixed by unpacking what I really meant by the "however".  :)

Larry

Re: S02 questions and comments

[Agent Zhang]

On 30 Mar 2008 16:35:56 -, John M. Dlugosz <[EMAIL PROTECTED]> wrote:
> I'm reading S02.pod with version information:
>   Last Modified: 17 Mar 2008
>   Number: 2
>   Version: 130
>
>  Meta-question 1: what is the succinct way to report this?  Is the "Version 
> 130" enough?

The SVN revision number is sufficient. By default we're just
pretending that we're referring to "the svn head".

>  3: I copied the file from  
> which I'm told is the up-to-date home.  When I ran pod2html, I got a warning 
> that 'encoding' is an unknown directive, and also see that the HTML title is 
> simply "TITLE".  Do I need a special version of pod2html, or how do I run it 
> properly?
>

IMHO pod2html is old and broken in various ways. I think you should
use the tools provided by Pod::Simple instead. For the Synopses on
feather, we're using the podhtml.pl script (based on
Pod::Simple::HTML):

http://svn.pugscode.org/pugs/util/podhtm.pl

Hopefully you may find it useful :)

Cheers,
-agentzh

S02 questions and comments - unspace

[John M. Dlugosz]

"Any contiguous whitespace (including comments) may be hidden from the parser 
by prefixing it with \. ... using unspace lets you line up postfix 
operators:"

%hash\  .{$key}
@array\ .[$ix]
$subref\.($arg)


What does the dotted form have to do with this?  It just confuses the example.

%hash\   {$key}
@array\  [$ix]
$subref\ ($arg)

Then, explain that 

"the dotted form can further help line up on arbitrary boundaries, since 
the unspace requires at least two characters.  If you need to shift the postfix 
over by only one character, use a dot.

%hash\ {$key}
@array.[$ix]
$subref($arg)

If you wish to use dots on all the lines for consistency, you might end up with 
something like:

%hash\  .{$key}
@array\ .[$ix]
$subref\.($arg)

As a special case to support this, a backslashed dot where a postfix is 
expected is considered a degenerate form of unspace. 
ORIGINAL TEXT CONTINUES



"Whitespace is not allowed before the parens, but there is a corresponding .() 
operator, plus the ``unspace'' forms that allow you to insert optional 
whitespace and comments between the backslash and the dot:"

The dotted form is not required to use unspace to insert optional whitespace.  
State that this is the same as the deal with subscripts, and xref the thing I 
opened this note with.

-

MyType\ .::\ .{'$foo'}  # same thing with unspaces


That is the same thing with unspaces AND dots.

MyType\ ::\ {'$foo'}  # same thing with unspaces

could be added to the list, right?

--

You can also use the :key($value) form to quote the keys of option pairs. To 
align values of option pairs, you may use the ``unspace'' postfix forms:

:longkey\  .($value)
:shortkey\ .
:fookey\   .{ $^a <=> $^b }


Same thing - that is using unspace AND using dots.


:longkey\  ($value)
:shortkey\ 
:fookey\   { $^a <=> $^b }


--

I think that concludes my "unspace rant".  That is, my confusion on reading the 
S02 on unspace being linked with dots, I presume to be documentation relics and 
I recall a much earlier discussion on "long-dot" which did link the concepts.  
Proceeding on that assumption, I constructively noted the offending passages 
and suggested changes in the text.

I hope that helps the effort, as well as my own understanding.

--John

S02 questions and comments

[John M. Dlugosz]

I'm reading S02.pod with version information:
  Last Modified: 17 Mar 2008
  Number: 2
  Version: 130

Meta-question 1: what is the succinct way to report this?  Is the "Version 130" 
enough?

Meta-question 2: Does this belong on a different mailing list?  I'm also 
including the documented file maintainer as a direct recipient.

3: I copied the file from  
which I'm told is the up-to-date home.  When I ran pod2html, I got a warning 
that 'encoding' is an unknown directive, and also see that the HTML title is 
simply "TITLE".  Do I need a special version of pod2html, or how do I run it 
properly?

4: "Whitespace is not allowed between a variable name and its subscript. 
However, there is a corresponding dot form of each subscript"
The use of "however" looks like it is meant to imply that the dot form allows 
you to add space.  I think this wording is leftover from the "long dot" 
explanation, but now is out of place.  I suggest dropping the "However," from 
the sentence.

I'm also wondering, in general, why we still have the dot forms of the 
subscripting (and other postfix operators) when the long-dot has been replaced 
by the unspace concept.  

--John