Bug 280566 - tree(3) man page: Fix example source code.
Summary: tree(3) man page: Fix example source code.
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: Maxim Konovalov
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2024-08-02 04:33 UTC by Hodong
Modified: 2024-08-03 19:58 UTC (History)
4 users (show)

See Also:


Attachments
Fix the example source code in tree(3) man page EXAMPLES. (1.05 KB, patch)
2024-08-02 04:33 UTC, Hodong
no flags Details | Diff
Alternative patch for tree.3 (1.37 KB, patch)
2024-08-03 01:04 UTC, Maxim Konovalov
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Hodong 2024-08-02 04:33:40 UTC
Created attachment 252444 [details]
Fix the example source code in tree(3) man page EXAMPLES.

The example source code in the tree(3) manual page causes compilation error.

$ cc -Wall example.c -o example
example.c:25:9: warning: non-void function does not return a value [-Wreturn-type]
   25 |         }
      |         ^
example.c:75:24: warning: missing terminating '"' character [-Winvalid-pp-token]
   75 |                 printf("Sum of values = %d0, RB_ROOT(&head)->sum);
      |                        ^
example.c:75:24: error: expected expression
example.c:78:10: error: expected '}'
   78 |         }
      |          ^
example.c:60:9: note: to match this '{'
   60 |         {
      |         ^
2 warnings and 2 errors generated.

This patch fixes errors.
Comment 1 Maxim Konovalov freebsd_committer freebsd_triage 2024-08-03 01:03:48 UTC
Hi,

Thanks for the patch!

Just for the record, it seems that there are several separate issues with the example, specifically:

(1) RB_AUGMENT macro should be defined as early as possible.  Otherwise it is no-op and the program doesn't work as intended, e.g., it doesn't calculate sum of the tree elements.

(2) Man page formatting error that leads to a compilation error if you try to copy-paste the code.

(3) There is also a missed new line between the tree structure content and the sum of the elements but it looks minor.

I created a slightly better looking to me patch to address all of the above.

Dear Hodong, are you good with this one?

Thanks,

Maxim
Comment 2 Maxim Konovalov freebsd_committer freebsd_triage 2024-08-03 01:04:31 UTC
Created attachment 252471 [details]
Alternative patch for tree.3
Comment 3 Maxim Konovalov freebsd_committer freebsd_triage 2024-08-03 01:12:17 UTC
I cc'ed Doug to this ticket who is the author of the code and man page changes just as a heads up.
Comment 4 Hodong 2024-08-03 02:15:21 UTC
Your patch works fine. It's much nicer than what I wrote. I appreciate it.
Comment 5 Maxim Konovalov freebsd_committer freebsd_triage 2024-08-03 02:21:47 UTC
Great!  Thanks for the review.

I'll let Doug to chime in and commit it afterwards.

Maxim
Comment 6 Doug Moore 2024-08-03 02:35:47 UTC
These seem to be entirely my errors, and the second patch fixes them well.  One odd thing that isn't my responsibility is the use of "\en" instead of "\n".  I don't know why the 'e' is there, and would remove it unless there's an explanation for it.
Comment 7 Maxim Konovalov freebsd_committer freebsd_triage 2024-08-03 03:32:16 UTC
Thanks, Doug.

Actually, \e is just a troff version of \.  Therefore \en stands for \n in troff world.

Maxim
Comment 8 commit-hook freebsd_committer freebsd_triage 2024-08-03 19:47:07 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=503b7f94d831642308585c980a7cabe4470960d0

commit 503b7f94d831642308585c980a7cabe4470960d0
Author:     Maxim Konovalov <maxim@FreeBSD.org>
AuthorDate: 2024-08-03 19:45:47 +0000
Commit:     Maxim Konovalov <maxim@FreeBSD.org>
CommitDate: 2024-08-03 19:45:47 +0000

    tree.3: the example code fixed

    PR:             280566
    Reviewed by:    dougm

 share/man/man3/tree.3 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Comment 9 Maxim Konovalov freebsd_committer freebsd_triage 2024-08-03 19:58:41 UTC
The man page fixed.  Thanks for the report!