(1)[0] ok but not 1[0]

[Ilya Zakharevich]

[A complimentary Cc of this posting was sent to
Florian Kaufmann

I am writing a documentation for Perl for myself. I hope it turns out
more concise, at least in my view, as the documentation about Perl I
have currently in my hands. I am writing it to learn Perl, to order my
thoughts, my understanding of Perl. It has a lot of positive side
effects though
- I learn Perl pretty well
- I learn LaTeX a bit (i decided to write the document in latex)

IMO LaTeX is the most unsuitable tool for source code of the docs. As
the minimum, it should be convertable to 1 man doc (for easy
grepping), and/or 1-doc or multi-doc HTML.

If I were on your place, I would look at an extension to POD which can
easily be dumbed down to POD, AND can be translated to LaTeX.
E.g., something like Y<for POD|for LaTeX> comes to mind - in the RARE
cases when something cannot be deduced from normal POD markup...

Hope this helps,
Ilya

 

[Tad J McClellan]

Perldoc says that "List values are denoted by separating individual
values by commas (and enclosing the list in parentheses where
precedence requires it):". To repeat the point, parentheses are not
required to create/specify lists.

The following two are equivalent
print 1,2,3;
print (1,2,3);

This is an application of "parenthesis around a function's argument
list are optional" rule.

Thus the following two should be equivalent too in my view
$x = 3[0];
$x = (3)[0];

Where is the function whose parens are being omitted/included?

There is no "equivalence" between the 1st two and the 2nd two.

 

[Florian Kaufmann]

This is an application of "parenthesis around a function's argument

list are optional" rule.

Are you very sure? I think its an application of the more general rule
"you can always add parentheses around an expression"

 

[Florian Kaufmann]

What are your plans for this documentation? I'm sure people are

interested.

I think I'll be writing for some weeks, maybe even months. I also have
a job during the day . And since I am learning Perl, learning
LaTeX, fiddling at my syntax notation the progress is not fast. But of
course I'll put it under GFDL or something similar and put it on the
net. Provided I am allowed to - the basics of my work are mainly
"Programming Perl" and http://perldoc.perl.org/. I sometimes copied
whole sentences. I fear I would break their copyright when I put my
document under GFDL.

Flo

 

[Michele Dondi]

Anyway, while the OP is confused by the fact e.g. 3[0] doesn't do what
he thinks it should, the current syntax for the wanted semantics seems
intuitive and dwimmy to me. I, for one, would find 3[0] to be
syntactically valid and semantically valid, to imply that 3 is an
autoboxed object (which in Perl 5 generally isn't unless using the
autobox module) and doing the role of an array.

This isn't possible within the syntax and semantics of Perl 5, as you'd
lose the distinction between $ary[0] and @ary[0], which is vital to get
the proper RHS context in assignments.

In fact I said so too, later on. You also quoted that bit: "but then
it would be very inconsistent with $n[0] being the first element of
@n. If sigils were invariant as they are in Perl 6 [...]"

Perhaps this would have some sense if the semantics were that
[0..2](0),

Huh? Perl never uses () for subscripting... did you mean (0..2)[0] ?

Yes, of course. It was a... speecho(?) much like "Man, this is crazy.
I hope I didn't brain my damage."

Still doesn't make a lot of sense...

Indeed: "but there wouldn't be much need to give
3[0] a meaning, either."

IIUC 3[0] is valid Perl 6, and means 3.[0], which may or may not make
sense depending on what object '3' evaluates to... but it's possible I'm
wrong, as I haven't tried using Perl 6 in anger yet.

I think so too and under pugs

pugs> say 3[0];
3

But that of course is not a *proof*.


Michele

 

[Michele Dondi]

IMO LaTeX is the most unsuitable tool for source code of the docs. As
the minimum, it should be convertable to 1 man doc (for easy
grepping), and/or 1-doc or multi-doc HTML.

While I'm a big LaTeX aficionado and listings.sty does an excellent
job at typesetting code, I wholeheartedly second that. Anyway, if one
does not deviate too much from standard classes and packages, TeX4HT
should do a good job for HTML conversion. I don't know if/how it works
with listings, though.


Michele

 

[Michele Dondi]

Are you very sure? I think its an application of the more general rule

Yes, he is.

"you can always add parentheses around an expression"

Nope.


Michele

 

[Charlton Wilbur]

FK> I am writing a documentation for Perl for myself. [...] I am
FK> writing it to learn Perl, to order my thoughts, my
FK> understanding of Perl.

Given your miscomprehensions in this thread (I've seen at least two),
and your acknowledgement that you're still learning Perl, I would like
to strongly recommend that before you make such documentation
available to the general public, you pass it around to several
experienced and knowledgeable Perl programmers for peer review
*before* you make it public.

Good intentions are a grand thing, but there are already far too many
Perl tutorials and references out there, including some that have been
printed and for which people are expected to pay money, which are full
of errors. *Please* don't add to them.

Charlton

 

[Uri Guttman]

FK> I think I'll be writing for some weeks, maybe even months. I also have
FK> a job during the day . And since I am learning Perl, learning
FK> LaTeX, fiddling at my syntax notation the progress is not fast. But of
FK> course I'll put it under GFDL or something similar and put it on the
FK> net. Provided I am allowed to - the basics of my work are mainly
FK> "Programming Perl" and http://perldoc.perl.org/. I sometimes copied
FK> whole sentences. I fear I would break their copyright when I put my
FK> document under GFDL.

i applaud your attempt at this doc but i will wager it won't be nearly
as useful as you expect. there are dozens of perl tutorials on the net
and almost all are total crap and full of mistakes and bad writing. in
many cases the authors also were self taught and thought they can create
a better doc. turns out that writing technical docs (especially
tutorials) needs much more programming skill and tons of experience
which most of those authors don't have (or ever will have). some even
proclaim how smart they are and still fail badly. i have read many and
have posted shredding reviews on usenet in the past so go google for
some of them. consider that larry wall wrote 'programming perl' and is
considered a very good writer and of course knows perl very well. yet
some have problems with that book (note: it is NOT a tutorial or
beginner book). i will repeat it, tech writing is VERY hard and much
harder than anyone who hasn't done it realizes. it is by far harder than
programming as you have to write much more text than code, understand
the material far better than you need for coding and english (or any
other natural language) is full of ambiguity and nuance that is not
found in programming languages.

report back in 6 months for a proper review/shredding and you will find
all your time and effort will likely have been wasted. just watching how
you think in this thread tells me you are not qualified enough to write
another perl tutorial that will make any mark at all. nothing personal
but this comes from my experience reading amateur tech writing about
perl. i have also been a technical editor of 4 perl books as well as a
perl trainer and article author so i also have direct experience in this
area.

good luck, for you will need it. you don't realize how hard a task lies
ahead of you.

uri

 

[Florian Kaufmann]

as useful as you expect. there are dozens of perl tutorials on the net

and almost all are total crap and full of mistakes and bad writing. in
many cases the authors also were self taught and thought they can create
a better doc. turns out that writing technical docs (especially
tutorials) needs much more programming skill and tons of experience
which most of those authors don't have (or ever will have). some even

I think you and Charlton Wilbur are perfectly right. By no means will
the document I am writing be better than "Programming Perl" or
http://perldoc.perl.org/ or other established documentation from an
objective point of view. Of course it will have a lot of mistakes and
errors in it, since I will never be a Perl professional but at most an
experience Perl user.

However it will be better from my subjective point of view. Its closer
to the way I am thinking. Its the way I am learning stuff - by
writting things down. Order stuff on paper until I can fully
understand it and have a concise view on it.

I don't know exactly why - "The C++ Programming Language" is a book
that is much more clear to me than "Programming Perl" - and I don't
think its just because I already know C++ better. Its because of the
way things are explained, specified.

Maybe you are right and I shouldn't make it public, because it will
definitely have much more mistakes in it than any official
documentation. So there is a concern that it would only confuse
people. Then again maybe there are people who can profit from it.
Maybe I have to make it very very clear in the abstract and/or
introduction that it's a book written by a non-professional and thus
will contain tons of mistakes.

Flo

 

[Uri Guttman]

FK> I think you and Charlton Wilbur are perfectly right. By no means will
FK> the document I am writing be better than "Programming Perl" or
FK> http://perldoc.perl.org/ or other established documentation from an
FK> objective point of view. Of course it will have a lot of mistakes and
FK> errors in it, since I will never be a Perl professional but at most an
FK> experience Perl user.

FK> Maybe you are right and I shouldn't make it public, because it will
FK> definitely have much more mistakes in it than any official
FK> documentation. So there is a concern that it would only confuse
FK> people. Then again maybe there are people who can profit from it.
FK> Maybe I have to make it very very clear in the abstract and/or
FK> introduction that it's a book written by a non-professional and thus
FK> will contain tons of mistakes.

then why even do it if it will have so many mistakes? it won't even help
you in your goal to learn perl. and publishing it with a disclaimer that
it has mistakes is even worse. just consider it a private document for
yourself and keep it that way. if you want to get feedback you could
publish the url but make sure it says this is not considered a
professional work. just check out the many tutorials i said exist on the
web. the mistakes and bad writing (and hubris of all thise authors) is
amazing.

uri

 

[jl_post]

The following two are equivalent
print 1,2,3;
print (1,2,3);

But the following two lines are not equivalent:

my @a = (1,2,3);
my @a = 1,2,3;

Parentheses sometimes make a big difference, because they can change
the order of when operators get evaluated.

 

[Florian Kaufmann]

then why even do it if it will have so many mistakes? it won't even help

you in your goal to learn perl. and publishing it with a disclaimer that

Because even now in the early stages I profit from my document. As
said, I learn things by writing down what I read, summarize in my own
words.

I can look up things faster because its much denser, my documents
internal logic and organization matches more the way I am thinking
then the Perl documentations I have. In those, a particular idea/rule
is seldom in one single place. Instead, its spread over a couple of
places. There are too little clear statements which rules apply to
exactly which things - often these docs try to specify rules by using
isolated examples. So its hard for me to get to know the general/basic
rules.

Say I want to learn differentation. Then I prefer to learn a pretty
basic rule like
f'(x)=lim( h -> 0 ; (f(x+h)-f(x)) / h )
http://en.wikipedia.org/wiki/Derivative#Definition_via_difference_quotients

Maybe along with a good visualization in form of a diagram. Maybe also
some very often used basic rules, knowing that they derive from the
rule above and don't really introduce new ideas/rules
(f*g)' = f*g' + f'*g
(f+g)' = f' + g'
.... http://en.wikipedia.org/wiki/Derivative#Rules_for_finding_the_derivative

But surely I don't like if the book doesn't tell me about the above
formulas and just tells me that I have to know the following rules to
understand differentiation and be able to differentiate.
(x**a)' = a*x**(a-1)
sqrt(x)' = 1 / ( 2 * sqrt(x) )
.... etc etc ... a very long list. http://en.wikipedia.org/wiki/Table_of_derivatives

These rules are just isolated examples of the basic rules. If I know
the basic rules well, I can deduce these rules by myself.

it has mistakes is even worse. just consider it a private document for
yourself and keep it that way. if you want to get feedback you could
publish the url but make sure it says this is not considered a
professional work.

Right!

 

[Ben Morrow]

But the following two lines are not equivalent:

my @a = (1,2,3);
my @a = 1,2,3;

Parentheses sometimes make a big difference, because they can change
the order of when operators get evaluated.

<sigh>

In both
print (1, 2, 3);
and
(1,2,3)[1]
(and
if (1==2) { }
for that matter) the parens have a quite different function from in
@a = (1, 2, 3);
.. In the last case, they are indeed just for precedence; in the others,
they are part of the syntax, and omitting them does more than simply
change the evaluation order.

Ben

 

[Peter J. Holzer]

FK> Maybe you are right and I shouldn't make it public, because it will
FK> definitely have much more mistakes in it than any official
FK> documentation. So there is a concern that it would only confuse
FK> people. Then again maybe there are people who can profit from it.
FK> Maybe I have to make it very very clear in the abstract and/or
FK> introduction that it's a book written by a non-professional and thus
FK> will contain tons of mistakes.

then why even do it if it will have so many mistakes?

I'm not sure what you mean by "do it". Writing the tutorial or
publishing it? For the first: Trying to put concepts into your own words
is a good way to clarify them. As you try to write it down you will find
that you are unsure about some aspects and do some more research.
As for the second: Trying to explain something to somebody else will
further clarify the concept (as you don't only need to think of some
words, but words that somebody else will understand) and will also shake
out many misconceptions, because you will have to answer all those pesky
"why ..." and "yes, but ..." questions.

I often find that I haven't understood something until I've successfully
explained it to somebody else. However, explaining face to face is much
better there than writing it down because you can see when the other
guy's eyes begin to glaze over - otherwise you never know if somebody
bothered to read your stuff at all and if they did whether they
understood it.

Maybe usenet postings are a reasonable compromise: Write short articles
about perl. If you got it right, it the article will be added to the
collective wisdom of the newsgroup. If you are unclear or wrong, people
will point it out.

hp