echo(1): Add EXAMPLES

[fernape]

Summary

Add some examples to the manual page.

Test Plan

Apply patch and view manual page.

igor, vale and mandoc -T lint are OK with the change

[pauamma_gundo.com]

bin/echo/echo.1

95–96

[pauamma@Pusat-Tasek] ~% /bin/echo "-hello\\tworld"
-hello\\tworld

Note the double backslash, compared to the single one in your example output.

101

Is there a reason to use the builtin echo for the 2nd invocation?

107

Same question here, plus spurious space before ;

[pauamma@Pusat-Tasek] ~% /bin/echo "hello\\c" ;echo world
hello\world

Note the backslash in the output, vs. none in your example output.

[imp]

I'd be more likely to suggest people use the more portable constructs available from printf(1).

bin/echo/echo.1

95–96

This is a difference between /bin/sh and /bin/csh and quoting rules.
If you do it inside of /bin/sh, then you get this output.

[fernape]

Use /bin/echo always

[fernape]

bin/echo/echo.1

95–96

But that is not what the user sees. Please, render the manpage with man ./echo.1. The first backslash is for mandoc. This is what is rendered:

Special treatment of options and backslashes:

      $ /bin/echo "-hello\tworld" <---- Just \t not \\t
      -helloworld

95–96

Yes, the examples use sh

107

Ditto, this is what the user sees when the manual page is rendered:

Or to achieve the same result:

      $ /bin/echo "hello\c" ;echo world
      helloworld

[fernape]

In D43493#991914, @imp wrote:

I'd be more likely to suggest people use the more portable constructs available from printf(1).

printf(1) is mentioned in the SEE ALSO section. Do you mean an additional note reinforcing the idea of using printf(1) instead of echo(1)?

[imp]

In D43493#991952, @fernape wrote:

In D43493#991914, @imp wrote:

I'd be more likely to suggest people use the more portable constructs available from printf(1).

printf(1) is mentioned in the SEE ALSO section. Do you mean an additional note reinforcing the idea of using printf(1) instead of echo(1)?

Yes. I'm of the opinion that echo should not be used any time you want the output to be exactly "just so" because other implementations don't do the \X expansion quite right, or they don't recognize the command switches to not do newline. And it's not even portable between /bin/echo and sh(1) builtin-echo on FreeBSD. For those times, you should use printf(1). It's also builtin to shell and any performance difference between echo and printf is going to be in the noise.

[fernape]

Add CAVEATS section to promote the use of printf(1)

[imp]

I'm more concerned that uses of echo are also non-portable to other systems.
The difference between /bin/sh and /bin/csh are likely not that interesting because almost nobody writes csh scripts.
printf is portable and the same everywhere (more or less), but echo is eccentrically different.

[fernape]

Remove reference to differences between shells.
Focus on portability issues.

[pauamma_gundo.com]

English nitpicks fixable on commit.

bin/echo/echo.1

129

136

Or are the two shortcomings only one?

[fernape]

Use plural.

[gbe]

LGTM

[fernape]

Thank you all for the review.