git: 7e68976408e4 - main - echo(1): Add EXAMPLES

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/src/commit/?id=7e68976408e4df21e120e2d6440392302cac84f3

commit 7e68976408e4df21e120e2d6440392302cac84f3
Author:     Fernando Apesteguía <fernape@FreeBSD.org>
AuthorDate: 2023-09-07 13:27:49 +0000
Commit:     Fernando Apesteguía <fernape@FreeBSD.org>
CommitDate: 2024-04-08 16:35:40 +0000

    echo(1): Add EXAMPLES
    
    While here add CAVEAT section and promote the use of printf(1)
    
    Reviewed by:            gbe@, imp@
    Approved by:            manpages (gbe)
    Differential Revision:  https://reviews.freebsd.org/D43493
---
 bin/echo/echo.1 | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/bin/echo/echo.1 b/bin/echo/echo.1
index aa547d2350f5..cb60bdcc88dd 100644
--- a/bin/echo/echo.1
+++ b/bin/echo/echo.1
@@ -89,6 +89,24 @@ Consult the
 manual page.
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+Special treatment of options and backslashes:
+.Bd -literal -offset indent
+$ /bin/echo "-hello\\tworld"
+-hello\tworld
+.Ed
+.Pp
+Avoid new line character:
+.Bd -literal -offset indent
+$ /bin/echo -n hello;/bin/echo world
+helloworld
+.Ed
+.Pp
+Or to achieve the same result:
+.Bd -literal -offset indent
+$ /bin/echo "hello\\c";/bin/echo world
+helloworld
+.Ed
 .Sh SEE ALSO
 .Xr builtin 1 ,
 .Xr csh 1 ,
@@ -105,3 +123,14 @@ The
 .Nm
 command appeared in
 .At v2 .
+.Sh CAVEATS
+The
+.Nm
+command behaves differently with regards to the built-in
+.Nm
+shell command in a number of ways including escaped characters handling.
+It also differs in behavior between different systems hence complicating writing
+portable scripts.
+It is advised to use the
+.Xr printf 1
+command to avoid these shortcomings.