Ingo says: > Sure, if your personal task is to write one document with one single output format in mind, even a tool containing that design mistake can prove adequate and helpful in that particular case.
But that is not my personal task: my task is to generate output in multiple formats, which raw inclusions let me do, because I have multiple inclusions, one each for each appropriate output format, and can select among them at appropriate points during processing, thus producing good output for PDF through groff, etc. I choose the appropriate tool for the purpose of the document; sometimes I go straight to troff, sometimes not; sometimes I use other tools in conjunction with troff that result in output in the formats necessary for the purpose of the document. In some cases raw inclusions are helpful; in others they are not. But when they are helpful, they are VERY helpful. On Mon, Jan 20, 2025 at 4:23 PM Ingo Schwarze <schwa...@usta.de> wrote: > Hello, > > 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 - for example, in the case of man(7) and mdoc(7) manual > pages, nicely typeset PDF output with groff(1), good quality HTML 5 > output to publish on the web with mandoc(1), terminal output for > viewing from the command line with either groff(1) or mandoc(1), > conversion to markdown for use on platforms such as github > with mandoc(1), conversion to a semantic search database with the > makewhatis(8) tool contained in the mandoc package, to spoken > language with a screen reader, and so on. > > 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. Taking markdown as an > example, i have discussed this aspect at length eight years ago at > > https://undeadly.org/cgi?action=article&sid=20170304230520 > section "Lack of independence" > > Besides, if you want to extend the capabilities of the roff(7) > language, do not write a roff(7) code generator eating some newly > designed language. Instead, for obvious reasons, extend an existing > macro set, or design a new macro set if you have extremely good > reasons why that is needed. > > > I'll note that this is a standard part of reStructuredText, which pandoc > > supports, and while I have not used it with pandoc's man output, I have > > used with pandoc's ms output, allowing some programs I wrote to generate > > reStructuredText to include tbl tables when the ultimate output format is > > PDF via groff -Tpdf and HTML when the ultimate output is HTML. Other > times > > I use it directly, to tweak things like page breaks. Moreover, pandoc's > > raw_attribute <https://pandoc.org/MANUAL.html#extension-raw_attribute> > > extension allows this in Markdown input. > > Sure, if your personal task is to write one document with one single > output format in mind, even a tool containing that design mistake > can prove adequate and helpful in that particular case. > > Yours, > Ingo > > -- T. Kurt Bond, tkurtb...@gmail.com, https://tkurtbond.github.io, https://consp.org or gemini://consp.org, and https://tkb.tx0.org
