Hello, i'm not sure i'm up to date with this discussion, hence i trimmed the other mailing lists.
I think i uttered my doubts that .SY will ever fly in the past. When an overly simplistic approach to a task of considerable complexity is introduced without fully considering the requirements of the task and when consequently, practical adoption of the new feature doesn't happen for about 15 years, it is not likely that minor tweaks to the design of the ill-begotten feature will suddenly save it more than a decade later. 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. 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. >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, 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. >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. No matter what you do, it will never become easy to understand. Long argument lists are one among the design decisions that tend to be (mildly) discouraged in function library design because they make writing and auditing of source code harder. So the tradeoff is just bad. In a problem subdomain that is already of above-average difficulty, you are offering a presentational feature making writing yet more complicated - and for little benefit because it only becomes relevant in cases that are unavoidably hard to understand either way. Considerable, purely presentational complication for marginal benefit in unusual corner cases that won't become particularly good either way. Just don't. Regarding .br - i agree that .br can be useful in manual pages in rare cases, sometimes in man(7), but it happens even in mdoc(7), more rarely. Yes, .br is among the least harmful low-level roff(7) requests that an author might reach for while writing a manual page. But that should be reserved for unusal cases that were unanticipated by markup language design. Designing the markup macro set in such a way that a need for using low-level presentational roff(7) requests - even relatively innocuous ones like .br - is already baked into the language design amounts to admitting defeat before even finishing the design stage. Alejandro Colomar wrote on Tue, Jun 03, 2025 at 01:06:11PM +0200: > 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. Yours, Ingo
