Update to printf.3 based on OpenBSD manual page structure #1200

chrisdavidson · 2024-04-25T03:31:59Z

Bug #247900
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=247900

printf.3
Update order of parameters alphabetically
Add parameter syntax to each parameter for clarity Untangle multiple opton entries into individual entries Update sentence structure throughout
Provide clarity on symbol based parameters

chrisdavidson · 2024-04-25T03:34:10Z

This is a new pull request to address the questions/comments/suggestions as described in pull request: #1149

lib/libc/stdio/printf.3

concussious · 2024-04-25T12:41:49Z

lib/libc/stdio/printf.3

I noticed you changed the semantic Defined variable macro to the presentational Emphasis macro for stdout.

The semantic (regular) Variable macro (usually) renders the same way, how does everyone feel about using that?

I noticed you changed the semantic Defined variable macro to the presentational Emphasis macro for stdout.

The semantic (regular) Variable macro (usually) renders the same way, how does everyone feel about using that?

it looks good for stdout

We generally use Dv stdout although there are a few instances of Em and Va. I would prefer Dv.

concussious · 2024-04-25T13:07:27Z

Just curious, what kind of tooling are you using that's putting g's at the end of lines?

chrisdavidson · 2024-04-25T13:43:04Z

no tooling, it is my finger typing that is causing the headache and i am working improving my neovim interaction to resolve this.

rilysh · 2024-04-26T06:09:23Z

lib/libc/stdio/printf.3

 .Fn asprintf
 and
 .Fn vasprintf
 dynamically allocate a new string with
-.Xr malloc 3 .
+.Xr malloc 3


IMO the previous one, "dynamically allocate a new string with malloc(3)." seems better than the explicit mentioning of "that is stored in ret." (ret is the return pointer, but confusing here).

i see that and it does read better having the ret removed, updates will have this change.

dag-erling · 2024-04-27T06:15:34Z

lib/libc/stdio/printf.3

We generally use Dv stdout although there are a few instances of Em and Va. I would prefer Dv.

dag-erling · 2024-04-27T06:17:58Z

lib/libc/stdio/printf.3

@@ -297,13 +335,14 @@ should be grouped and separated by thousands using
 the non-monetary separator returned by
 .Xr localeconv 3 .
 .El
-.It
+.Itg


Suggested change

.Itg

dag-erling · 2024-04-27T06:18:50Z

lib/libc/stdio/printf.3

 The
 .Vt double
-argument is rounded and converted in the style
+argument is rounded and converted tog


Suggested change

argument is rounded and converted tog

argument is rounded and converted to

dag-erling · 2024-04-27T06:18:59Z

lib/libc/stdio/printf.3

-The exponent always contains at least two digits; if the value is zero,
-the exponent is 00.
+where the number of digits after the hexadecimal-point character
+is equal to theg


Suggested change

is equal to theg

is equal to the

lib/libc/stdio/printf.3

dag-erling · 2024-04-27T06:24:34Z

lib/libc/stdio/printf.3

-respectively.
-These conversion characters are deprecated, and will eventually disappear.
-.It Cm eE
+to represent theg


Suggested change

to represent theg

to represent the

lib/libc/stdio/printf.3

dag-erling · 2024-04-27T06:25:29Z

lib/libc/stdio/printf.3

+.Li INFg
+org
+.Li -INF .
+If the argument is not-a-number (NaN), it is converted tog


Suggested change

If the argument is not-a-number (NaN), it is converted tog

If the argument is not-a-number (NaN), it is converted to

dag-erling · 2024-04-27T06:27:00Z

lib/libc/stdio/printf.3

+.It Cm B
+The
+.Vt unsigned int
+(or apporiate variant) argument is converted to unsigned binary.


This is a little thin compared to, say, o or x.

i agree, would you recommend evaluating what o and x look like and see how it aligns with B since they are similar specifiers?

dag-erling · 2024-04-27T06:27:04Z

lib/libc/stdio/printf.3

+.It Cm b
+The
+.Vt unsigned int
+(or appropriate variant) argument is converted to unsigned binary.


This is a little thin compared to, say, o or x.

dag-erling · 2024-04-27T14:12:25Z

lib/libc/stdio/printf.3

@@ -29,7 +29,10 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 5, 2023
+.\" -


Suggested change

.\" -

concussious · 2024-04-25T14:05:03Z

lib/libc/stdio/printf.3

+.Pp
+.Cm A
+conversion uses the prefix
+.Dq Li 0X ,


The Ql macro is the preferred macro for formatting literal inline fragments. Historically, Dq Li was the preferred way before the deprecation of Li.
~style.mdoc(5)

With that change, would it appropriate to use Sq/Ql elsewhere as well for consistency? These render with single quotes on console, so it looks inconsistent from where where the file is previously using Dq.

i am not sure i am following. The recommendation is to make all from .Sq/.Ql -> .Dq basee on your reference?

lib/libc/stdio/printf.3

chrisdavidson · 2024-04-28T14:26:42Z

and now we have some more details with b and B options, these updates are based on the wording and structure of the x and X documentation, with the necessary conversation to binary notation.

dag-erling

I'm beginning to question how seriously you're taking this.

dag-erling · 2024-04-28T17:08:39Z

lib/libc/stdio/printf.3

+.Cm B
+.Sm on
+.Pp
+The


This is redundant now.

lib/libc/stdio/printf.3

chrisdavidson · 2024-04-29T21:40:50Z

Thank you all for the suggestions/comments/recommendations on this pull request.

The latest one, has incorporated these changes along with the refinement of b and B options. The options were updated based on the std documentation shared.

Please let me know if there is anything missing or refined.

Again thank you for the guidance on this manual page update.

Bug #247900 https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=247900 MFC: 1 week

dag-erling · 2024-04-30T08:30:25Z

There are still eight instances of “theg” and one instance of “tog” in the text. They are all individually marked in this review and trivial to find using your editor's search function, yet they are still present.
You keep making up new incorrect text for the B and b conversion specifiers instead of just copying the text for X and x verbatim and changing only what needs to change.
Please move the SPDX tag to the top like you were asked. It needs to be preceded and followed by exactly one blank comment line. There also needs to be a single blank comment line between the bottom of the disclaimer and the .Dd line.
Please review your changes using git diff freebsd/main.. and man lib/libc/stdio/printf.3 before pushing.
Please stop rebasing your branch, it makes it harder for us to review your progress. We will rebase and possibly squash as we see fit when (if) we commit your patch.

dag-erling · 2024-05-12T15:19:59Z

lib/libc/stdio/printf.3

+.Pp
+Similar to
+.Cm b
+with the variation on the string value prefix


Ungrammatical.

dag-erling · 2024-05-12T15:20:18Z

lib/libc/stdio/printf.3

+Similar to
+.Cm b
+with the variation on the string value prefix
+.Sq Ob


dag-erling · 2024-05-12T15:20:21Z

lib/libc/stdio/printf.3

+with the variation on the string value prefix
+.Sq Ob
+to
+.Sq OB


lib/libc/stdio/printf.3

dag-erling · 2024-05-12T15:22:14Z

lib/libc/stdio/printf.3

+.Pp
+For non zero results the prefix 
+.Sq 0b
+will be prepended to result.


Really? Always?

lib/libc/stdio/printf.3

dag-erling · 2024-05-12T15:25:23Z

lib/libc/stdio/printf.3

+.Ar u
+except that the
+.Ar unsigned int
+argument is converted to unsigned octal notation.


Why does o now use different wording than b and x?

lib/libc/stdio/printf.3

bsdimp · 2024-05-25T12:46:27Z

ping? what are the plans here? It can't land as it is, and the changes @dag-erling is suggesting are more intensive than I can do while prepping to land the change.

chrisdavidson · 2024-05-25T17:15:38Z

i am currently working through @dag-erling recommendarions and requests. as it stands, it's going to be a little while.. is there a way to tag as "going slow but it's going"?

bsdimp · 2024-05-25T17:25:49Z

I'm unsure. I'll check back every couple of weeks or so. Take your time.

bsdimp added the needs-review label Apr 25, 2024

concussious reviewed Apr 25, 2024

View reviewed changes

lib/libc/stdio/printf.3 Show resolved Hide resolved

concussious reviewed Apr 25, 2024

View reviewed changes

rilysh reviewed Apr 26, 2024

View reviewed changes

chrisdavidson mentioned this pull request Apr 27, 2024

Update printf(3) based on latest OpenBSD structure and format #1149

Closed

dag-erling suggested changes Apr 27, 2024

View reviewed changes

chrisdavidson force-pushed the printf3 branch 2 times, most recently from e9c0dca to 4e42125 Compare April 27, 2024 13:13

dag-erling suggested changes Apr 27, 2024

View reviewed changes

concussious suggested changes Apr 27, 2024

View reviewed changes

chrisdavidson force-pushed the printf3 branch from 4e42125 to 827e047 Compare April 28, 2024 14:20

dag-erling suggested changes Apr 28, 2024

View reviewed changes

chrisdavidson force-pushed the printf3 branch from 677aea4 to 16bda5b Compare April 29, 2024 21:38

printf.3 - Improvements to manual page

3c57479

Bug #247900 https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=247900 MFC: 1 week

chrisdavidson force-pushed the printf3 branch from c036e65 to 3c57479 Compare April 29, 2024 21:47

Refine of X and X conversion types to align with other converstion types

332140f

dag-erling suggested changes May 12, 2024

View reviewed changes

bsdimp added changes-required and removed needs-review labels May 16, 2024

bsdimp added the man-only label Jun 2, 2024

	argument is rounded and converted tog
	argument is rounded and converted to

	If the argument is not-a-number (NaN), it is converted tog
	If the argument is not-a-number (NaN), it is converted to

Update to printf.3 based on OpenBSD manual page structure #1200

Are you sure you want to change the base?

Update to printf.3 based on OpenBSD manual page structure #1200

Conversation

chrisdavidson commented Apr 25, 2024

chrisdavidson commented Apr 25, 2024

concussious Apr 25, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

concussious commented Apr 25, 2024

chrisdavidson commented Apr 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

concussious Apr 25, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidson commented Apr 28, 2024

dag-erling left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidson commented Apr 29, 2024

dag-erling commented Apr 30, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bsdimp commented May 25, 2024

chrisdavidson commented May 25, 2024

bsdimp commented May 25, 2024

concussious Apr 25, 2024 •

edited

concussious Apr 25, 2024 •

edited