Hi Marc, Marc Chantreux wrote on Wed, Nov 06, 2019 at 08:42:28AM +0100:
> let me ruin your day: are you aware of scdoc? > https://git.sr.ht/~sircmpwn/scdoc Yes, i think i tripped over it before, once. > i really appreciated reading about you opinion. thank you. I think the basic idea is a thoroughly bad one: targetting man(7) as an output language is already a dubious choice. On the one hand, man(7) can be considered an ancient, obsolete language. It was the state of the art from 1979 to about 1990 and has now been obsolete for almost three decades. Admittedly, there are still unusual circumstances where you need it, not listing them here. But in that case, it can and should be written by hand. Yes, it is more difficult than mdoc(7) or perlpod(1) to write, but not all *that* hard, so a wrapper language is not really needed. With the exception of perlpod(1)/pod2man(1), most programs that autogenerate man(7) code produce low-quality output, so usually, using a preprocessor is a bad idea because you get poor manual page formatting. scdoc(1) is not an exception; the output code quality is poor indeed: * stray .P before and after .SH * incorrect usage of plain "-" in NAME line * weird ALL CAPS formatting for .SS * failure to use font macros, using font escapes instead * stray .P inside .RS/.RE * incorrect use of plain "-" for \(em * violation of "new sentence, new line" * missing double space after full stop * EXTREMELY poor formatting of bullet lists, totally failing to use .TP or .IP in nroff output mode, instead resorting to plain .nf * TERRIBLE gratuitions use of .ie n for lists with manual negative \h that doesn't even work reliably in a portable way; while it does work with groff(1), it doesn't with mandoc(1) or other formatters * relies on tbl(7) for tables, but without giving any instructions to the subsequent formatter to run the tbl(1) preprocessor; while that works with mandoc(1), it is not portable and fails by default even with groff(1) * produces UTF-8 characters embedded in man(7) code instead of properly encoding them as documented in groff_char(7) and mandoc_char(7); while that works with mandoc(1), it is not portable and fails by default even with groff(1) There may be more problems with it, this list is just from one very brief glance at the man(7) output generated from the scdoc.5.scd manual page itself. To summarize, there wasn't any need for yet another man(7) autogenerator, perlpod(1) already existed, and while most man(7) autogenerators are bad, this one may even be producing below-average quality. Besides, several of the points i made against Markdown appear to apply to scdoc just as well (or rather, just as badly), in particular context sensitivity/ambiguity, purely presentational markup and lack of semantic markup, lack of language independence... Do not use it. Yours, Ingo
