Looping in a couple of things Branden brought up that I felt compelled to address, after catching up on the list.
On Feb 19, 2026, at 11:28 AM, G. Branden Robinson <[email protected]> wrote: > I find this to be generally true (with honorable exceptions) of software > documentation undertaken by people who regard the avoidance of tools > (like *roff or TeX[1]) for structured document composition as a positive > good. ... > > [1] Or, as I understand it, the expensive, proprietary, and now dead > FrameMaker, which I never encountered in the flesh. FrameMaker is still being sold, although it’s subscription-only. In the early naughts, I dumped it and went to groff for work-related stuff for several years, after Adoobie decided they didn’t care about MacOS anymore. If you want to call a move to subscription-only “dead,” though, I won’t argue. :-D It’s better than MS Weird, but writing Markdown in ed is better than MS Weird. I think Frame is part of AEM (Adoobie Experience Manager) now. People who are looking for structured document composition often turn to XML— mostly DITA but DocBook is still kicking—these days. XML purists would say both *roff and TeX aren’t structured, because you can use primitives to force behavior that XML markup languages can’t support. There’s an echo of that in the -man vs. -mdoc debates here. Technical writing has its trendy formats, much like coders have their trendy languages (perl, Python, Ruby, etc). On Feb 21, 2026, at 3:28 PM, G. Branden Robinson <[email protected]> wrote: > The wide popularity of non-semantic markup languages like Markdown and > reStructured Text hints at a darker possibility: a lot of implementors > suck at documenting their systems with semantic tools because thinking > carefully about the semantics of their systems freezes them up. I did technical writing for over 40 years, and will continue to do so if I can find a job. In that time, I’ve used everything from a roff clone on Idris to DITA-XML on a high- end CCMS. Theoretically, yes, highly-structured and -semantic markup can be useful (for example, picking out terms to generate a glossary), but how often are things like that actually implemented? There was a paper, “There are no unstructured documents,”[1] that discussed software meant to recover structure from a PDF based on the presentation. I call it “implied structure” or “shared context,” because people use visual cues agreed upon over centuries to derive structure. If you depend on shared context, it’s not difficult to move Markdown to DITA, and vice-versa.[2] Nowadays, controversial or not, one can use AI to derive that structure. I fed an LLM a four-page long table of alarm codes from an SCTE spec (PDF format) and had it give it back as a CSV file. One quick awk script later (plus a few edits where the LLM had misplaced quotes in the CSV), I had the framework for documenting those alarms. It boils down to, how much structure is enough? Personally, I think HTML and -mm are pretty close to the sweet spot. You can always use the class attribute in HTML to add more semantics if needed, or modify -mm by adding or changing macros. Metadata can also be important, and there are accepted ways of adding that metadata to Markdown (YAML headers) or HTML (meta elements). The -mm macros support at least some broad metadata (document type, author, etc) as well, and more could be added as needed. — Larry [1] https://web.archive.org/web/20061110082020/http://www.exegenix.com/media/pdf/exegenix_xmleurope2002_paper.pdf <https://web.archive.org/web/20061110082020/http://www.exegenix.com/media/pdf/exegenix_xmleurope2002_paper.pdf> [2] The DITA Open Toolkit (DITA-OT) <https://www.dita-ot.org <https://www.dita-ot.org/>/> supports Markdown, and HTML5 structured in a particular way, as peer formats. They call it “Lightweight DITA” (LwDITA). It supports conversions in both directions.
