search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.91k stars 542 forks source link

pod should be indentable #3104

Closed p5pRT closed 20 years ago

p5pRT commented 23 years ago

Migrated from rt.perl.org#5124 (status was 'resolved')

Searchable as RT5124$

p5pRT commented 23 years ago

From vicki.brown@barclaysglobal.com

I assume (hope) this is an old and oft-submitted request.

POD should be indentable. Perl is white-space tolerant; why should POD be different.

The Camel sayeth​:

  ...files...may contain dollops of pod sprinkled about wherever   the author feels like it. Perl simply skips pover the pod text   when parsing the file for execution.

I say​: if I can't indent it\, it ain't :wherever I feel like it".

The Camel sayeth​:

  The Perl lexer knows to begin skipping when\, at a spot   where it would ordinarily find a statement\, it instead finds a line   beginning with an equal sign and an identifier".

I say "That's misleading and not true..."

Let's get nit-picky about "beginning with".

Comments "begin with" a #. But\, that statement does not imply that comments MUST begin in column 1!

If I can indent these statements

  # x is cool

  $x = 25;

Why can't I indent

  =head   ...   =cut

If nothing preceeds the statement (pod) except (invisible to Perl) white space... why can't I indent pod?

Sayeth the Camel​: This allows you to intermix your source code and documentation freely.

Nay\, not freely. My documentation commands must be left-justified in column 1. At no other time is Perl so heavy-handed.

I thought I had done with Column 1 when I left FORTRAN behind.

Pod isn't... well...\, very Perlish.

Perl Info ``` Site configuration information for perl 5.00404: Configured by adiop at Wed Nov 4 22:06:21 PST 1998. Summary of my perl5 (5.0 patchlevel 4 subversion 4) configuration: Platform: osname=solaris, osvers=2.4, archname=sun4-solaris uname='sunos moose 5.4 generic_ sun4m ' hint=recommended, useposix=true, d_sigaction=define bincompat3=y useperlio=undef d_sfio=undef Compiler: cc='cc', optimize='-O', gccversion=2.6.0 cppflags='-I/usr/local/include -I/opt/gnu/include' ccflags ='-I/usr/local/include -I/opt/gnu/include' stdchar='unsigned char', d_stdstdio=define, usevfork=false voidflags=15, castflags=0, d_casti32=define, d_castneg=define intsize=4, alignbytes=8, usemymalloc=y, prototype=define Linker and Libraries: ld='cc', ldflags =' -L/usr/local/lib -L/opt/gnu/lib' libpth=/usr/local/lib /opt/gnu/lib /lib /usr/lib /usr/ccs/lib libs=-lsocket -lnsl -ldb -ldl -lm -lc -lcrypt libc=/lib/libc.so, so=so useshrplib=false, libperl=libperl.a Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' ' cccdlflags='-fpic', lddlflags='-G -L/usr/local/lib -L/opt/gnu/lib' Locally applied patches: @INC for perl 5.00404: /usr/local/lib/perl5/sun4-solaris/5.00404 /usr/local/lib/perl5 /usr/local/lib/perl5/site_perl/sun4-solaris /usr/local/lib/perl5/site_perl /usr/local/lib/perl5/sun4-solaris . Environment for perl 5.00404: HOME=/ext203/home/browvic LANG (unset) LC_COLLATE=en_US LC_CTYPE=en_US LC_MESSAGES=C LC_MONETARY=en_US LC_NUMERIC=en_US LC_TIME=en_US LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/ext203/home/browvic/bin:/ext203/home/browvic/nib:/usr/local/bin:/usr/ccs/bin:/usr/ucb:/usr/bin:/bin:/etc:/sbin:/usr/sbin:/usr/games:.:/net/asg-sf03/prod/sybase/bin:/usr/lib/lp/postscript:~/Work/bagelbin PERL_BADLANG (unset) SHELL=/bin/tcsh ```
p5pRT commented 23 years ago

From [Unknown Contact. See original ticket]

On Jan 8\, vicki.brown@​barclaysglobal.com said​:

POD should be indentable. Perl is white-space tolerant; why should POD be different.

How\, then\, would you differentiate between paragraphs and as-is text?

=head1 Foo

This is a paragraph

  this is as is text

=cut

Would Perl have to keep track of the indentation of the POD directives?

  =head1 Foo

  This is a paragraph

  this is as is text

  =cut

p5pRT commented 23 years ago

From @simoncozens

On Mon\, Jan 08\, 2001 at 01​:28​:39PM -0800\, vicki.brown@​barclaysglobal.com wrote​:

The Perl lexer knows to begin skipping when\, at a spot where it would ordinarily find a statement\, it instead finds a line beginning with an equal sign and an identifier".

I say "That's misleading and not true..."

Let's get nit-picky about "beginning with".

Comments "begin with" a #. But\, that statement does not imply that comments MUST begin in column 1!

Comments aren't lines.

Comments begin with a "#". That's correct. The beginning of a comment has to be a # sign\, which is just as well\, because I don't want things *before* the # sign being treated as a comment. For POD\, lines must begin with a "=". There must be nothing on a line before an "=". I think that's perfectly clear.

Now\, what isn't clear to me at all is what happens in this case​:

$a

=begin ;

print $a;

Perl prints "begin". But it shouldn't.

p5pRT commented 23 years ago

From [Unknown Contact. See original ticket]

On Jan 8\, Simon Cozens said​:

Now\, what isn't clear to me at all is what happens in this case​:

$a

=begin ;

print $a;

Perl prints "begin". But it shouldn't.

Not so. POD directives start where Perl is expecting a new statement.

"The Perl lexer knows to begin skipping when\, at a spot where it would ordinarily find a statement\, it instead encounters a line beginning with an equal sign and an identifier..."

  -- Camel 3

p5pRT commented 23 years ago

From [Unknown Contact. See original ticket]

  -----Original Message-----   From​: Simon Cozens [mailto​:simon@​cozens.net]   > Comments aren't lines.

Statements aren't "lines" either.

... The Perl lexer knows to begin skipping when at a spot where it would normally find a statement...

Column 2 is such a "spot". So is column 29. Iff preceded by whitespace. Iff we're talking statement. Or comments. Or anything but... pod.

  > There must be nothing on a line before an "=". I think that's perfectly clear.

Oh\, it's perfectly clear. I never said it wasn't clear.

I said I think it's wrong :-)

 
 

p5pRT commented 23 years ago

From [Unknown Contact. See original ticket]

  From​: Jeff Pinyan [mailto​:jeffp@​crusoe.net]   Sent​: Monday\, January 08\, 2001 13​:45

  On Jan 8\, vicki.brown@​barclaysglobal.com said​:

  >POD should be indentable. Perl is white-space tolerant; why should POD be   >different.

  How\, then\, would you differentiate between paragraphs and as-is text?

  =head1 Foo

  This is a paragraph

  this is as is text

  =cut

  The way it's done now. The beginning of a here document can be indented. _Commands_ can be indented."As is text" can't be indented.

  Let's bear in mind the difference between data and program. Program should be white-space tolerant.

  Would Perl have to keep track of the indentation of the POD directives?

  No. I'm asking for whitespace to be ignored in Perl "command lines". Thus the "level of indentation" is not at issue - because the amount of white space should be ignored along with the fact of the whitespace.. This is Perl we're discussing\, not Python :-)

  - Vicki