Hacker News Reader

Perl was not and still is not suitable for people who refuse to read the manual or tutorial.

Perl had and still has truly AMAZING documentation (and far better in perl 5 than Perl 6 - where the documentation's search function is regularly broken for example). And out of this world bring-up tutorials. But if the bar is at "I want to be up to speed after reading a short booklet" - well, that's not gonna work. For me I have programmed in perl for decades and I still get the occasional deep plunge in a feature area that I never used before... And the various docs and books still come through.

On top of that, Perl 5 had an amazing community ready to help - but understandably annoyed with constantly re-quoting the AMAZING documentation. It could have gone either way, it just went the way it did: experts present and ready to answer. But there too - if you expect the community to constantly answer the most basic questions, well, Perl was not for you.

As a tradeoff perhaps, that expert community also spent a lot of effort on the AMAZING module library.

Perl 5's thorough documentation, plus splendid course book, plus all the books, plus CPAN, PLUS the expert help producing fantastic rabbit holes to learn more about your PROFESSIONAL MEDIUM. THAT was the reason for choosing perl.

If anything, newcomers don't go to the documentation because they are not aware that documentation can be THAT good. That was, still is, a marketing error.

That's an interesting observation - and my recollection is that the perl heyday was just about before the Googlefication of the world; certainly before stacked overflowing.

Grab a snippet of Java or Python and you can google it pretty easily, grab some line noise from perl and you would first need something to translate it into idiomatic text - search engines would search for "OUTPUT_AUTOFLUSH" but would often discard things like "$|++"

I remember learning my use of perl from a red book - probably "Perl 5 by Example" - everything was in books back then, and you read them. Now you learn programming via searches and LLMs, so the languages that win going forward are going to be the ones optimized for that.

> search engines would search for "OUTPUT_AUTOFLUSH" but would often discard things like "$|++"

Out of curiosity, I tried

    perl "$|"

in DDG and Google. DDG returned nothing, but Google led with "perl $|=1; What is this?", and "Perl, what does $|++ do?", both from Stack Overflow. Search like it's 2014, eh? I don't have a time machine, but I'm pretty sure that quoting would've worked ten years ago, too.

> the only answer I got was 'man perldoc'

When I asked a question on the PERL Usenet group in the 90s, I used the word "newbie" to describe my skill level. I got an automated email explaining why I shouldn't use that word.

> when I asked on IRC the only answer I got was 'man perldoc'

Your overall point notwithstanding, this was just bad advice. What you want is `man perlvar` (or equivalently `perldoc perlvar`) which documents this and other predefined variables:

       HANDLE->autoflush( EXPR )
       $OUTPUT_AUTOFLUSH
       $|      If set to nonzero, forces a flush right away and after every
               write or print on the currently selected output channel.
               Default is 0 (regardless of whether the channel is really
               buffered by the system or not; $| tells you only whether you've
               asked Perl explicitly to flush after each write).  STDOUT will
               typically be line buffered if output is to the terminal and
               block buffered otherwise.  Setting this variable is useful
               primarily when you are outputting to a pipe or socket, such as
               when you are running a Perl program under rsh and want to see
               the output as it's happening.  This has no effect on input
               buffering.  See "getc" in perlfunc for that.  See "select" in
               perlfunc on how to select the output channel.  See also
               IO::Handle.

               Mnemonic: when you want your pipes to be piping hot

Also, `man perl` gives a great overview of the extensive number of Perl-related manpages. I think any person that starts from `man perl` will be able to answer a lot of their questions, but part of the problem was that around the millennium, people stopped reading man-pages, and started looking for information on the web. perl was one of those old-school tools that were documented extensively in man-pages, but past 1995 ~nobody bothered to read man-pages anymore.

That variable in particular gets covered in the Llama book as well. Anyone serious about learning perl in the 90's had at least one of the Camel or Llama books.

Golly

There, the problem illustrated

"You are not serrious" is a downright hostile attitude

"man perldoc" as an answer can be translated as "f*^&%k off you stupid...."

  man perldoc

is too curt, and therefore may feel hostile especially for native English-speakers who are used for polite communication to be more wordy. But cultural things aside it's actually a good working solution.

> f*^&%k off

Hey you're writing perl already! ;)

Sorry for being salty earlier, but learning a language still takes at least a day or two of solid reading of the official manuals. https://perldoc.perl.org if you want a web version.

This is exactly the point.

There was a fifteen year period where the best way of finding out what something meant in a programming language was to Google it. Pre-AI, post the predominance of newsgroups and offline documentation.

Try googling "$|++". It just doesn't work. Never has.

Now Google "file.flush". First hit is the answer you need on SO.

You did not need to google anything. The complete documentation was right there, next to the interpreter, on your machine. Ready for scanning and reading from top to bottom; and broken in sections that were actually relevant; and ready to search in bulk if you prefered with whichever local search tool you cared for.

No need for google. (And google was run by python fans; probably saw no need to support searching for '$|++'.)

And I notice "post the predominance of offline doc". Well that's one problem right there: As of 2025, there is still nothing that beats perl 5 docs as ~260 man pages. Probably LLM-based AI is getting there, at least for people who have difficulty with text. But for the rest of us, it's VERY useful to know that there is solid (offline) doc.

Right, yes, exactly.

Also to be fair, a modern Perl app doesn't even need to use `$|++` since the framework, even if it's raw Plack, will manage output flushing for you since you're no longer banging on raw stdout. I'd say Perl suffers from an even worse problem of legacy tutorials than PHP, but the size of PHP's userbase and thus sheer number of bad tutorials makes it worse there.

chromatic's https://modernperlbooks.com site is nearly unmaintained now, but still contains some good links to tutorials and whatnot on the obvious subject. Including a pretty recent retrospective: https://outspeaking.com/words-of-technology/why-perl-didnt-w...

I disagree, at least when it comes to the web (of those days). What's the point of rewriting what's already well- and accurately-written in the docs? What better job are the people on that message board going to do with regards to such a small, specific syntax feature? The point of those "communities" wasn't to answer questions like "what is this variable?" but rather to have actual discussions on the language, such as how to structure applications, design patterns, projects, etc. Imagine trying to build an online community for this purpose, only to spend your days answering the most basic questions possible that were already explained many times before.

Eventually, a website more tailored to such questions was created - Stack Overflow - and there things were very different than in subject-specific communities: there was no "community", there were no discussions, just a big mess of questions. It had a purpose and it served it well. Now it's dying too because of LLMs, but I digress.

Now, in a different scenario, say a colleague asking you that question at work, a direct answer is warranted, but without letting the colleague know that this information and a lot more is a just a few keypresses away would be a wasted opportunity, and not particularly a good way to help that colleague progress.

You can only spoon feed people so much. At a certain point relying on other people to just give you the answer every time you don't know something is lazy. It's like you have no respect for their time.

Golly. There are still some who think it is ok to be rude to newbies.

$|++ is arcane to anyone not steeped in Perl

The newbies could be warmly welcomed and shown respect.

But no, RTFM.

That is rude to somebody drowning in newness. If you do not want to answer their question, then don't. But some people seem to get a kick out of being rude to weaker people

All the times it happened to me, back in the '90s this made life really much harder than it needed to be.

For all the ones who bum me out

For all the ones who fill my head with doubt

For all the squares who get me pissed

You've made my shitlist

> made life really much harder than it needed to be

If only you had read the manual...

Seriously though, of course I wasn't advocating for rudeness, and trust me, I remember how rude some people were back then in tech-related boards, this was not a unique Perl thing. I'm advocating for pointing people to the sources of information they're looking for.

> You've made my shitlist

Well then I hope it's posted somewhere I can refer to at will so that I don't have to ask you on a message board like a noob.

>Golly. There are still some who think it is ok to be rude to newbies.

the entire tech industry is driven by humans and we're really bad at everything. once the AIs take over things should be much better, except for the occasional hallucination.

A professional medium might have been gate-kept being paying coursework. Perl was not: the super-complete documentation was right there, in the distribution; the remarkably intelligently written course book was right there on everyone's shelves and in your local public library; the in-depth books same thing; And quickly enough even free on the net; the expert-built module library was all there to use and study; the experts were giving their time freely, writing deep dive articles at the simple prompt of worthy questions in addition to columns on topics which I guess were not getting enough questions.

For a professional medium, the only lack that I can tell is from a marketing point of view: installing the distribution for example, probably did not highlight enough how extensive the documentation was.

Let me respectfully disagree.

  man perldoc

would tell one needs to use -v key to learn about a var. And consequently

  perldoc -v '$|'

would tell everything one needs to know about $|

So it was actually reasonable advice.

RTFM might be reasonable advice, but its not "welcoming" advice.

I agree in general (and already commented on this). But some people believe it's like giving fish instead of fishing rod. And I think it was prevalent idea in tech circles during 90s-00s that people who don't read that fm waste other participants time, and needlessly multiply forum topics or extend conversation history. Which was seen as uncivil behavior in those times.

I remember being very enthusiastic about helping people on, say, Stack Overflow. It didn’t take much extra effort to be nice and made me happy.

But I also burned out relatively quickly. I’d happily answer new questions nicely, but the third or fourth time I saw the same question I spent much less effort to give a welcoming answer than I had the first time I saw it.

Of course, getting the same question repeatedly may suggest something should be redesigned.

I don’t know any good way to keep helpful volunteers helpful for a long time. The best idea I have is constantly recruiting new experts to continually replace the ones that burn out and chase off newbies.

> getting the same question repeatedly may suggest something should be redesigned

Yes! There was a lesson in that and we all missed it. That was probably one of the failings of perl. It ran into a generation of people who never knew about "man pages", or couldn't read (jk - but only somewhat: for some people reading is very hard because various flavors of ADHD, dyslexia, executive disfunction, whatever) and the man page is then useless, or they go to google first and '$|++' failed (because google was raised on python).

Better marketing of the documentation would have helped.

I would say "we'll do better next time" but then perl 6... I'm not happy with perl 6 documentation. There is a lot of it - no problem there. But it insists on living online which necessitates a hosted search function. Which is always broken. And there is still no "local doc" solution.

man I hate that always online stuff. why isn't there the comprehensive man pages thing for perl 6? rhetorical question tho, I don't have much interest in perl 6.

If they specified ‘perldoc -v $|’ instead of just ‘man perldoc’ I’d have been thankful for that as the entire response. It’s literally a pointer to where the answer is and to how to use the canonical tool to find it.

Yep, especially when so many instances of TFM were awful. Perl's docs were fantastic, or so at least I thought at the time, but they were the first large open source project docs I devoured. I can imagine someone coming from another language not even considering just looking at the man page because they were used to awful documentation.

You are right, Perl's docs are so unusually good that newcomers can't believe they don't need the internet to find clear answers, and go searching/asking anyway, sometimes in wrong places.

FreeBSD has the same problem: plenty of its new exploring users dismiss the most well-intentioned advice to read its excellent Handbook as a sort of joke.

I’ve seen that one firsthand! “I want to do a thing.” “That’s in chapter 5 of the handbook.” “Oh cool. Is there a substack or something that explains it?”

Fair enough, but I think the first part of the advice would be a lot more helpful if it included the second part too. It's the intermediate step that turns people off: why do I need to learn about `perldoc` when I asked about `$|`? (And that's assuming the question asker is familiar with man-pages to begin with, otherwise, you need to read `man man` first!) It feels like you're sending them off on a wild goose chase, even if that's not your intent.

In the millennial web forum world, a n00b would ask "what does $| do?" and the answer would be "it disables output buffering", which is what the n00b wanted to know in the first place. It's the Stack Overflow model of giving men fish, instead of teaching them how to fish.

And in today's LLM-powered world that's only more true. If you ask ChatGPT "In a Perl script, what does $|++ do?" it will immediately give you a correct and concise answer, not make you read `man perldoc` first.

Yes, it would look and work better if presented with an explanation like "you can find any var description by using...". But as I commented already in another thread there was a widespread belief in 90s-00s that users who ask about already documented pieces are being uncivil, not vice versa. So it's not about Perl community per se. The same was norm in many Linux fora, for example.

so they should have written that. Next you're going to tell me man man is reasonable advice

How would I know that $| is a var? It could be an operator, or a function, or a directive.

There's no space for doubts at all. If it starts with $ then it's a scalar variable name. It's a very basic rule in Perl. Like any Perl tutorial would mention it within a few paragraphs from the start.

So then wouldn't that make $|++ the variable name?

Smokey, this is not 'Nam! This is <Perl>, there are rules!

'$' guarantees a scalar. Then it either alphanumeric id, or a single non-alphanumeric symbol. And the latter means you deal with a 'special' var which with 100% certainty has a documentation entry.

This comment kind of epitomizes the way the Perl community works, to be honest.

The problem is with man pages themselves. You shouldn't have to read 100% of something to find 0.1% of something. In fact, this concept is covered extensively in CS theory about sorting. Reading a manpage is less efficient than asking someone who already knows.

Only locally, only for you, and only short term. You are wasting the time of the person you are asking, and you are learning absolutely nothing about the context of the answer. When the next question arises, you won't even know where to look, you will only continue wasting other peoples' time.

That's a false assumption that the man page even has the info you need. There are channels to write bugs against code, but almost nothing to file bugs against man pages. That's not even a concept to most people, that it's a bug when you apply a use case (say, to apply eui-64 to SLAAC in IPv6 in order to generate a consistent address) and cannot find the information using the man page. If you filed a bug that the man pages failed you nobody would fix it because it's not sexy, glamorous work. Its easier to tell someone to RTFM.

In this case, you would have to already know about the existence of eui-64 to know that is what you want. I've seen this many times, you have to know what the thing is already, or know what the answer is to your problem, in order to find it in the man page.

Total waste of my time. I don't care if it's free or was created by volunteers, that isn't absolution of criticism when it represents something and fails to deliver it.

Nonetheless, you are expecting other people to know the manpage and read it for you. That is a game you may be able to play with paid support, but usually not even there: They will be more wordy and polite, but in essence tell you to RTFM as well.

Bugs in Perl modules that are documentation related are normal bugreports and patches in the normal patch flow because documentation is embedded as POD within the source code.

Your example is very specific and weird (and maybe not even Perl-related). From which you deduce that it is OK to waste the time of volunteers because once one manpage failed you and you decided to never read any manpages again. You only seem to care about your own time, not anyone else's. That is not how anything works on this planet, either you deal with volunteers, where you have to make them care about your query by being considerate, friendly and respect their time as well as you would like yours respected. Or you are dealing with paid support, in which case you have to make them care by paying them for their time by the hour.

There are some manpages which are too long, and cumbersome but it's not a widespread problem I believe. In particular man perldoc is laconic and on point.

I don't think that RTFM is the best form to answer, but those who auto-reject "man" as an answer are definitely missing something important

The trick is to already know how to use regexes to make searching the manpages easier! But you really have to nail down the rules for escaping when you want to search for perl's gnarliest sigil magic.

The man pages were broken into competent sections over multiple man pages. About 260 of them on this machine (not really: there is a change-tracking man page per release recently.) The 1st man page is a very compact index to them.

After that, each section is long but very searchable.

But I can see how many people never even noticed."Man page? what's that? what for?"

But if every user is expected to read the entire manual cover-to-over before asking a question about a four-character operator, what's the point of dividing it into sections?

I know you are not serious but let's go with it anyway. Since we have to be welcoming to newbies :-) Not expected to read cover to cover. Cover to cover would be the tutorial / course work. And even then in a layered language like perl 5, the later chapters only when needed. Layered: the language and coursework is written to add one layer of the language after the previous ones. So you can start writing things that do function after just the first layer.

Expected to know it's there, navigate through it to find the operators or system variables and that you can search through the thing. There are ~260 perl man pages on this computer - not expected to read them. For damn sure expected to use them.

Do read one more section from top to bottom now and then - if the thing is the one fundamental tool in your job!

But that's what the ancestor was trying to do. Then he ran into a symbol he hadn't gotten to yet, asked about it, and got flamed for not reading the full manual!

> flamed for not reading the full manual!

It was not for not reading the full manual. It was for not using the manual. Somewhere between "not at all", "not competently", "not persistently". And he was pointed to a perl-specific tool which is made for searching the doc. Not the same thing?

And he/they had missed an entire category of symbols. That none of the responses pointed at - their bad on that. That is, all these symbols are described in the same manual section. And used in illustrative examples all over the place. They are not exactly a deep hidden thing.

Also, regarding "flamed". No. Not really. They were handed the same response that countless other questions were getting. Anyone frequenting these forums saw them countless times. It is quite possible that it was their first time on that forum / chat and then that the answer was shocking and traumatic. Yes to that. So that in hindsight, the standard response should have included a pointer to a "how to use the doc" doc. That would have helped. Since it was a generation was seemed unaware of the man pages.

The problem is the implicit assumption that you can throw an entire book at someone and expect them to be able to figure out where to look for each piece of information in it without them knowing beforehand what things even are. If someone hasn't ever seen a variable like `$|` before, it's not necessarily going to be obvious to them what it is, and without knowing how to classify it, they aren't going to know how to tell what chapter it's described in. You're defining the bar for someone to be able to ask a question as high enough that they spent enough time reading through everything to be able to identify it. That's going to be fine for some people, but not everyone learns the same way, and when some people learn better a different way than you, it's not because they're stupid or lazy, but because there's just a lot of variety in what works well or doesn't for people.

Of course, you aren't under any obligation to spend time helping people who you don't want to, but if a community as a whole reacts this way when someone asks a question, they're making the bet that the there are enough people who are similar enough to them to sustain things in the future. Given that this both happened years ago to the parent commenter and now again when they tell the story again, it's not really that hard to believe that this might have been common enough that a lot of people experienced it. The entire point of this thread is discussing why Perl has faltered, and your explanation in the last paragraph comes across as basically saying "kids these days..." in slightly different words. I'd argue that even if the kids loved man pages, having a condescending attitude towards them would probably still come through in other ways, and that would have had pretty much the same effect.

I am agreeing with you that there was a mismatch between the expectations on using the elaborate documentation in its various forms and the tutorials and the stellar course - and a large set of potential users. Nobody expected "the entire book" but perl 5's rise came at the time when many stopped reading man pages, and many projects stopped providing them.

I agree with you that this probably was a contributor in some people giving up perl quickly. For python or php.

Like I mentioned elsewhere, for people for whom using a book would be a barrier - perl would have been a poor choice anyway. You can't program in perl without using the man pages and books. It's a large language, with lots of features purposely made less visible to the newcomer.

In addition, many people were exposed to perl from web scripts. And it was sooo tempting to just paste in a perl script, and then want to modify it, without spending any time on learning the language. Perl makes that frustrating (and compensates with a stellar course book). I still defend perl by arguing that (in perl) there is no point in discussing what $| might mean even before having covered the basics, for example sigils. The course book is layered, and for good reason: to let you write a program in useful order, fundamentals first. The special variables come up fairly early but then again the course book had an extensive index which includes these special variables first in a symbol section, and then again in the alphabetical order for their wordy version $| or $OUTPUT_AUTOFLUSH. I'm not trying to beat you over the head with the manual. Just pointing out that the course book was throrough and intelligently written.

I'll point out that throwing a question at a forum without poking around it a little to figure out the local mores - well, still now, that will get you barked at. Lesson: Forums would do well to provide a more useful paste-in than "RTFM" - ready to go for their users. Instead of "RTFM". At least if they want to foster adoption. Does any forum do that particiularly well, that you have noticed? Most discords for example, do NOT do that well: it's possible to create stickies and they are really not visible. So people create onboarding documents which then get too long and get skipped. A problem not solved there.

Sorry for the bad experience you had, I believe it's always better to be kind to strangers on those global nets. But TBH perldoc would really work very well for you.

This is so spot on. You can't google line noise, and that mattered before LLMs. And everything else you said.