Bug 255340

Comment 1 Fernando Apesteguía 2021-05-11 06:10:55 UTC

Hi Harald,

I am not sure about this. The commands do not provide similar functionality:

$ echo -e "reverse this\nand this" | sort -r
reverse this
and this

$ echo -e "reverse this\nand this" | rev
siht esrever
siht dna

Hi Fernando,

you are right that the functionality differs significantly.
But if I was sure which does what, I wouldn't need to consult man(1).

mount(8) has a reference to setfacl(1) e.g. and comm(1) has cmp(1) and diff(1) in the SEE ALSO section.
These are functionality wise very different too.
SEE ALSO is meant to guide users into a possibly better matching direction, which tail or sort (-r) might be if one confused the function of rev(1). At least that's how I've been unsing the SEE ALSO section of FreeBSD's man pages, and especially tail(1) was a nice hint for somebody looking for a  "| reverse-feature".

Thanks,
-harry

Comment 3 Fernando Apesteguía 2021-05-11 10:19:16 UTC

(In reply to Harald Schmalzbauer from comment #2)

Hi,

I see what you mean.

As I see it, mount(8) references *acl(1) because it has an acl option and then, it is extremely related. comm(1), cmp(1) and diff(1) all show differences in files.
tail(1) and sort(1) are not cross-referenced because they do completely unrelated things: one shows files (in different ways) the other one sorts streams (using different criteria).

In SEE ALSO we can reference other utils, but not other utils with specific flags. I think it would be confusing for a user to look at rev(1) and find references to a sorting utility and a file showing one.

So the problem is actually how to make the sort flag that you are looking for more accessible.

Would apropos Fl=reverse work for you?

(In reply to Fernando Apesteguía from comment #3)
Thanks for your elaboration!

Now I remember the most confusing path: 'apropos reverse':
rev(1) - reverse lines of a file

I'm not native english speaker... to my understanding, this suggestes that the lines itself will be reversed, not the characters of a line.

Of course, the man page makes that clear in the examples section, but to my understanding this 'apropos reverse' result currently is misleading.

If 'apropos reverse' leads to tail(1) I'm completely fine.

Thanks,
-harry

Comment 5 Fernando Apesteguía 2021-05-11 19:01:54 UTC

Ok, then.

I will close this one since aprooos can lead to sort if used with the proper flags.

Thanks!

(In reply to Fernando Apesteguía from comment #5)

Ok, so the mentioned confusing description of 'apropos rev' seems to be intended.
Users with limited knowledge about apropos(1) flags won't find the tools, doing what was described for rev(1).
I learned now that this is the intended behaviour.
FreeBSD is making big progress in gaining almost the same professional support level as common Linux distros teach us - keep information secret and as soon as it's wide spread, change it.

What I absolutely cannot cope with your answer is the lack of the line telling us which flags lead to sort.

Comment 7 Fernando Apesteguía 2021-05-12 05:32:25 UTC

(In reply to Harald Schmalzbauer from comment #6)

Hi Harald

s/flags/arguments. The one I already posted:

apropos Fl=reverse

that one looks for flags with 'reverse' in their names.

With that, you can reach sort(1).

But let me tell you again why in general, when you look for 'reverse' you should not find tail(1) or sort(1): because they do not reverse anything. Think of sort(1). It sorts. That's it. It does not really reverse anything, it just applies a certain criteria to compare two individual elements and does that for all the elements of the input.

Another example: bash provides Ctrl-R and Ctrl-S to do a reverse or forward search history (see reverse-search-history (C-r) in bash man page) but honestly I don't see anyone happy getting 'bash' when using apropos reverse.

man and apropos are not a search engines and hence they are limited in the kind of searches they can provide.

Cheers.

Thank you for the clarification about the apropos(1) parameters.

I still can't accept the "works as intended" closing.
More than 20 years ago, I prefered FreeBSD over Linux as beginner for learning PC-OS from the Unix-alikes.
One of the reasons was the well maintained SEE ALSO section of the man pages, which FreeBSD offered while Linux manpages had lots of additional shortcomings and rearely a SEE ALSO section.

Your statement
"when you look for 'reverse' you should not find tail(1) or sort(1): because they do not reverse anything."
is not true.
tail(1) is able to reverse the lines of a file.
At least the version we have in FreeBSD base, which supports the -r argument.  This "reverses the lines of a file" - which is our current (misleading and ambigous) short description for rev(1).

Linux tail doesn't have this feature, but they have tac(1) - which is a reverse cat(1), which corresponds to our tail -r.
And 'apropos rev' on Linux clearly tells the user that "lines are reversed characterwise".
This is much more presice and correct than our "reverse lines of a file".
The short description of our rev(1) is misleading and incorrect to my understanding - so it does not work as intended, because short descriptions mustn't be potentially misleading if it's easy to tell clearly and unambigous by little different wording.  Correcting rev(1)'s short description safes lifetime, why refusing to do so?

Linux's rev(1) man page also mentions tac(1) in the SEE ALSO section, because tac reverses lines of a file.
Like our tail -r does.
No single FreeBSD user nor developer will loose lifetime by having to read over the yet to be created SEE ALSO section of the rev(1) man page.
But even if the misleading "reverse lines of a file" is changed into "reverses lines characterwise", many FreeBSD users will safe lifetime by finding out tail -r might be the kind of reversing they are looking for.
Especially useres from different Unix-alike OSes, where the tail(1) implementation doesn't offer this feature, but tac(1) is availible.
We don't have tac, so having tail(1) in the SEE LASO section is extra beneficial for users missing tac, since tail -r is the aequivalent to tac.

If you still see no use of mentioning tail(1) in rev(1)'s SEE ALSO section, I want to discuss this on a wider base to know, what others think about.
I agree that sort(1) might be too far away with it's core functionality from rev's core function.  But tail -r is our tac and exactly does a reversing thing.

FreeBSD deserves keeping up good habits and this kind of user support, which simply helps saving time. It always has been the spirit of FreeBSD fellows to make usere's lives easier, not harder, that's why your shortcut in closing this request as "works as intened" is kind of upsetting me. In multiple ways it does not, to my understanding, which conforms to what the Linux guys think e.g.

Thanks
-harry

Comment 9 Fernando Apesteguía 2021-05-14 07:02:34 UTC

(In reply to Harald Schmalzbauer from comment #8)

> I still can't accept the "works as intended" closing

It was intended as "man(1) and apropos(1) work as intended", not as "everything is fine and I am right". Options, when we close a PR, are limited and sometimes the resolution does not quite fit any of them.

> Your statement "when you look for 'reverse' you should not find tail(1) or
> sort(1): because they do not reverse anything."is not true.tail(1) 
> is able to reverse the lines of a file.

I would argue that a command does what the description says it does. From tail(1):

tail – display the last part of a file

Yes, there is a flag that reverses the order of the lines, starting with the last one at the top, but tail(1) is not for reversal ordering in general. It is for when you are only interested in the last parts of a file. 

$ cat t
this is the first line
this is the second line
this is the third line
$ tail t
this is the first line
this is the second line
this is the third line
$ tail -r t 
this is the third line
this is the second line
this is the first line

> Linux tail doesn't have this feature, but they have tac(1) - which 
> is a reverse cat(1), which corresponds to our tail -r.

Well, yes and no :-) From a Suse Linux:

tac (1)              - concatenate and print files in reverse

So the _purpose_ of that command is to print in reverse. It does not have a flag to print in forward mode. It can use one separator or other, ok, but its _only_ purpose is to show files in reverse mode. The purpose of tail is to show the last part of the file.

BTW, typing 'apropos reverse' in Linux shows:

col (1)              - filter reverse line feeds from input XXX
git-rev-list (1)     - Lists commit objects in reverse chronological order
lreverse (n)         - Reverse the order of a list
pamendian (1)        - reverse endianness of a Netpbm image
pamperspective (1)   - a reverse scanline renderer for Netpbm images
rev (1)              - reverse lines characterwise
revoutput (3am)      - Reverse output strings sample extension
revtwoway (3am)      - Reverse strings sample two-way processor extension
rvnamed (8)          - reverse name resolution daemon for iptraf (8) XXX
tac (1)              - concatenate and print files in reverse
TAILQ_FOREACH_REVERSE (3) - implementations of singly-linked lists, singly-linked tail queues, lists and tail queues
thin_rmap (8)        - output reverse map of a thin provisioned region of blocks frommetadata device or file.
TIFFswab (3tiff)     - byte- and bit-swapping routines XXX
xxd (1)              - make a hexdump or do the reverse. XXX

At least the entries with XXX are pure noise. Seriously, xxd(1) does not have anything to do with reversing anything at all.

>  Correcting rev(1)'s short description safes lifetime, why refusing to do so?

Well, this is the first time that you proposes to do so. The PR is about adding tail -r and sort to SEE ALSO, not to change the description of rev(1). Nor could I find any references of your intention to change that description in the PR previous to this mention. In short: I did not refuse because we didn't even talk about it!

> If you still see no use of mentioning tail(1) in rev(1)'s SEE ALSO section, I want to discuss this on a wider base to know, what others think about.

Sure thing. You can probably write to freebsd-questions@ or freebsd-doc@. Also, remember that this PR is public as I am sure some people have passed by and read it.

> ... that's why your shortcut in closing this request as "works as intened" is kind of upsetting me...

It was not my intention to shortcut anything. I thought we had reached an agreement, which we clearly did not.

(In reply to Fernando Apesteguía from comment #9)
>> Linux tail doesn't have this feature, but they have tac(1) - which 
>> is a reverse cat(1), which corresponds to our tail -r.
> 
> Well, yes and no :-) From a Suse Linux:
> 
> tac (1)              - concatenate and print files in reverse
> 
> So the _purpose_ of that command is to print in reverse. It does not have a
> flag to print in forward mode. It can use one separator or other, ok, but its
> _only_ purpose is to show files in reverse mode. The purpose of tail is to show
> the last part of the file.

Exactly for the reason you mentioned in this last sentence, I want to see it mentioned in rev's SEE ALSO section.
People looking for reversing lines of a file might find rev(1), but won't find tail(1) with the current man page.  Instead they'll wonder why the description of rev(1) turns out to do something different than it's short description tells.

But tail(1) is not a single purpose tool in the incarnation we have in base.
Who mandates that SEE ALSO section must only list single purpose tools?

I won't waste others time, neither myself anymore.  You do not want to help improving FreeBSD, so I'll wait for changing responsibilities and re-open at times. Insisting of what the initial topic was about is nitpicking and time wasting.
Have you compared FreeBSD's 'apropos reverse'?  Good luck adjusting it to your understandings.

Comment 11 Fernando Apesteguía 2021-05-14 09:45:00 UTC

(In reply to Harald Schmalzbauer from comment #10)

> Who mandates that SEE ALSO section must only list single purpose tools?
Nobody AFAIK, neither I said so.
See: https://en.wikipedia.org/wiki/Man_page

I just don't get the relationship between showing the last 10 lines of a file like N-10, N-9...N-1 instead of N-1, N-2...N-10 and reversing the characters of every line in a file.

> You do not want to help improving FreeBSD...

That is just something you made up based on absolutely nothing but your opinion and not backup up by any facts. I even told you what mail lists you can address your concerns to. It is pretty unfair to be honest.

Nobody is preventing you to:
   1 - reopening this PR
   2 - renaming this PR to: "improve rev(1) short description" if that is what you want
   3 - adding a patch
   4 - opening a review (reviews.freebsd.org/) 
   5 - discussing this in any of the mailing lists available

Also, if you think I did not treat you properly, there are procedures you can use: https://www.freebsd.org/internal/code-of-conduct/

(In reply to Fernando Apesteguía from comment #11)

>> You do not want to help improving FreeBSD...

> That is just something you made up based on absolutely nothing but your
> opinion and not backup up by any facts. I even told you what mail lists you
> can address your concerns to. It is pretty unfair to be honest.

Sorry, I tried to explain with all my english wording available what my concern is about, but you always referenced facts, which I can't and never wanted to argue about, but have little to do what SEE ALSO and my intention is about.
Please see:

>> Who mandates that SEE ALSO section must only list single purpose tools?
> Nobody AFAIK, neither I said so.
> See: https://en.wikipedia.org/wiki/Man_page
> 
> I just don't get the relationship between showing the last 10 lines of a file
> like N-10, N-9...N-1 instead of N-1, N-2...N-10 and reversing the characters
> of every line in a file.

I think I made clear that I'm thinking of soembody wanting to reverse lines of a file. _Not_ the character sequence of a line!
This is a common requirement for administrative scripting tasks.
On Linux, I utilize apropos(1) and get the hint to tac(1) (as well as to rev(1) and some other unrelated tools, but it doesn't really bother anybody to this extent).
On FreeBSD, I utilize apropos too, and the only matching hint I get is to rev(1) (and lots of unrelated tools, which is no problem to this extent and not worth spending a single minute thinking about wether it is correct or not - there's real problems to work on) which does a different kind of reversing.
If I'm aware about tac(1), I have to assume FreeBSD doesn't provide a functionality to reverse lines of a file, since there is no tac.
Which is wrong, because our tail(1) version is a multi purpose tool, doing exactly what somebody is looking for, who might not be aware about that tail extension.  The latter is especially likely, because other tail(1) versions don't offer this mode.
But this fact currently is hidden, which results in a needless time consuming procedure for people like me, to falsify, because I don't want to believe that doc is correct in that regard.
I opened this PR to ask for unhiding it.
And, in the process of discussion, to correct rev(1)'s short description.

If I saw a commit clarifying rev(1) and closing this with "overcome by events", nothing would make me think you block FreeBSD improvements. I'd open another one requesting the SEE ALSO section to be added too.
But you closed with "works as intended" although I pointed out some misleading areas which definitely need correction.

I won't waste anybody elses time for esaclating this pointless discussion.
Lots of my fellows and myself utilized apropos(1) for more than two decades and learned about almost all tools this way.  SEE ALSO always has been the source of choice for reaching similar but different tools.  Exactly that's the case here.  Somebody wants to reverse something and there are two kinds of reversing (since we have two kinds of ordering regarding text processing), which can't be narrowed down further before looking up a tool to accomplish that.
And there are two different tools accomplishing those two different tasks which share the same describing resp. search wording.
At least the single purpose tool should reference the multi purpose counterpart for the other kind of related reversing resp. tool.
And all tools available for accomplishing "reversings" must be listed for a simple apropos(1) request.
If you think this is not the correct way to utilize apropos, and it's better to have people beeing forced to try harder finding available tools, I'm very disappointed, because this distracts people and wastes time. Needlessly.  That's why I come to the conclusion that you're not interested in improving FreeBSD usability. It's not nice, but it's not unfair too, just the summary of your responses.
If you feel responsible for documentation issues, but I need to spend an hour explaining why I think there is an docuemntation issue, we seem to have contrary ambitions.
My aim is to help people saving time.
Your aim is completely unclear to me after this disappointing discussion. That beeing said, let us agree on misunderstandings and go back to work.
-harry

Comment 13 Fernando Apesteguía 2021-05-14 14:33:45 UTC

Reopening to relieve OP's discomfort with the previous resolution.

Comment 14 Fernando Apesteguía 2022-02-01 15:38:16 UTC

We now have man -K

man -K 'reverse' -S1 

or 

man -K 'reverse.*order' -S1

help to find the proper result.

Closing since no action was taken by the OP.