On Tue, Jun 11, 2024 at 07:52:30AM GMT, G. Branden Robinson wrote: > Hi Alex,
Hi Branden, > At 2024-06-10T21:24:54+0200, Alejandro Colomar wrote: > > Hi Branden, > > > > Is it correct to nest EX/EE within nf/fi? > > It's harmless. "Correct" is a question of taste and attempts at > portability to legacy systems. > > > $ cat nfi.man > > .TH EXE 7 2024-06-10 alx > > .SH Name > > nf \- EX > > .SH SYNOPSIS > > .nf > > .B #include <foo.h> > > .P > > .EX > > I find myself wondering why you're postponing the change of typeface to > Courier on typesetters here. > > > struct { > > int a; > > int b; > > }; > > .EE > > ...and leaving it early. > > > .P > > .B #include <bar.h> > > .P > > .B #define BAR \[dq]bar\[dq] > > .fi > > I think the foregoing would be off-putting with family changes in it. > I've also never seen this idiom of setting the preprocessor directives > in roman used anywhere else in man pages. It's not roman; it's bold. Did you mean proportional? Michael liked proportional typeface for everything in the synopsis, and so I'm following his tradition. I'm only using EX/EE for structures, for alignment reasons. The actual synopsis that I'm formatting is: SYNOPSIS #include <linux/fs.h> /* Definition of PAGE* and PM_* constants */ #include <sys/ioctl.h> int ioctl(int pagemap_fd, PAGEMAP_SCAN, struct pm_scan_arg *arg); #include <linux/fs.h> struct pm_scan_arg { __u64 size; __u64 flags; __u64 start; __u64 end; __u64 walk_end; __u64 vec; __u64 vec_len; __u64 max_pages; __u64 category_inverted; __u64 category_mask; __u64 category_anyof_mask; __u64 return_mask; }; struct page_region { __u64 start; __u64 end; __u64 categories; }; where only the structures would be EX/EE. > > I'd structure what you have like this: > > .nf > .EX > ... > .EE > .fi In this case, nf/fi is actually redundant, no? Isn't EX/EE a strict superset of nf/fi? I think of it as being nf/fi + monospace. > > Or should I terminate the nf/fi block before entering EX/EE? I ask > > because mandoc(1) is bugging me. groff(1) seems to do the right thing > > --mandoc(1) also seems to do the right thing; it just complains--. > > I'll let Ingo speak to that. > > I've advised the ncurses project to use both `nf`+`EX` and `fi`+`EE` to > accommodate systems that don't implement the Ninth Edition Unix/groff > `EX`/`EE` extension to man(7). By doing it, the example will format > comprehensibly even if it remains in the Times font on typesetters. Ahh, now I understad your rationale: a fallback in case EX/EE doesn't exist. I'll keep using just EX/EE for meaning EX/EE, and not workaround its lack. > Another approach would be to define a page-local copy of `EX` and `EE`, > but not everyone finds that solution sanguine. Nah, but those interested in systems that lack it could maybe press those systems to add a system-wide definition of those, which would be cheaper and better. > In the Linux man-pages project, I would not bother with this doubling up > at all. In practical scenarios, everything that renders a Linux man > page is going to support `EX` and `EE`.[1] Even Solaris 11 can handle > these macros. Yup. > Regards, > Branden > > [1] groff_man(7): > > .EX > .EE Begin and end example. After .EX, filling is disabled and a > constant‐width (monospaced) font is selected. Calling .EE > enables filling and restores the previous font. > > .EX and .EE are extensions introduced in Ninth Edition Unix. > Documenter’s Workbench, Heirloom Doctools, and Plan 9 > troffs, and mandoc (since 1.12.2) also support them. > Solaris troff does not. See subsection “Use of extensions” > in groff_man_style(7). > > [I do not contradict myself. Solaris troff is Solaris's own derivation > of AT&T troff. It remains in deployment on Solaris 10. Solaris 11 uses > GNU troff (albeit a _really old_ version, which nevertheless supports > `EX` and `EE` man(7) macros).] Have a lovely day! Alex -- <https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature