[PATCH v3] open_how.2type: ffix

[PATCH v3] open_how.2type: ffix

[Alejandro Colomar]

Format structures with tbl(1) to improve alignment in proportional-width font text.

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

Hi Branden,

I feel this v3 is good enough to propose it as an actual patch to the list.

v3:

- Use .nf/.fi for comments, but not for types and member names.
- Specify 2 spaces as the distance between types and member names,
  and between member names and the comments.
- Disallow hyphenating some identifier, to avoid confusion.

Cheers,

Alex

 man2type/open_how.2type | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/man2type/open_how.2type b/man2type/open_how.2type
index e058c08dc..01446a56b 100644
--- a/man2type/open_how.2type
+++ b/man2type/open_how.2type
@@ -13,9 +13,30 @@ Linux kernel headers
 .B #include <linux/openat2.h>
 .PP
 .B struct open_how {
-.BR "    u64  flags;" "    /* " O_ "* flags */"
-.BR "    u64  mode;" "     /* Mode for " O_ { CREAT , TMPFILE "} */"
-.BR "    u64  resolve;" "  /* " RESOLVE_ "* flags */"
+.PD 0
+.TS
+l lB2 lB2 l1 lX.
+\&	u64	flags;	/*	T{
+.fi
+.BR O_ *
+flags */
+.nf
+T}
+\&	u64	mode;	/*	T{
+.fi
+Mode for
+.BR \%O_ { CREAT , TMPFILE }
+*/
+.nf
+T}
+\&	u64	resolve;	/*	T{
+.fi
+.BR RESOLVE_ *
+flags */
+.nf
+T}
+.TE
+.PD
     /* ... */
 .B };
 .fi
-- 
2.36.1

[PATCH v4] open_how.2type: ffix

[Alejandro Colomar]

Format structures with tbl(1) to improve alignment in
proportional-width font text.

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Heinz-Jürgen Oertel <hj.oertel@t-online.de>
Cc: Ralph Corderoy <ralph@inputplus.co.uk>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2type/open_how.2type | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/man2type/open_how.2type b/man2type/open_how.2type
index 570bc9b22..16f289820 100644
--- a/man2type/open_how.2type
+++ b/man2type/open_how.2type
@@ -13,9 +13,26 @@ Linux kernel headers
 .B #include <linux/openat2.h>
 .PP
 .B struct open_how {
-.BR "    u64  flags;" "    /* " O_ "* flags */"
-.BR "    u64  mode;" "     /* Mode for " O_ { CREAT , TMPFILE "} */"
-.BR "    u64  resolve;" "  /* " RESOLVE_ "* flags */"
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+u64	flags;	/*	T{
+.BR O_ *
+flags */
+T}
+u64	mode;	/*	T{
+Mode for
+.BR \%O_ { CREAT , TMPFILE }
+*/
+T}
+u64	resolve;	/*	T{
+.BR RESOLVE_ *
+flags */
+T}
+.TE
+.RE
+.nf
     /* ... */
 .B };
 .fi
-- 
2.36.1

[PATCH v5 1/2] open_how.2type: ffix

[Alejandro Colomar]

Format structures with tbl(1) to improve alignment in
proportional-width font text.

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Heinz-Jürgen Oertel <hj.oertel@t-online.de>
Cc: Ralph Corderoy <ralph@inputplus.co.uk>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2type/open_how.2type | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/man2type/open_how.2type b/man2type/open_how.2type
index 570bc9b22..847f33f95 100644
--- a/man2type/open_how.2type
+++ b/man2type/open_how.2type
@@ -13,10 +13,27 @@ Linux kernel headers
 .B #include <linux/openat2.h>
 .PP
 .B struct open_how {
-.BR "    u64  flags;" "    /* " O_ "* flags */"
-.BR "    u64  mode;" "     /* Mode for " O_ { CREAT , TMPFILE "} */"
-.BR "    u64  resolve;" "  /* " RESOLVE_ "* flags */"
-    /* ... */
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+u64	flags;	/*	T{
+.BR O_ *
+flags */
+T}
+u64	mode;	/*	T{
+Mode for
+.BR \%O_ { CREAT , TMPFILE }
+*/
+T}
+u64	resolve;	/*	T{
+.BR RESOLVE_ *
+flags */
+T}
+.TE
+.nf
+/* ... */
+.RE
 .B };
 .fi
 .SH DESCRIPTION
-- 
2.36.1

[PATCH v5 2/2] sockaddr.3type: ffix

[Alejandro Colomar]

Format structures with tbl(1) to improve alignment in
proportional-width font text.

I also reordered the types in the SYNOPSIS, to be consistent with
C syntax.

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Heinz-Jürgen Oertel <hj.oertel@t-online.de>
Cc: Ralph Corderoy <ralph@inputplus.co.uk>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

This page clearly shows that using tabs would be hard.

Although having different alignment for every structure doesn't convince me...


 man3type/sockaddr.3type | 127 ++++++++++++++++++++++++++++++++--------
 1 file changed, 102 insertions(+), 25 deletions(-)

diff --git a/man3type/sockaddr.3type b/man3type/sockaddr.3type
index 9367158e1..9c7a5afff 100644
--- a/man3type/sockaddr.3type
+++ b/man3type/sockaddr.3type
@@ -16,55 +16,132 @@ Standard C library
 .nf
 .B #include <sys/socket.h>
 .PP
+.BR typedef " /* ... */  " socklen_t;
+.BR typedef " /* ... */  " sa_family_t;
+.PP
 .B struct sockaddr {
-.BR "    sa_family_t     sa_family;" "      /* Address family */"
-.BR "    char            sa_data[];" "      /* Socket address */"
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+sa_family_t	sa_family;	/*	T{
+Address family */
+T}
+char	sa_data[];	/*	T{
+Socket address */
+T}
+.TE
+.RE
+.nf
 .B };
 .PP
 .B struct sockaddr_storage {
-.BR "    sa_family_t     ss_family;" "      /* Address family */"
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+sa_family_t	ss_family;	/*	T{
+Address family */
+T}
+.TE
+.RE
+.nf
 .B };
 .PP
-.BR typedef " /* ... */ " socklen_t;
-.BR typedef " /* ... */ " sa_family_t;
-.PP
 .fi
 .SS Internet domain sockets
 .nf
 .B #include <netinet/in.h>
 .PP
-.B struct sockaddr_in {
-.BR "    sa_family_t     sin_family;" "     /* " AF_INET " */"
-.BR "    in_port_t       sin_port;" "       /* Port number */"
-.BR "    struct in_addr  sin_addr;" "       /* IPv4 address */"
-.B };
-.PP
-.B struct sockaddr_in6 {
-.BR "    sa_family_t     sin6_family;" "    /* " AF_INET6 " */"
-.BR "    in_port_t       sin6_port;" "      /* Port number */"
-.BR "    uint32_t        sin6_flowinfo;" "  /* IPv6 flow info */"
-.BR "    struct in6_addr sin6_addr;" "      /* IPv6 address */"
-.BR "    uint32_t        sin6_scope_id;" "  /* Set of interfaces for a scope */"
-.B };
+.B "typedef uint32_t  in_addr_t;"
+.B "typedef uint16_t  in_port_t;"
 .PP
 .B struct in_addr {
-.B "    in_addr_t s_addr;"
+.fi
+.RS 4
+.TS
+lB2 lB.
+in_addr_t	s_addr;
+.TE
+.RE
+.nf
 .B };
 .PP
 .B struct in6_addr {
-.B "    uint8_t   s6_addr[16];"
+.fi
+.RS 4
+.TS
+lB2 lB.
+uint8_t	s6_addr[16];
+.TE
+.RE
+.nf
 .B };
 .PP
-.B typedef uint32_t in_addr_t;
-.B typedef uint16_t in_port_t;
+.B struct sockaddr_in {
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+sa_family_t	sin_family;	/*	T{
+.B AF_INET
+*/
+T}
+in_port_t	sin_port;	/*	T{
+Port number */
+T}
+struct in_addr	sin_addr;	/*	T{
+IPv4 address */
+T}
+.TE
+.RE
+.nf
+.B };
+.PP
+.B struct sockaddr_in6 {
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+sa_family_t	sin6_family;	/*	T{
+.B AF_INET6
+*/
+T}
+in_port_t	sin6_port;	/*	T{
+Port number */
+T}
+uint32_t	sin6_flowinfo;	/*	T{
+IPv6 flow info */
+T}
+struct in6_addr	sin6_addr;	/*	T{
+IPv6 address */
+T}
+uint32_t	sin6_scope_id;	/*	T{
+Set of interfaces for a scope */
+T}
+.TE
+.RE
+.nf
+.B };
 .fi
 .SS UNIX domain sockets
 .nf
 .B #include <sys/un.h>
 .PP
 .B struct sockaddr_un {
-.BR "    sa_family_t     sun_family;" "     /* Address family */"
-.BR "    char            sun_path[];" "     /* Socket pathname */"
+.fi
+.RS 4
+.TS
+lB2 lB2 l1 lX.
+sa_family_t	sun_family;	/*	T{
+Address family */
+T}
+char	sun_path[];	/*	T{
+Socket pathname */
+T}
+.TE
+.RE
+.nf
 .B };
 .fi
 .SH DESCRIPTION
-- 
2.36.1

Re: [PATCH v5 2/2] sockaddr.3type: ffix

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2798 bytes --]

[replying just to Alex and the lists]

Hi Alex,

At 2022-07-30T01:01:09+0200, Alejandro Colomar wrote:
> Format structures with tbl(1) to improve alignment in
> proportional-width font text.
> 
> I also reordered the types in the SYNOPSIS, to be consistent with
> C syntax.
> 
> Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Cc: Heinz-Jürgen Oertel <hj.oertel@t-online.de>
> Cc: Ralph Corderoy <ralph@inputplus.co.uk>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> 
> This page clearly shows that using tabs would be hard.
> 
> Although having different alignment for every structure doesn't
> convince me...

You can resolve that.  Simply choose column widths that are large enough
for the widest data types and identifiers appearing in the page, and use
the `w` modifier in each table to impose that width on the relevant
columns.

At a glace, these look like plausible candidates.

> -.BR "    struct in6_addr sin6_addr;" "      /* IPv6 address */"
> -.BR "    uint32_t        sin6_scope_id;" "  /* Set of interfaces for a scope */"

"struct in6_addr" is 15 characters wide; in typographer-speak, call that
15 ens, and in roff(7) lands "15n".  "sin6_scope_id" is 13n.

So your table formats for this page would look like this.

lBW(15n)2 lBW(13n)2 l1 lX.

These explicit measurements are not guaranteed to be perfect; they may
leave excess space or even be too small in the unlikely event you have
to deal with data types or identifiers that look like "MWMWMWMWMWM".

On the bright side I can't think of how they could go wrong in
terminals.  And you can, of course, spend as much time time as you care
to tuning them for typesetting devices.

But these widths will have to be manually maintained, and in multiple
places at that.  (Of course, this only applies if a page documents more
than one struct or union type _and_ uses more than one table _and_ you
want the columns to align across those tables.)

Like I said on the groff list, tbl(1) is heavy machinery.  And beautiful
typography spreads its sublime wings when proportional typefaces get
involved.  There are good roffish tricks for avoiding some of these
problems--they involve using the `\w` escape sequence to measure things,
and storing the results in registers--but unfortunately they are
unlikely to work well, or at all, with mandoc(1) or other non-roff
formatters.

But, people thought they weren't giving up anything important when, 20
years ago, they decided they wanted to wanted to parse man pages into
XML or HTML without having to implement a roff formatter.  man(7) pages
were "almost" simple enough...

So if you want me to resurrect that tab stop-computing macro idea, let
me know.  ;-)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]