Hi Ingo, On Tue, Jun 03, 2025 at 02:49:16PM +0200, Ingo Schwarze wrote: > Hello, > > i'm not sure i'm up to date with this discussion, hence i trimmed the > other mailing lists.
I had fogotten some parts we had discussed too. Thanks for reminding
some.
> I think i uttered my doubts that .SY will ever fly in the past.
Yes, you did.
> While manually specifying large indentations is occasionally useful
> (as just one of several possible examples, consider a tagged list
> where some of the tags are of considerable length and all the bodies
> are very short, for example a single, short word each), *default*
> indentations should never be large - when something results in an
> indentatation of more than about 8n without the author manually
> specifying the large indentation, i consider that a design defect.
> I believe that is one of the many design defects of the .SY macro,
> but the macro has many other defects that are much worse.
Agree.
> I do not consider manually specifying line breaks in a synopsis
> as a desirable feature, neither from the perspective of the author
> nor from the perspective of the reader.
I disagree with this. A great example of where I want to specify the
line breaks is printf(3). Let's show both the Linux manual page and the
OpenBSD page SYNOPSIses side by side:
Linux:
SYNOPSIS
#include <stdio.h>
int printf(const char *restrict format, ...);
int fprintf(FILE *restrict stream,
const char *restrict format, ...);
int dprintf(int fd,
const char *restrict format, ...);
int sprintf(char *restrict str,
const char *restrict format, ...);
int snprintf(size_t size;
char str[restrict size], size_t size,
const char *restrict format, ...);
int vprintf(const char *restrict format, va_list ap);
int vfprintf(FILE *restrict stream,
const char *restrict format, va_list ap);
int vdprintf(int fd,
const char *restrict format, va_list ap);
int vsprintf(char *restrict str,
const char *restrict format, va_list ap);
int vsnprintf(size_t size;
char str[restrict size], size_t size,
const char *restrict format, va_list ap);
OpenBSD:
SYNOPSIS
#include <stdio.h>
int
printf(const char * restrict format, ...);
int
fprintf(FILE *stream, const char * restrict format, ...);
int
sprintf(char * restrict str, const char * restrict format, ...);
int
snprintf(char * restrict str, size_t size, const char * restrict format,
...);
int
asprintf(char ** restrict ret, const char * restrict format, ...);
int
dprintf(int fd, const char * restrict format, ...);
#include <stdarg.h>
#include <stdio.h>
int
vprintf(const char * restrict format, va_list ap);
int
vfprintf(FILE *stream, const char * restrict format, va_list ap);
int
vsprintf(char * restrict str, const char * restrict format, va_list ap);
int
vsnprintf(char * restrict str, size_t size, const char * restrict format,
va_list ap);
int
vasprintf(char ** restrict ret, const char * restrict format, va_list ap);
int
vdprintf(int fd, const char * restrict format, va_list ap);
I consider the Linux manual page to be significantly more useful,
because every 'format' argument is aligned at the start of a line, which
causes the differences between the different APIs to stand out. In this
case, I don't care much about how much indentation I want, but I do want
to set line breaks.
I've been working on changing the entire repository for using SY/YS in
C functions, and I find .br very useful sometimes (quite more that you'd
anticipate).
> From the perspective of the author, writing a synopsis for a
> function library manual page is usually already a relatively
> complicated task (compared to other aspects of manual page writing).
> I don't think adding additional complication, additional aspects
> to consider to that task is wise. The synopsis macros should be
> designed is such a way as to help the author concentrate, during
> the tricky process of writing the synopsis, on the semantic aspects
> on the markup,
I think the presentational detail of breaking the line is important, to
stand out differences between closely related APIs.
> and the author should not be distracted by being
> invited to worry about presentational aspects. For the sake of
> keeping manual page *writing* simple (remember that most manual
> page writers are programmers, not technical writers or typesetting
> professionals) the formatter should make all decisions about
> synopsis formatting in a fully automated way.
I agree that the easier to write a SYNSOPSIS, the better. Which favours
SY/YS over the current BI. With BI, I need to measure and iterate to
get a pleasing page. With SY/YS, it's pretty much automated, and the
only thing I need to care about in the common case is deciding if I want
any line breaks, or just leave it to the formatter.
> From the perspective of a reader, a function library manual page
> having multiple functions with so many arguments that line breaks
> are required is unavoidably a very complicated manual page.
Agree. I tend to split pages when they have too much stuff.
> > Which of course, runs off the right margin. That's the reason I think
> > SY should reduce the indentation if the first line after it would go
> > past the right margin. That's not ideal because non-first arguments
> > would still have the issue, but at least it reduces the number of cases
> > where something like this happens.
>
> Here, another one, and a more serious one, of the many design defects
> of the .SY macro rears its ugly head. It conflates writing section 1
> synopses with section 3 synopses, even though both have very different
> requirements both from a semantic and from a presentational perspective.
>
> In section 1, the first word - the command name - is usually short.
> For that reason, indenting by more than 8n (in violation of the
> general guideline i claimed above) is actually acceptable for
> section 1, because long command names are rare, even those command
> names longer than eight characters are rarely *much* longer,
> and even in those cases where command names are longer than 8n,
> it almost never happens that individual command line arguments are
> long enough that line breaking the synopsis becomes a problem.
>
> In section 3, practical needs are very different. Long function
> names are much more widespread than lang command names, long function
> names are typically much longer than long command names, and the text
> needed to specify a single function argument is typically much longer
> than the text needed to specify a single command line argument,
> so the tradeoffs for line breaking are totally different.
> In section 3, i'd say a sane default indentation is 4n.
> Anything more is of dubious value. Indenting by the length of
> the function name is certainly a terrible idea.
Agree. If SY detects that the first argument doesn't fit in the same
line as the command name, it should use a fixed alignment. That's the
simplest thing to do, and probably the best one too. We could just use
whatever the default indentation is (e.g., IP or RS without argument).
Have a lovley day!
Alex
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
