Hello, onf wrote on Mon, Jan 20, 2025 at 11:13:57PM +0100: > On Mon Jan 20, 2025 at 10:22 PM CET, Ingo Schwarze wrote: >> T. Kurt Bond wrote on Mon, Jan 20, 2025 at 12:57:16PM -0500: >> > Branden said:
>>>> As far as I know, none of pod2man(1), asciidoctor(1), docutils(1), >>>> or pandoc(1) supports a syntax for inlining "raw" man(7)/*roff >>>> source into a document. >> Since this point keeps getting discussed, i'll briefly mention >> that, when designing a markup language, permitting the inclusion >> of chunks written in a different markup language is usually >> terrible language design. >> >> The point of a markup language is to support a variety of output >> formats [...] > That's not always true; HTML is a markup language too, after all, > and it's very tightly integrated with the Web to the point of often > not being easily convertible to other media. Actually, the *intention* of HTML officially still is supporting various output media and seperation of content and presentation - even though that is becoming harder over time due to the proliferation of language features at the edges of the language. You have a point that not all successful (in the sense of widely used) markup languages actually reach this goal. That doesn't mean the goal should be thrown overboard when starting to design a new language. >> Designing your language such that authors can inline a different >> language restricts your new language to essentially support only >> that single output language that can be inlined, so it makes your >> whole new language essentially pointless. [...] > There are many languages which were created to serve as an abstraction > over a language deemed too complicated or unwieldy. I still claim that's almost always a bad idea with extremely few exceptions. At least, the number of layers ought to be minimized, or the ecosystem as a whole become a jungle that is hard to understand for human beings. Typical exceptions where an abstraction layer makes sense include: * a high-level structured or object-oriented programming language as an abstraction over machine assembly code (but then refrain from using macros or code preprocessing on top of that) * a scripting language that allows running code without needing compilation implemented by a compiled program - this is a rare case where two-level astraction makes sense. * A typesetting language like roff(7) or TeX is another axample of a second-tier abstraction. * A macro set like LaTeX or mom(7) or man(7) or mdoc(7) is the extremely rare case where a third-layer abstraction makes sense. Note that in all these examples, the distance between adjacent abstraction layers is huge. Writing code in a compiled languaged feels totally different from writing code in assembly. Writing a shell script feels totally deferent from writing the C code implementing the shell. Writing low-level roff(7) code feels totally different from writing the "C with classes" oode implementing it. heck, even writing a mom(7) document is totally different from writing low-level roff(7) code. All the examples you name are terrible examples that should not exist. > See markdown, which was originally designed to simplify writing stuff > on the web Absolutely a bad idea. Even though HTML has become a bit fat, it's not so hard to learn that an abstraction would be needed on top of it. In addition, the markdown language design is totally botched for at least a dozen reasons - for details, see https://undeadly.org/cgi?action=article&sid=20170304230520 . Besides, writing HTML and writing markdown syntax feel about the same, there is very little distance between the two abstraction level, it's more like putting a bit of lipstick on the pig, but it still remains easy to see it's essentially the same pig, the same level of abstraction. > scdoc, which is something like markdown for man. I only briefly looked at that one at one point in the past, but immediately hated it. You should not write a man(7) code generator when you do not understand how man(7) works. The code quality that scdoc produces was very bad last time i looked, and the language design did not impress me either, though i admit i don't remeber the details, only that it felt poorly thought out. It is possible to write a decent man(7) code generator. The perlpod(1) format and the pod2man(1) program prove that. I'm not saying this toolchain is perfect. For example, it emits a bit much low-level roff code in the preamble because it is over-ambitious with respect to portability - then again, that particular long preamble may look scary, but is mostly harmless in practice. What i am saying is that pod2man(1) is the best man(7) generator i'm aware of, and while neither perfect nor particularly powerful, it's of decent quality. But is such a thing needed for writing manual pages? No, it isn't. Writing perlpod(1) code is not essentially different from writing man(7) or mdoc(7) code, the abstraction is minimal at best. Of course, when competing formats already exist, converters are are often needed. But that doesn't change the argument that designing thin abstractions is evil. Yours, ingo
