On Tue, 5 Nov 2019 18:38:03 +0100 Ingo Schwarze <schwa...@usta.de> wrote:
> Hi, > > 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. I'm not a fan of pandoc either. It's a little too black-boxy for my taste. > There is no need at all to bother > with pandoc when you write documentation. (It may be useful for > other purposes, i have no idea). > > If you write documentation, just use the best format in the first > place. If the project you are documenting allows checking in > documentation in mdoc(7) format, use that. TL/DR SUMMARY: mdoc(7) is cool, but based on an hour or so's research is insufficient for all but the simplest full length books. I've spent the last hour or so looking at man pages mandoc(1) and mdoc(7), and I currently don't see how a non-simple book could be authored in mdoc(7). First of all, I see no method of creating a header hierarchy like <h1>...<h6> or \part ... \subparagraph . I'd suspect it could be done by nesting .Sh lines, but I couldn't see how that could be done. As far as I can tell, mdoc(7) has no way to declare arbitrary styles. If I want a style called "stories", as an author I should be able to use one, and worry about semantic to presentational conversion of the stories style to be something I make later (with CSS or LaTeX or whatever). Almost by definition, if I can't create new semantic styles, I'll need to use or reuse predefined ones, which introduces ambiguity and mixing of semantic and presentational. Kudos for provisions to make a bibliography, and a TOC in HTML output. mdoc(7) supported lists cover a wide variety of presentations, but as far as I can tell you can't make new kinds of lists based on the existing lists. For instance, I might have a list for people with vertical spacing very different from a list for concepts, and I see no way to do that in mdoc(7) without declaring that all people are done with one kind of mdoc(7) list, and all concepts are done with another. Another problem: If I initially do both people and concepts with a certain mdoc(7) list type, and then decide people should look different, I'd have to search out all the people, instead of changing one line of CSS or one line of LaTeX. Based on my hour or so research, I don't understand how mdoc(7) would be a good authoring format for anything but the simplest book length document. If I'm wrong, I might start writing my books in mdoc(7). SteveT Steve Litt November 2019 featured book: Manager's Guide to Technical Troubleshooting Second edition http://www.troubleshooters.com/mgr
