{"id":9604,"date":"2025-02-18T03:00:00","date_gmt":"2025-02-18T08:00:00","guid":{"rendered":"https:\/\/www.both.org\/?p=9604"},"modified":"2025-02-15T21:04:02","modified_gmt":"2025-02-16T02:04:02","slug":"learning-to-love-groff-ms","status":"publish","type":"post","link":"https:\/\/www.both.org\/?p=9604","title":{"rendered":"Learning to love \u2018groff -ms\u2019"},"content":{"rendered":"
\r\n
\r\n \r\n <\/i>\r\n <\/a>\r\n 1 <\/span>\r\n<\/div><\/div>\n

My journey with markup systems began when I was an undergraduate physics student at university. Until then, I wrote class papers using a desktop word processor for DOS, like WordPerfect. But in 1992, I discovered the Unix lab on campus, and by 1993, I looked for that same kind of computing power on my home computer. That\u2019s how I found and installed my first Linux distribution.<\/p>\n\n\n\n

Unfortunately, Linux didn\u2019t have any desktop word processors. Whenever I asked for help online, others told me to \u201cdo it the Unix way: learn LaTeX or nroff.\u201d I actually learned both; LaTeX made it easy to format equations and other mathematics when writing my physics lab reports, and nroff made it easy to write other class papers that could \u201cget by\u201d with typewriter-like output.<\/p>\n\n\n\n

Linux provides nroff- and troff-compatible formatters as groff<\/strong>, although some Linux distributions install a minimal groff by default, just enough to format manual pages that use it. If you want to explore groff, you may need to install the remaining packages; on Fedora Linux, you can use this:<\/p>\n\n\n\n

$ sudo dnf install 'groff-*'<\/code><\/pre>\n\n\n\n
Most people prepare documents in nroff using a macro package<\/em>, and at first I used Eric Allman\u2019s -me<\/code> macros. These were fairly straightforward, with macros like .sh<\/code> for a numbered section heading, .uh<\/code> for an unnumbered section heading, .pp<\/code> to start a new paragraph, .b<\/code> for bold text, and .i<\/code> for italic or underlined text.<\/p>\n\n\n\n
.sh 1 \"Introduction\"\n.pp\nThis is the first paragraph of a paper.\nYou can format text in\n.b \"bold\"\nor\n.i \"italic\"\ntext.<\/code><\/pre>\n\n\n\n
More recently, I\u2019ve started exploring the -ms<\/code> macro package, and I really like it. Let\u2019s explore how to get started with groff -ms<\/code> to create documents.<\/p>\n\n\n\n
A brief history<\/h2>\n\n\n\n
The -ms<\/code> package has a long history, but I\u2019ll summarize it briefly this way: When Ken Thompson created Unix at Bell Labs, one of the early programs was Joe Ossanna\u2019s roff<\/strong> text formatting system. This was a version of the RUNOFF formatter by Jerry Saltzer, but only supporting the abbreviated versions of RUNOFF\u2019s formatting commands. Later, the Unix team updated roff (as nroff<\/strong> or new roff<\/em>) to support more advanced formatting required by the Legal team, for preparing patent applications. Much later, Bell Labs purchased a Graphics Systems Model C\/A\/T phototypesetter, and Ossanna again updated nroff to become troff<\/strong> for using the typesetter.<\/p>\n\n\n\n
Along the way, Bell Labs collected a set of formatting macros for advanced technical writing. The -ms<\/code> macro package makes it easy to prepare documents that look great anywhere. More recently, I started learning how to use -ms<\/code> to create professional looking PDF content.<\/p>\n\n\n\n
Document structure<\/h2>\n\n\n\n
The -ms<\/code> macros assume a certain document structure, using this order of precedence:<\/p>\n\n\n\n
    \n
  1. If writing a formal document with a cover page, start with .RP<\/code><\/li>\n\n\n\n
  2. Define registers and strings to set custom font, font size, margins, etc.<\/li>\n\n\n\n
  3. Document information, like the title and author<\/li>\n\n\n\n
  4. The body text, using headings and paragraphs<\/li>\n<\/ol>\n\n\n\n
    If you are satisfied with the defaults, your documents can start with the document information, then the body text.<\/p>\n\n\n\n
    Document information<\/h2>\n\n\n\n
    The -ms<\/code> macros provide lots of options to define the document information, but as a beginner, I find I rely on just a few:<\/p>\n\n\n\n
    Start the title with the .TL<\/code> macro, then any lines that follow will be formatted as the title.<\/p>\n\n\n\n
    Define the author using .AU<\/code> and type the author\u2019s name on the lines that follow. To include the author\u2019s institution (such as for an academic paper), use the .AI<\/code> macro, with the institution on the next line.<\/p>\n\n\n\n
    To include a date in the footer of the document, use the .DA<\/code> macro on a line by itself. You can also give this an argument, such as to give a specific date.<\/p>\n\n\n\n
    If your document requires an abstract, use the .AB<\/code> macro to start it, and .AE<\/code> to end the abstract. The abstract, if provided, should be the last item provided before typing the body text.<\/p>\n\n\n\n
    .TL\nThis is the title\n.AU\nJim Hall\n.AI\nMy Institution\n.DA \"today\"\n.AB\nThis is the abstract.\nYou might need to provide an abstract if you are\nwriting a scientific paper intended for academic\npublication.\n.AE<\/code><\/pre>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    Document body<\/h2>\n\n\n\n
    Documents are usually structured using headings and paragraphs. Use .NH<\/code> to start a numbered heading, with the section title on following lines. For unnumbered headings, use the .SH<\/code> macro instead, also with the section title on the next line.<\/p>\n\n\n\n
    Start regular paragraphs with the .PP<\/code> macro on a line by itself. By default, this is a first-line indented paragraph, which is typical for most professional documents. If you need a left-block paragraph instead, use the .LP<\/code> macro.<\/p>\n\n\n\n
    Citations use a different format, where the first line is \u201cex<\/em>dented\u201d (instead of in<\/em>dented) and following lines are indented. To format an \u201cexdented\u201d paragraph, use the .XP<\/code> macro.<\/p>\n\n\n\n
    For different kinds of emphasis within the text, use bold and italic text. The .B<\/code> macro will set all following text in bold, and the .I<\/code> macro will use italic text. For either, you can also provide an argument to format only that text in bold or italic. If you provide following arguments, they will be the \u201cpost\u201d and \u201cpre\u201d text, respectively. This is useful if you need to format a phrase in bold, but don\u2019t want the trailing comma to be bold. Or you might need to format text in italics, but also inside parentheses, but prefer that the parentheses remain in normal text.<\/p>\n\n\n\n
    If you use either .B<\/code> or .I<\/code> on a line by itself, all following text will appear as bold or italic. To revert to normal text (called \u201croman\u201d text) use the .R<\/code> macro.<\/p>\n\n\n\n
    .TL\nThis is the title\n.AU\nJim Hall\n.AI\nMy Institution\n.DA \"today\"\n.AB\nThis is the abstract.\nYou might need to provide an abstract if you are\nwriting a scientific paper intended for academic\npublication.\n.AE\n.NH\nIntroduction\n.LP\nIn most documents, you might use first-line indented\nparagraphs. But if you want your document to look\nreally fancy, consider using a left-block paragraph\nafter section headings and after major displays such\nas images.\n.PP\nAfter that, use first-line indented paragraphs.\nYou can also use a number register to define the\namount of space for the first-line indent.\n.SH\nWorks\nCited\n.XP\nAuthor, A.B. Title of article.\n.I \"Title of periodical\" ,\n.I \"vol num\"\n.I \"issue num\" ), (\npages.\n(here is some extra text to cause the exdented paragraph\nto wrap, so you can see what it looks like)<\/code><\/pre>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    Two-column format<\/h2>\n\n\n\n
    Many scientific journals prefer to publish articles in two-column format. The narrower columns often makes the text easier to read, if the text isn\u2019t too long.<\/p>\n\n\n\n
    To format your document in two-column format, add the .2C<\/code> macro. But remember the document structure that -ms<\/code> expects; the .2C<\/code> macro is considered body text<\/em> formatting, so it should go after the abstract and before your first section heading. Here\u2019s a longer sample that includes some \u201clorem ipsum\u201d placeholder text, so you can see the output in two-column format:<\/p>\n\n\n\n
    .TL\nThis is the title\n.AU\nJim Hall\n.AI\nMy Institution\n.DA \"today\"\n.AB\nThis is the abstract.\nYou might need to provide an abstract if you are\nwriting a scientific paper intended for academic\npublication.\n.AE\n.2C\n.NH\nIntroduction\n\n...\n\n.SH\nWorks\nCited\n.XP\nAuthor, A.B. Title of article.\n.I \"Title of periodical\" ,\n.I \"vol num\"\n.I \"issue num\" ), (\npages.\n(here is some extra text to cause the exdented paragraph\nto wrap, so you can see what it looks like)<\/code><\/pre>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    Writing with groff<\/h2>\n\n\n\n
    While groff is somewhat niche these days, I really enjoy writing with groff. With groff, I can focus on the content<\/em> of what I\u2019m writing, with little distraction. After a while, I find the \u201cdot commands\u201d to format my document become almost natural, or at least very minimal.<\/p>\n\n\n\n
    With groff, you can produce different kinds of output, including HTML for web delivery, PDF for online viewing, and PostScript for printed output. For example, to format a paper using groff -ms<\/code> as a PDF, type:<\/p>\n\n\n\n
    $ groff -ms -Tpdf paper.ms > paper.pdf<\/code><\/pre>\n\n\n\n
    To learn more about formatting with the -ms<\/code> macros, read the groff_ms<\/code>(7) manual page on your system:<\/p>\n\n\n\n
    $ man groff_ms<\/code><\/pre>\n\n\n\n
    This article is adapted from Learning to love \u2018groff -ms\u2019<\/a> by Jim Hall, and is republished with the author’s permission.<\/p>\n","protected":false},"excerpt":{"rendered":"
    1 My journey with markup systems began when I was an undergraduate physics student at university. Until then,<\/p>\n","protected":false},"author":33,"featured_media":4259,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_lmt_disableupdate":"","_lmt_disable":"","footnotes":""},"categories":[5,579],"tags":[147,91,720,718,717,719],"class_list":["post-9604","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-linux","category-writing","tag-fun","tag-linux","tag-ms-macro","tag-nroff","tag-roff","tag-troff"],"modified_by":"David Both","_links":{"self":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/9604","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/users\/33"}],"replies":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=9604"}],"version-history":[{"count":1,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/9604\/revisions"}],"predecessor-version":[{"id":9608,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/9604\/revisions\/9608"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/media\/4259"}],"wp:attachment":[{"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=9604"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=9604"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=9604"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}