Hi, On Wed, Nov 06, 2019 at 08:43:18AM +0100, Ingo Schwarze wrote: > Hi Steve, > > Steve Litt wrote on Tue, Nov 05, 2019 at 06:38:52PM -0500: > > On Tue, 5 Nov 2019 18:38:03 +0100 > Ingo Schwarze wrote: > >> Andrew wrote on Sun, Nov 03, 2019 at 12:56:58PM +0000: > > >> [ Pandoc ] > >>> is one of the most useful tools I have ever used. If you are > >>> writing any sort of documentation then I *highly* recommend > >>> checking it out > > >> I strongly oppose that point. > > Admittedly, this was a bit of a diversion because the OP asked about > long, general-purpose texts like books - but all the same, it didn't > want to let the statement "pandoc is recommended for *documentation*" > go unchallenged. In my opinion, most of the points you made in the OpenBSD Journal apply for novels too, and probably even more so for technical books, but I can only judge for the first.
The fact that markdown is not semantic, but essentially presentational, makes it impossible to make formatting changes to a whole semantic category after the fact (e.g. plant name, song title, place name), and impossible to automatically extract that information from the file for various purposes. A fully featured apropos(1) is not required for novels, but it's handy to at least be able to extract a list of names from a specific semantic category, whether to check it's correct, or to display it somewhere else (like an index). It's also handy when translating a work, to compare the original and translated version on specific points, often catching mistakes. But maybe the worst consequence of the markdown pitfalls you mention, is that it cannot provide any kind of syntax error reporting. Markup languages have different needs than programming languages. For example favouring warnings (like you did for mandoc(1)) is generally better than fatal errors (like often LaTeX). But no warnings (like markdown) is worse than both. Some people seem to think syntax highlighting is enough to avoid formatting mistakes, but you cannot depend on it when reading a diff, for example. And anyways, it's still easy to overlook a small formatting error. In my opinion, most of mandoc(1) design philosophy is worth considering for non-documentation long works: diff and grep-friendly simple non-ambiguous syntax, good non-fatal warnings, mostly semantic and fast. All of this seems good for any big project. When designing frundis(1) for novels, it's been my main inspiration, though it falls short on one point: due to the unpredictable requirements of creative works, it's been simpler (unavoidable?) to not make it fully self-contained. At least, new macros can abstract target format specific parts and make it fully-contained per project, which is still better than markdown. For long technical books, I don't think there's still anything approaching what mandoc(1) is for documentation. LaTeX and groff are good, but not semantic enough (making non-PDF exports tricky), have a quite fragile syntax at times and, in my experience, are not great at error reporting - which may be because of current tools instead of the languages themselves, though. Yon
