4 ms·

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 i

by gosub100 11mo ago

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.

thyristan 11mo ago
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.
- gosub100 11mo ago
  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.
  - thyristan 11mo ago
    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.
broken-kebab 11mo ago
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
jwillp 11mo ago
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.
creer 11mo ago
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?"
- Bratmon 11mo ago
  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?
  - creer 11mo ago
    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!
    - Bratmon 11mo ago
      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!
      - creer 11mo ago
        > 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.

thyristan 11mo ago

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.

gosub100 11mo ago
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.
- thyristan 11mo ago
  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.

broken-kebab 11mo ago

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

jwillp 11mo ago

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.

creer 11mo ago

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?"

Bratmon 11mo ago
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?
- creer 11mo ago
  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!
  - Bratmon 11mo ago
    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!
    - creer 11mo ago
      > 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.