Hyphens, minus, and dashes in Debian man pages

Posted Oct 24, 2023 0:43 UTC (Tue) by jkingweb (subscriber, #113039)
In reply to: Hyphens, minus, and dashes in Debian man pages by branden
Parent article: Hyphens, minus, and dashes in Debian man pages

> I'm trying to reach and assist people who care about writing man(7) (and mdoc(7) for that matter) competently. If they don't care about that, I'm wasting my time, and they shouldn't waste theirs telling the world how man(7) _should_ be done.

I am such a person (especially after reading this article), though I'm a complete neophyte. Thus far I've been writing Markdown and converting it using Pandoc, mainly because I had no idea where to begin to learn how to do things properly. And... I still don't. Should I start by reading man(7), or mdoc(7), or something else altogether? There seems to be many schools of thought (as is so common in the free software world), but I'd love an authoritative hand point me in *one* direction, whatever it is.

Hyphens, minus, and dashes in Debian man pages

Posted Oct 24, 2023 3:07 UTC (Tue) by branden (guest, #7029) [Link] (1 responses)

> Thus far I've been writing Markdown and converting it using Pandoc, mainly because I had no idea where to begin to learn how to do things properly. And... I still don't. Should I start by reading man(7), or mdoc(7), or something else altogether?

My recommendation is the groff_man_style(7) page in the groff 1.23.0 release. It attempts to bring the reader from a state of no knowledge about man(7) or roff to a point where they can write a man page. It's not quite a tutorial--it doesn't start with a skeleton page that you fill in, but it covers the basics first and then discusses each group of man(7) macros in approximately the order you're likely to need to use them. So it starts with `TH` and `SH` and their relatives, then covers paragraphing macros, then synopsis macros, then hyperlink macros, and finally font styling macros.

You can start on page 253 of the collected groff man pages PDF. https://www.gnu.org/software/groff/manual/groff-man-pages...

> There seems to be many schools of thought (as is so common in the free software world), but I'd love an authoritative hand point me in *one* direction, whatever it is.

In the course of the past several years I've learned a great deal about the history of *roff and man pages, and I've attempted to reflect that learning in the content of the groff's own man pages.

But even authoritative voices are not infallible, so if you find errors, I'd appreciate hearing about them. (I find that the adjective sits on me uncomfortably, in any case.)

Hyphens, minus, and dashes in Debian man pages

Posted Oct 30, 2023 22:33 UTC (Mon) by jkingweb (subscriber, #113039) [Link]

Thank you very much for the pointer. I found the groff_man_style(7) very well written and an excellent introduction. After spending a couple of days transcribing my manual to groff then mdoc I decided to go with mdoc (despite its doing a poorer job of layout in a couple of places, especially with links—the groff .UR macro yields beautiful output), but I don't know if I would have been able to grasp the basics without first reading groff_man_style(7), so you have my gratitude!