Hi Paul, Paul Swanson wrote on Wed, Jun 19, 2019 at 07:09:39PM +0000:
> Has anyone had any experience with using mandoc for report writing? I doubt that. > I realise it may be a silly / naive question. > > But in recent times I've started using groff (with grefer) to write > academic papers, because it's relatively easy to use for my purposes. Groff is no doubt an excellent tool for that task. Not a big surprise either because Jerry Saltzer originally implemented RUNOFF in 1964 to typeset his thesis - and this family of systems has been used again and again for similar purposes during these 5 1/2 decades. > As such, it got me wondering if mandoc is suitable for such a purpose. Mandoc provides a subset of the functionality of groff plus some additional functionality. No doubt the subset has grown during the decade that mandoc is now in production. But i'd still say the majority of groff typesetting and report writing functionality of groff is not provided by mandoc: - The document format is strictly fixed to "one manual page". You cannot have a title, you cannot have a subtitle, you cannot mention the author(s) and their institution and location at the beginning (only at the end), you cannot have an abstract, you cannot have footnotes, you cannot have images or drawings, you cannot have appendices or indexes, a table of contents only appears in HTML output but not in PDF output, sections always start in the same order: NAME, SYNTAX, DESCRIPTION ... - For an academic paper, typographic output quality is quite important. Mandoc PDF output quality is so much worse than groff PDF output quality that it is probably insufficient for an academic paper and no doubt makes you look sloppy and unprofessional. - You have no control over presentation format. First level titles are always flush left and ALL CAPS, second level title are always slightly indented and bold, there is no way to have third level titles or section numbering, running text is always indented. You get no paragraph adjustment and no hyphenation. Fonts are hardcoded, there are no ligatures, kerning is so simplistic that you could almost call it unsupported. - You cannot use refer(1) or pic(1) or chem(1) or any other add-on macro set with the exception of tbl(7) and eqn(7) - and typographical output quality of tbl(7) and eqn(7) in PDF output is abysmal. On the other hand, the bonus features mandoc provides over groff are irrelevant for your purpose: + Mandoc supports seamless display of your paper by man(1) at the command line, and your paper can be found by system apropos(1). + Mandoc supports converting your paper to man(7) format, just in case your want to support installing it on, say, SUN Solaris 9 machines. + Mandoc supports converting your paper to markdown format, just in case you want to publish in on github, too. + In case your paper is explaining a library function or programming utility, HTML output from mandoc will be semantic, while groff will strip it to presentational HTML of much lower quality - but the semantic macros that mdoc(7) provides might be of little relevance for the subject area you want to write about. + Mandoc helps you check whether the formatting details of your paper adhere to the conventions of OpenBSD (or at your choice, NetBSD) base system manual pages - but not the conventions required by whatever scientific journal you may be targetting. You may be able to use a hammer to split a plank of wood in the middle, but it will be tedious work and the result won't look pretty. For an academic paper, use groff, Heirloom troff (also in the ports tree), or LaTeX (also in the ports tree). Neither the mdoc(7) nor the man(7) macros are adequate. Nowadays, you would probably want to look at the groff_mom(7) macro set. If you feel extremely conservative, you might stick to the groff_mm(7) or groff_ms(7) macro sets, but even that would no longer seem a natural choice. Yours, Ingo
