Hi, G. Branden Robinson wrote on Mon, Apr 24, 2017 at 09:22:25PM -0400: > At 2017-04-24T18:29:57+0200, Ingo Schwarze wrote: >> G. Branden Robinson wrote on Mon, Apr 24, 2017 at 11:41:22AM -0400:
>>> to the more readable (and, I submit, more writable-by-the-novice): >>> >>> .TP >>> .B \-scale \c >>> .IR xfac [, yfac ] >>> Multiply the horizontal and vertical window size by >> YIKES, that sounds like an absolutely terrible idea! > My example, or the method I proposed to achieve it? Both, because both only make sense together. If you don't change the definition of the .TP macro, you cannot use .TP headers containing two macro lines. If you don't want two-line .TP headers, there is no point in changing the syntax of the .TP macro. >> The \c escape sequence is a horrible hack that should never >> be used by end users and should be avoided, if possible, >> even in the implementation of macro sets. > In that case we groff fans have some sweeping around our own door to do, > first and foremost with the (arguably) two most excellent macro packages > we have: Sure, i admit roff is not an easy language, so the implementation of roff macros is often not pretty. Given that Werner wrote much of the groff_mdoc(7) implementation, and he really knows what he is doing, i suspect that most uses of \c could not be avoided. While mdoc(7) is easy to use, the implementaion is not trivial at all; in particular the modern groff implementation is quite a refined thing, much more so than Cynthia's original 4.4BSD implementation, which was much simpler. > I'm happy to examine the impact this change would have on Heirloom > troff. First I'd like to get some feedback on my specific objective. It does seems likely that there is some way to harmonize Heirloom with what gets done in groff. But i do doubt the basic direction in this specific respect. > There are only two living implementations of *roff in the world, right? Well, and the partial one in mandoc, but mandoc follows groff in roff matters. > If \c is documented badly and/or under-specified, let's determine its > precise semantics and document them clearly. I do suspect there is room for improvement, or at least clarification, in the \c specification, so working on that likely makes sense. But please, regard that as a work to help macro implementors, **not** end users! >> There is little you can do to make writing legacy man(7) code >> easier for the novice. > I don't agree. Or perhaps more precisely, I haven't yet given up hope. Well, as long as one doesn't make matters worse, keeping up hope is not a sin. :-) >> The problem is that it always requires mixing two different language >> levels: man(7) macros and low-level roff requests and escapes. > "Always requires" is much too strong. Lots of manpages are written in a > very small subset of the language. Small subsets, yes. The roff language is indeed quite large, and man(7) manual pages typically only need a fraction of it. But almost every man(7) manual page requires *some* low-level roff requests. > In my experience, one can write an attractive manpage almost without > ever restoring to straight requests. And yet you suggest that authors should use the \c escape sequence, which quite definitely is a very low-level roff feature and not an element of the man(7) language at all. In the example you bring up, there is indeed no viable alternative to using \f font escapes. You propose to trade the \f for \c. I say \c is much worse than \f. The syntax and semantics of \f is relatively easy to understand, and people writing man(7) are used to it, while \c is quite arcane. > (People are often ignorant of the an-ext macros, which are so > liberally licensed they can be used anywhere.) I admit that the en-ext macros minimally improve semantic capabilities of the man(7) language, but by so little that man(7) remains an almost exclusively presentational language even with man-ext. For that reason, i deem that using man-ext does more damage than good: It doesn't substantially improve the language, but it does cause compat grief on old systems, which is exactly where the legacy man(7) language is still needed. Bad tradeoff... > I entirely agree with the virtues of semantic of "presentation"-based > markup. However, this could be mitigated by encouraging a consistent > style in groff_man(7) itself. Some coordination with Michael Kerrisk et > al. of the man-pages project would be valuable as well; I think almost > all of the advice in man-pages(7) of that package is very sound. I mostly agree, with very few reservations. Their section headers are gratuitiously different from what groff recommends (in groff_mdoc(7)) and are out of order. Some should better not be used (CONFIGURATION, OPTIONS, ATTRIBUTES, NOTES) and some have unusual titles (EXAMPLE instead of EXAMPLES, CONFORMING TO instead of STANDARDS, VERSIONS instead of HISTORY). AUTHORS should be encouraged rather than discouraged. Besides, i'd recommend constant-width/typewriter font for special macros and errno names rather than bold, and i see no need to make references to other manual pages bold, the section number in parentheses is obvious enough. I would also disagree with part of the advice given below "Example programs", but all of the above is minor. The general direction of man-pages(7) is very useful. >> Writing mdoc(7) is much easier for the novice because it's semantic >> and because it does not require mixing in low-level roff features. > And yet, why have so few people outside of the BSD community adopted it? Frankly, i'm not sure. Illumos has, for example; so of the free operating systems, it's mostly GNU that doesn't use it. One reason could likely be that GNU used to use texinfo(1), but that is being abandoned now. > It's a great macro package and I admire it. But USENIX and BSD built > it, and "they" didn't come. > > People keeep writing in man(7). Let's do what we can to help them write > it better. No real objection to that, if it can be done, but little hope here, except maybe for style recommendations, and man-pages(7) clearly is already quite good at that. > Ideally, I'd like to make some enhancements to man and its documentation > that encourage people to make the leap to mdoc, _especially_ those > people who are enlightened enough to see the sinfulness of > presentation-based, rather than semantic, markup. We should make it > obvious to them that the groff people aren't fools, either, and want to > help them make that jump. But for those who don't, here's man with some > semantic training wheels to file the rougher edges off. Sounds good to me. > People are already writing it wrong--a lot. That is certainly true. I see it in our ports tree. Average quality of hand-written third party man(7) - unless from Kerrisk, of course - is usually below average quality of hand-written mdoc(7). Usually, the least problematic man(7) code you find in the wild is pod2man(1) output. >> The only remaining asset of man(7) is portability, and even that >> is becoming less and less of an argument for using it given the >> wide availablity of both mdoc(7) itself and the mandoc -Tman >> mdoc(7)-to-man(7) converter. > Of course what we need is a converter that goes in the other direction; I have very little hope for that. The best we can hope for would be a tool to convert from man(7) to mdoc(7), doing some guessing of the required markup, but requiring considerable manual postprocessing. I know that a full converter is not a realistic goal because i am maintaining pod2mdoc(1), which is about the same difficulty, and i used it to convert the complete corpus of OpenSSL manuals, so i know quite well which amout of postprocessing is required, and which problems you face when trying to improve the automatic guessing. >> If, by fiddling with man(7) syntax, you harm man(7) portability, then >> you really throw its last remaining asset overboard. > I'd like to see what we can achieve by fiddling with it _without_ > harming its portability. Sure, but your proposed change from .it to .itc together with the changed .TP idiom you propose very seriously breaks portability. If people would start using that, their manuals would severly misformat on old systems. And legacy systems that no longer get properly updated and maintained is exactly where man(7) matters most nowadays. Yours, Ingo