system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example
PATCH 1/1 system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example
---
Hi Michael,
Quoted 4 lines · Michael Kerrisk (man-pages)
PS It occurs to me that this manual page is a suitable place to explain the general technique of casting integral system data types to [u]intmax_t for the purpose of
printf(). Would you like to add this, Alex?
Sure. Good idea!
Hope you like the patch :)
Cheers,
Alex
man7/system_data_types.7 | 52 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+)
man7/system_data_types.7 +52 -0
@@ -626,6 +626,58 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the types described in this page don't have a corresponding +length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of a type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of a type that doesn't have a length modifier, +an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of a type that doesn't have a length modifier. +The appropriate conversions from and to +.I intmax_t +are used as explained in the notes section above: +.PP +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> + +int +main (void) +{ + static const char *const str = "There are 60 s in an hour"; + time_t secs; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "There are %jd", &tmp); + + /* Copy the value to the time_t variable secs */ + secs = tmp; + + /* Print the value */ + printf("There are %jd seconds in an hour!\en", (intmax_t) secs); + + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Signature · 1 line
2.28.0
Hi Alex,
Quoted 6 lines · Alejandro Colomar
Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
Hi Michael,On 9/20/20 10:20 PM, Michael Kerrisk (man-pages) wrote:
Quoted 8 lines
Quoted 4 lines
PS It occurs to me that this manual page is a suitable place to explain the general technique of casting integral system data types to [u]intmax_t for the purpose of
printf(). Would you like to add this, Alex?Sure. Good idea!
Hope you like the patch :)
Good in principle, but some tweaks required.
man7/system_data_types.7 See also: · line 630
Quoted 13 lines
man7/system_data_types.7 | 52 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+)man7/system_data_types.7 +2
-0@@ -626,6 +626,58 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the types described in this page don't have a corresponding
s/types/integer types/
man7/system_data_types.7 See also: · line 642
Quoted 12 lines
man7/system_data_types.7 +12
-0+length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of a type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of a type that doesn't have a length modifier,
s/a type/an integer/
man7/system_data_types.7 See also: · line 647
Quoted 5 lines
man7/system_data_types.7 +5
-0+an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used.
Hmmm -- I wonder if we need to say something about range checking. I mean, what if time_t is narrower than intmax_t in the example below? (It's not, on my x86-64 system.) The problem of course is how to construct such a range check in the absence of any appropriate POSIX constants (e.g., there is no TIME_T_MAX).
Quoted 8 lines
man7/system_data_types.7 +8
-0+The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of a type that doesn't have a length modifier. +The appropriate conversions from and to +.I intmax_t +are used as explained in the notes section above: +.PP
man7/system_data_types.7 See also: · line 665
Quoted 10 lines
man7/system_data_types.7 +10
-0+.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> + +int +main (void) +{ + static const char *const str = "There are 60 s in an hour";
Either "60" needs to be 3600 or "hour" needs to be "minute".
man7/system_data_types.7 See also: · line 676
Quoted 11 lines
man7/system_data_types.7 +11
-0+ time_t secs; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "There are %jd", &tmp); + + /* Copy the value to the time_t variable secs */ + secs = tmp; + + /* Print the value */ + printf("There are %jd seconds in an hour!\en", (intmax_t) secs);
See my previous comment. A change may be required in the line above.
man7/system_data_types.7 See also: · line 683
Quoted 7 lines
man7/system_data_types.7 +4
-0+ + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Hello Michael,
Indentation of structure definitions, shell session logs, and so on
When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and EE macros, and surround them with suitable paragraph markers (either .PP or .IP). For example:
.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PPThat could be simplified to the following, right?:
.IP
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.PPOr is there any difference?
Thanks,
Alex
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Hi Alex,
Quoted 36 lines · Alejandro Colomar
Hello Michael,
Indentation of structure definitions, shell session logs, and so on
When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and EE macros, and surround them with suitable paragraph markers (either .PP or .IP). For example:
.PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PPThat could be simplified to the following, right?:
.IP .EX int main(int argc, char *argv[]) { return 0; } .EE .PP
Quoted 1 line
Or is there any difference?
.IP indents by 8 spaces by default, I think. Also, .IP won't indent further, if we are already in an area of indented paragraphs.
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Quoted 33 lines · Michael Kerrisk (man-pages)
Quoted 32 lines · Alejandro Colomar
Indentation of structure definitions, shell session logs, and so on
When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and EE macros, and surround them with suitable paragraph markers (either .PP or .IP). For example:
.PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PPThat could be simplified to the following, right?:
.IP .EX int main(int argc, char *argv[]) { return 0; } .EE .PP
Quoted 3 lines
Quoted 1 line
Or is there any difference?
.IP indents by 8 spaces by default, I think.
7 "ens" on nroff devices (like terminals), 7.2n on troff devices.
An "en" is a traditional typesetting unit of measure, the width of a letter "n" in the font being used. For monospaced fonts, including those used in character-cell terminals--barring the employment of CJK "fullwidth" code points--this is the same width as a space.
Quoted 2 lines
Also, .IP won't indent further, if we are already in an area of indented paragraphs.
This is true. In my maintenance work on groff's man pages I have devised an idiom of calling .RS twice, putting in the desired material, and then calling .RE twice.
In membarrier(2), however, life is simple because no code examples are being nested inside an indented paragraph (.IP). I'm attaching a patch; it produces no visible difference in output, not even white space changes.
I should add that my suggestion is to _not_ specify precise indentation amounts in man pages, as this is a presentation matter and readers may prefer tighter or more generous indentation, which they can control via the IN register; that is, passing -rIN to the groff command. (Or, more likely, by configuring it in their man.local file so all pages that respect the user's wishes are consistent.)
I've been improving the groff_man(7) page over the past few years to document all of this stuff much better, and recently in groff git[1] I've split out a groff_man_style(7) page. The latter is (as near as makes no difference) a strict superset of the former.
Michael's site has a fairly recent snapshot of these pages:
https://man7.org/linux/man-pages/man7/groff_man.7.html
https://man7.org/linux/man-pages/man7/groff_man_style.7.html
Feedback is welcome. For the latter page, I still need to write my grand introduction where I explain the real typesetting basics: filling, adjusting, breaking, and how these all relate to hyphenation.
In my opinion, .in requests are never necessary in idiomatic, well-written man pages and I'm happy to offer technical advice for how to achieve the desired result without using them.
I'm also happy to prepare patches for man-pages documents implementing my recommendations. :)
Regards,
Branden
[1] https://git.savannah.gnu.org/cgit/groff.git
Use .RS/.RE man macros instead of .in requests.
man2/membarrier.2 +6 -6
@@ -60,11 +60,11 @@ The key idea is to replace, for these matching barriers, the fast-side memory barriers by simple compiler barriers, for example: .PP -.in +4n +.RS 4 .EX asm volatile ("" : : : "memory") .EE -.in +.RE .PP and replace the slow-side memory barriers by calls to .BR membarrier ().
@@ -285,7 +285,7 @@ very frequently, and where "slow_path()" is executed infrequently, the following code (x86) can be transformed using .BR membarrier (): .PP -.in +4n +.RS .EX #include <stdlib.h>
@@ -332,13 +332,13 @@ main(int argc, char **argv) exit(EXIT_SUCCESS); } .EE -.in +.RE .PP The code above transformed to use .BR membarrier () becomes: .PP -.in +4n +.RS .EX #define _GNU_SOURCE #include <stdlib.h>
@@ -421,4 +421,4 @@ main(int argc, char **argv) exit(EXIT_SUCCESS); } .EE -.in +.RE
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Hi Branden,
Quoted 34 lines · G. Branden Robinson
Quoted 33 lines · Michael Kerrisk (man-pages)
Quoted 32 lines · Alejandro Colomar
Indentation of structure definitions, shell session logs, and so on
When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and EE macros, and surround them with suitable paragraph markers (either .PP or .IP). For example:
.PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PPThat could be simplified to the following, right?:
.IP .EX int main(int argc, char *argv[]) { return 0; } .EE .PP
Quoted 5 lines
Quoted 3 lines
Quoted 1 line
Or is there any difference?
.IP indents by 8 spaces by default, I think.
7 "ens" on nroff devices (like terminals), 7.2n on troff devices.
D'oh, yes. 7!
Quoted 33 lines
An "en" is a traditional typesetting unit of measure, the width of a letter "n" in the font being used. For monospaced fonts, including those used in character-cell terminals--barring the employment of CJK "fullwidth" code points--this is the same width as a space.
Quoted 2 lines
Also, .IP won't indent further, if we are already in an area of indented paragraphs.
This is true. In my maintenance work on groff's man pages I have devised an idiom of calling .RS twice, putting in the desired material, and then calling .RE twice.
In membarrier(2), however, life is simple because no code examples are being nested inside an indented paragraph (.IP). I'm attaching a patch; it produces no visible difference in output, not even white space changes.
I should add that my suggestion is to _not_ specify precise indentation amounts in man pages, as this is a presentation matter and readers may prefer tighter or more generous indentation, which they can control via the IN register; that is, passing -rIN to the groff command. (Or, more likely, by configuring it in their man.local file so all pages that respect the user's wishes are consistent.)
I've been improving the
groff_man(7)page over the past few years to document all of this stuff much better, and recently in groff git[1] I've split out agroff_man_style(7)page. The latter is (as near as makes no difference) a strict superset of the former.Michael's site has a fairly recent snapshot of these pages:
https://man7.org/linux/man-pages/man7/groff_man.7.html
https://man7.org/linux/man-pages/man7/groff_man_style.7.html
Quoted 7 lines
Feedback is welcome. For the latter page, I still need to write my grand introduction where I explain the real typesetting basics: filling, adjusting, breaking, and how these all relate to hyphenation.
In my opinion, .in requests are never necessary in idiomatic, well-written man pages and I'm happy to offer technical advice for how to achieve the desired result without using them.
So, I don't disagree with you. (And as ever, thank you for your detailed input.) The pattern I use above (with ".in +4n/.in" was a hack that I cam up with to get code blocks with a "suitable" indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've quoted inline below), does seem better. I'm not averse to changing things. But, there is a related question. I use a similar hack in the SYNOPSIS of many pages (e.g., chmod.2), to undent a single line:
[[
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.PP
]]
Presumably, that could be replaced with ".RS -4/.RE", but is there something even better?
Thanks,
Michael
Quoted 9 lines
I'm also happy to prepare patches for man-pages documents implementing my recommendations. :)
Regards,
Branden
======
Use .RS/.RE man macros instead of .in requests.
man2/membarrier.2 +6 -6
@@ -60,11 +60,11 @@ The key idea is to replace, for these matching barriers, the fast-side memory barriers by simple compiler barriers, for example: .PP -.in +4n +.RS 4 .EX asm volatile ("" : : : "memory") .EE -.in +.RE .PP and replace the slow-side memory barriers by calls to .BR membarrier ().
@@ -285,7 +285,7 @@ very frequently, and where "slow_path()" is executed infrequently, the following code (x86) can be transformed using .BR membarrier (): .PP -.in +4n +.RS .EX #include <stdlib.h>
@@ -332,13 +332,13 @@ main(int argc, char **argv) exit(EXIT_SUCCESS); } .EE -.in +.RE .PP The code above transformed to use .BR membarrier () becomes: .PP -.in +4n +.RS .EX #define _GNU_SOURCE #include <stdlib.h>
@@ -421,4 +421,4 @@ main(int argc, char **argv) exit(EXIT_SUCCESS); } .EE -.in +.RE
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Quoted 1 line · Michael Kerrisk (man-pages)
On 9/21/20 4:15 PM, G. Branden Robinson wrote:
[much snippage]
Quoted 22 lines
Quoted 3 lines
In my opinion, .in requests are never necessary in idiomatic, well-written man pages and I'm happy to offer technical advice for how to achieve the desired result without using them.
So, I don't disagree with you. (And as ever, thank you for your detailed input.) The pattern I use above (with ".in +4n/.in" was a hack that I cam up with to get code blocks with a "suitable" indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've quoted inline below), does seem better. I'm not averse to changing things. But, there is a related question. I use a similar hack in the SYNOPSIS of many pages (e.g., chmod.2), to undent a single line:
[[
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BRfeature_test_macros(7)):
.in
.PP
]]
Quoted 2 lines
Presumably, that could be replaced with ".RS -4/.RE", but is there something even better?
You're correct; .RS honors a negative indentation argument. So you could do this and I would consider it an improvement because it reduces the number of lexemes that man page readers--human and machine alike--have to comprehend.
I noticed something about "Feature Test Macro Requirements for glibc", however...
Because of the negative indent, it's within one en of the indentation of a subsection (.SS) heading; in fact it's an exact match on nroff devices (terminals). I'm guessing that wasn't an accident. You're even already title-casing it like a heading.
If you used .SS, it look much the same but end up in bold.
Admittedly the parenthetical man page cross-reference fits poorly with a subsection heading, in part because the font style change would be obscured. However, I think that could be moved to the _end_ of the synopsis with little loss. It doesn't take seasoned readers of section 2 and 3 man-pages documents long to internalize this knowledge about feature_test_macros(7), so repeating it by rote in the current pseudo-heading may not be helping much. Inexperienced readers need to read closely anyway, and experienced ones already know this information.
I notice that in these feature test macro areas you're making heavy use of .ad and .br requests, as well as the deprecated .PD macro to set the inter-paragraph spacing to zero. However, that's probably a digression for another thread... :)
Regards,
Branden
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Quoted 25 lines · G. Branden Robinson
Quoted 1 line · Michael Kerrisk (man-pages)
On 9/21/20 4:15 PM, G. Branden Robinson wrote:
[much snippage]
Quoted 22 lines
Quoted 3 lines
In my opinion, .in requests are never necessary in idiomatic, well-written man pages and I'm happy to offer technical advice for how to achieve the desired result without using them.
So, I don't disagree with you. (And as ever, thank you for your detailed input.) The pattern I use above (with ".in +4n/.in" was a hack that I cam up with to get code blocks with a "suitable" indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've quoted inline below), does seem better. I'm not averse to changing things. But, there is a related question. I use a similar hack in the SYNOPSIS of many pages (e.g., chmod.2), to undent a single line:
[[
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BRfeature_test_macros(7)):
.in
.PP
]]
Quoted 7 lines
Quoted 2 lines
Presumably, that could be replaced with ".RS -4/.RE", but is there something even better?
You're correct; .RS honors a negative indentation argument. So you could do this and I would consider it an improvement because it reduces the number of lexemes that man page readers--human and machine alike--have to comprehend.
I've done it.
Quoted 9 lines
I noticed something about "Feature Test Macro Requirements for glibc", however...
Because of the negative indent, it's within one en of the indentation of a subsection (.SS) heading; in fact it's an exact match on nroff devices (terminals). I'm guessing that wasn't an accident. You're even already title-casing it like a heading.
Quoted 5 lines
If you used .SS, it look much the same but end up in bold.
Admittedly the parenthetical man page cross-reference fits poorly with a subsection heading, in part because the font style change would be obscured.
(Yes, I'm not so keen on that.)
Quoted 6 lines
However, I think that could be moved to the _end_ of the synopsis with little loss. It doesn't take seasoned readers of section 2 and 3 man-pages documents long to internalize this knowledge about
feature_test_macros(7), so repeating it by rote in the current pseudo-heading may not be helping much. Inexperienced readers need to read closely anyway, and experienced ones already know this information.
Possibly you are right, but that's a bigger global edit that I won't attempt for now.
Quoted 4 lines
I notice that in these feature test macro areas you're making heavy use of .ad and .br requests, as well as the deprecated .PD macro to set the inter-paragraph spacing to zero. However, that's probably a digression for another thread... :)
I think the words you were looking for are "disgusting hack" :-). Feel free to start another thread...
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
In reply to G. Branden RobinsonHi Branden,
I want to circle back to a point you raised...
Quoted 45 lines · G. Branden Robinson
Quoted 33 lines · Michael Kerrisk (man-pages)
Quoted 32 lines · Alejandro Colomar
Indentation of structure definitions, shell session logs, and so on
When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and EE macros, and surround them with suitable paragraph markers (either .PP or .IP). For example:
.PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PPThat could be simplified to the following, right?:
.IP .EX int main(int argc, char *argv[]) { return 0; } .EE .PPQuoted 3 lines
Quoted 1 line
Or is there any difference?
.IP indents by 8 spaces by default, I think.
7 "ens" on nroff devices (like terminals), 7.2n on troff devices.
An "en" is a traditional typesetting unit of measure, the width of a letter "n" in the font being used. For monospaced fonts, including those used in character-cell terminals--barring the employment of CJK "fullwidth" code points--this is the same width as a space.
Quoted 6 lines
Quoted 2 lines
Also, .IP won't indent further, if we are already in an area of indented paragraphs.
This is true. In my maintenance work on groff's man pages I have devised an idiom of calling .RS twice, putting in the desired material, and then calling .RE twice.
If I understand what you are saying, then iif we are at an indented level (.TP, .IP), then we can use your idiom:
.RS
.RS n
...
.RE
.RE
But, this idiom won't work if we're not at an indented level (?). In other words, at .PP level we should not use .RS/.RS n/.RE/.RE, right?
By contrast, ".in +n/.in" works regardless of whether we are at an indented level, right? (I'm not saying this recommend the use of .in; I just want to clarify my understanding.)
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Quoted 13 lines · Michael Kerrisk (man-pages)
Hi Branden,
I want to circle back to a point you raised...
If I understand what you are saying, then iif we are at an indented level (.TP, .IP), then we can use your idiom:.RS
.RS n
...
.RE
.RE
Quoted 3 lines
But, this idiom won't work if we're not at an indented level (?). In other words, at .PP level we should not use .RS/.RS n/.RE/.RE, right?
Not true. You can use .RS/.RE "almost everywhere", as topologists say.
Quoted 3 lines
By contrast, ".in +n/.in" works regardless of whether we are at an indented level, right? (I'm not saying this recommend the use of .in; I just want to clarify my understanding.)
.RS and .RE are wrappers around .in. .RS applies a default indentation if one is not given, and in any case stores the indentation amount in a register named for the indentation "level" (roughly[2], how many times you've called .RS since the last .SH or .SS). That way you can call .RE without arguments, or as ".RE 2" to say "go back two indentation levels" without having to track or remember any indentation measurements.
Does this help? If you can think of any place in groff_man(7) or groff_man_style(7) I can make this clearer, please tell me. Until today the only two "FAQ"s I had in (what is now) the style page dealt with relative insets.
And you're not alone in misunderstanding .RS/.RE. My frustration with it back in August 2017 it is a major part of what sucked me into the groff project in the first place[1].
Regards,
Branden
[1] I wouldn't try it inside one of the macros that uses an "input trap". I don't think it would occur to most people to even try, so I'll save my experiments for _after_ I've sent this mail. :)
[2] .RS and .RE work like nested parentheses.
[3] https://lists.gnu.org/archive/html/groff/2017-08/msg00028.html
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Quoted 2 lines · G. Branden Robinson
[...] you can call .RE [...] as ".RE 2" to say "go back two indentation levels"
Nope, that's wrong. Forget I said that; I think I might now see something I can further improve in the documentation.
You can see I'm still bedeviled by relative insets. :-|
I tend to never use the argument to .RE; I just call .RE multiple times to balance out my .RS calls, just like parentheses. When I do that, I don't get surprised.
Quoted 1 line
without having to track or remember any indentation measurements.
This part remains true. :)
Regards,
Branden
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Hi Branden,
Sorry -- I think I'm still not getting it.
Quoted 10 lines · G. Branden Robinson
Quoted 2 lines · G. Branden Robinson
[...] you can call .RE [...] as ".RE 2" to say "go back two indentation levels"
Nope, that's wrong. Forget I said that; I think I might now see something I can further improve in the documentation.
You can see I'm still bedeviled by relative insets. :-|
Quoted 7 lines
I tend to never use the argument to .RE; I just call .RE multiple times to balance out my .RS calls, just like parentheses. When I do that, I don't get surprised.
Quoted 1 line
without having to track or remember any indentation measurements.
This part remains true. :)
Currently, I use the idiom
.PP
.in +4n
.EX
<code>
.EE
.in
.PP
or, if we're in indented paragraph territory:
.IP
.in +4n
.EX
<code>
.EE
.in
.IP
This is of course hacky, and of course in order to get it right, I need to know where to use .IP vs .PP.
I'd happily replace this with the use of ".RS 4/.EX/.EE/.RE", but what, if anything do I surround it with? And can I do it in a way that I don't need to care whether I'm currently in an indented zone of text?
I mean, if I use:
.RS
.RS 4
.PP
.EX
int
main(void)
{
printf("Hello world\n");
}.EE
.PP
.RE
.RE
That produces the desired results (4-space indent) if I am currently in an indented zone (.TP or .IP). (But it starts to get even more horribly verbose, in terms of markup, than what I currently use.)
But if I use that same form in an unindented zone, then <code> is massively (12 spaces) indented. Instead, seem to need to say just:
.RS +4
.PP
.EX
int
main(void)
{
printf("Hello world\n");
}.EE
.PP
.RE
What I'd *ideally* like is a solution for indented code blocks that (in order or priority):
1) is not more verbose than the current solution
2) uses more idiomatic mark-up than the current solution
3) uses exactly the same form, regardless of whether I'm currently in an indented region of text.
So far, I don't see such a solution.
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on
Hi Brnaden,
A ping on the below, in case you have some thoughts.
Thanks,
Michael
Quoted 106 lines · Michael Kerrisk (man-pages)
Hi Branden,
Sorry -- I think I'm still not getting it.
Quoted 10 lines · G. Branden Robinson
Quoted 2 lines · G. Branden Robinson
[...] you can call .RE [...] as ".RE 2" to say "go back two indentation levels"
Nope, that's wrong. Forget I said that; I think I might now see something I can further improve in the documentation.
You can see I'm still bedeviled by relative insets. :-|
Quoted 7 lines
I tend to never use the argument to .RE; I just call .RE multiple times to balance out my .RS calls, just like parentheses. When I do that, I don't get surprised.
Quoted 1 line
without having to track or remember any indentation measurements.
This part remains true. :)
Currently, I use the idiom
.PP
.in +4n
.EX
<code>
.EE
.in
.PPor, if we're in indented paragraph territory:
.IP
.in +4n
.EX
<code>
.EE
.in
.IPThis is of course hacky, and of course in order to get it right, I need to know where to use .IP vs .PP.
I'd happily replace this with the use of ".RS 4/.EX/.EE/.RE", but what, if anything do I surround it with? And can I do it in a way that I don't need to care whether I'm currently in an indented zone of text?
I mean, if I use:
.RS
.RS 4
.PP
.EX
int
main(void){ printf("Hello world\n"); }.EE
.PP
.RE
.REThat produces the desired results (4-space indent) if I am currently in an indented zone (.TP or .IP). (But it starts to get even more horribly verbose, in terms of markup, than what I currently use.)
But if I use that same form in an unindented zone, then <code> is massively (12 spaces) indented. Instead, seem to need to say just:
.RS +4
.PP
.EX
int
main(void){ printf("Hello world\n"); }.EE
.PP
.REWhat I'd *ideally* like is a solution for indented code blocks that (in order or priority):
1) is not more verbose than the current solution
2) uses more idiomatic mark-up than the current solution
3) uses exactly the same form, regardless of whether I'm currently in an indented region of text.So far, I don't see such a solution.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH v2 1/1 system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example
In reply to Michael Kerrisk (man-pages)---
Hi Michael,
I added the part about range checking, and used a type with defined limits to show a complete example.
Thanks,
Alex
man7/system_data_types.7 | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+)
man7/system_data_types.7 +62 -0
@@ -629,6 +629,68 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the integer types described in this page don't have +a corresponding length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of an integer type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of a type that doesn't have a length modifier, +an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +When copying from the temporary variable to the actual variable, +the value could overflow. +If POSIX provides lower and upper limits to the type, +the user should check that the value is within those limits, +before actually copying the value. +The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of an integer type that doesn't have a length modifier. +The appropriate conversions from and to +.IR intmax_t , +and the appropriate range checkings, +are used as explained in the notes section above: +.PP +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> + +int +main (void) +{ + static const char *const str = "500000 us in half a second"; + suseconds_t us; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "%jd", &tmp); + + /* Check that the value is within the valid range */ + if (tmp < -1 || tmp > 1000000) + exit(EXIT_FAILURE); + + /* Copy the value to the suseconds_t variable 'us' */ + us = tmp; + + /* Print the value */ + printf("There are %jd us in half a second.\en", (intmax_t) us); + + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Signature · 1 line
2.28.0
Corrections below:
Quoted 37 lines · Alejandro Colomar
Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
Hi Michael,
I added the part about range checking, and used a type with defined limits to show a complete example.
Thanks,
Alex
man7/system_data_types.7 | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+)man7/system_data_types.7 +12
-0@@ -629,6 +629,68 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the integer types described in this page don't have +a corresponding length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of an integer type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t
man7/system_data_types.7 See also: · line 653
Quoted 10 lines
man7/system_data_types.7 +10
-0+by an explicit cast. +To scan into a variable of a type that doesn't have a length modifier, +an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +When copying from the temporary variable to the actual variable, +the value could overflow. +If POSIX provides lower and upper limits to the type,
Actually, I should have said:
If the type has upper and lower limits,
or something like that.
Quoted 44 lines
man7/system_data_types.7 +40
-0+the user should check that the value is within those limits, +before actually copying the value. +The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of an integer type that doesn't have a length modifier. +The appropriate conversions from and to +.IR intmax_t , +and the appropriate range checkings, +are used as explained in the notes section above: +.PP +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> + +int +main (void) +{ + static const char *const str = "500000 us in half a second"; + suseconds_t us; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "%jd", &tmp); + + /* Check that the value is within the valid range */ + if (tmp < -1 || tmp > 1000000) + exit(EXIT_FAILURE); + + /* Copy the value to the suseconds_t variable 'us' */ + us = tmp; + + /* Print the value */ + printf("There are %jd us in half a second.\en", (intmax_t) us); + + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Hello Alex,
Quoted 8 lines · Alejandro Colomar
Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
Hi Michael,
I added the part about range checking, and used a type with defined limits to show a complete example.
Thanks! Still a few coments.
Quoted 20 lines
Thanks,
Alex
man7/system_data_types.7 | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+)man7/system_data_types.7 +4
-0@@ -629,6 +629,68 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the integer types described in this page don't have +a corresponding length modifier for the +.BR printf (3)
man7/system_data_types.7 See also: · line 645
Quoted 10 lines
man7/system_data_types.7 +10
-0+and the +.BR scanf (3) +families of functions. +To print a value of an integer type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of a type that doesn't have a length modifier,
s/a type/an integer type/
man7/system_data_types.7 See also: · line 651
Quoted 6 lines
man7/system_data_types.7 +6
-0+an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +When copying from the temporary variable to the actual variable,
s/actual/destination/
Quoted 21 lines
man7/system_data_types.7 +21
-0+the value could overflow. +If POSIX provides lower and upper limits to the type, +the user should check that the value is within those limits, +before actually copying the value. +The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of an integer type that doesn't have a length modifier. +The appropriate conversions from and to +.IR intmax_t , +and the appropriate range checkings, +are used as explained in the notes section above: +.PP +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> + +int +main (void)
man7/system_data_types.7 See also: · line 682
Quoted 10 lines
man7/system_data_types.7 +10
-0+{ + static const char *const str = "500000 us in half a second"; + suseconds_t us; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "%jd", &tmp); + + /* Check that the value is within the valid range */ + if (tmp < -1 || tmp > 1000000)
I think the first part of the check here should be 'tmp < 0'. (Yes, the defined range for the type must allow -1, but speaking of -1 microseconds is nonsensical, right?
Quoted 4 lines
man7/system_data_types.7 +4
-0+ exit(EXIT_FAILURE); + + /* Copy the value to the suseconds_t variable 'us' */ + us = tmp;
man7/system_data_types.7 See also: · line 696
Quoted 10 lines
man7/system_data_types.7 +7
-0+ + /* Print the value */ + printf("There are %jd us in half a second.\en", (intmax_t) us); + + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH v3 1/1 system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example
---
Hi Michael,
wfix +
I thought that checking between 0 and 1M might create confusion, so I kept that check, and added another one
to differentiate the error code from normal values.
Cheers,
Alex
man7/system_data_types.7 | 73 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+)
man7/system_data_types.7 +73 -0
@@ -629,6 +629,79 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the integer types described in this page don't have +a corresponding length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of an integer type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of an integer type +that doesn't have a length modifier, +an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +When copying from the temporary variable to the destination variable, +the value could overflow. +If POSIX provides lower and upper limits to the type, +the user should check that the value is within those limits, +before actually copying the value. +The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of an integer type that doesn't have a length modifier. +The appropriate conversions from and to +.IR intmax_t , +and the appropriate range checkings, +are used as explained in the notes section above: +.PP +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> + + +int +main (void) +{ + static const char *const str = "500000 us in half a second"; + suseconds_t us; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "%jd", &tmp); + + /* Check that the value is within the valid range of suseconds_t */ + if (tmp < -1 || tmp > 1000000) { + fprintf(stderr, "Scaned value might overflow!\en"); + exit(EXIT_FAILURE); + } + + /* Copy the value to the suseconds_t variable 'us' */ + us = tmp; + + /* Even though suseconds_t can hold the value -1, + it represents an error code */ + if (us < 0) { + fprintf(stderr, "Scanned an error code!\en"); + exit(EXIT_FAILURE); + } + + /* Print the value */ + printf("There are %jd us in half a second.\en", (intmax_t) us); + + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Signature · 1 line
2.28.0
Hi Alex,
Quoted 11 lines · Alejandro Colomar
Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
Hi Michael,
wfix +
I thought that checking between 0 and 1M might create confusion, so I kept that check, and added another one
to differentiate the error code from normal values.
Thanks. I've applied this, and done some light editing. Please let me know if anyting in commit 89c6c2bdd2ea doesn't look okay.
Thanks,
Michael
Quoted 88 lines
man7/system_data_types.7 | 73 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+)man7/system_data_types.7 +73
-0@@ -629,6 +629,79 @@ See also: .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. +.PP +Most of the integer types described in this page don't have +a corresponding length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of an integer type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of an integer type +that doesn't have a length modifier, +an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +When copying from the temporary variable to the destination variable, +the value could overflow. +If POSIX provides lower and upper limits to the type, +the user should check that the value is within those limits, +before actually copying the value. +The example below shows how these conversions should be done. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of an integer type that doesn't have a length modifier. +The appropriate conversions from and to +.IR intmax_t , +and the appropriate range checkings, +are used as explained in the notes section above: +.PP +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> + + +int +main (void) +{ + static const char *const str = "500000 us in half a second"; + suseconds_t us; + intmax_t tmp; + + /* Scan the number from the string into the temporary variable */ + sscanf(str, "%jd", &tmp); + + /* Check that the value is within the valid range of suseconds_t */ + if (tmp < -1 || tmp > 1000000) { + fprintf(stderr, "Scaned value might overflow!\en"); + exit(EXIT_FAILURE); + } + + /* Copy the value to the suseconds_t variable 'us' */ + us = tmp; + + /* Even though suseconds_t can hold the value -1, + it represents an error code */ + if (us < 0) { + fprintf(stderr, "Scanned an error code!\en"); + exit(EXIT_FAILURE); + } + + /* Print the value */ + printf("There are %jd us in half a second.\en", (intmax_t) us); + + exit(EXIT_SUCCESS); +} +.EE .SH SEE ALSO .BR feature_test_macros (7), .BR standards (7)
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Alex,
Thanks. I've applied this, and done some light editing. Please let me know if anyting in commit
89c6c2bdd2eadoesn't look okay.Thanks,
Michael
Hi Michael,
It looks good :)
Thanks,
Alex