.TL Syntax Examples .AU tropf .AB Demonstration of possible syntax using groff, sorted by macro package. .AE .DA . .NH 1 Plain .PP Plain groff provides a small base for the language. Though mainly it governs the general look an feel of the source code. .NH 2 Code Structure .PP Newlines have meanings. To create a line purely for source code structure, without it having a meaning for the output use .B "a single . char" "." .CB .cc ~ .PP Some text . . .PP More Text ~cc .CE . .NH 2 Control Sequence .PP Generally all commands begin with a dot. This can be changed using the \fC.cc\fR macro. .CB .cc ~ \fC.cc ~ . now the dot can be used like any other character . commands now begin with a ~ \fC~PP a paragraph . call cc without arguments to reset \fC~cc ~cc .CE . .NH 2 Inline Formatting .PP To switch the font inline, use the sequence .CW "\ef[]" or alternatively .CW "\ef" " if" .CW "" " is only" .B "a single character" "." . With .CW "" being one of these: . .TS nospaces center tab(|); l l lfC l. Code | Result _ R | \fRroman (regular)\fR I | \fIitalics\fR B | \fBbold\fR C | \fCconstant width\fR BI | \f[BI]bold italics\fR CI | \f[CI]constant width italics\fR CB | \f[CB]constant width bold\fR CR | \f[CR]constant width roman\fR CBI | \f[CBI]constant width bold italics\fR .TE . .CB The above table looks like that in the source: [...] CI | \ef[CI]constant width italics CB | \ef[CB]constant width bold CR | \ef[CR]constant width roman [...] .CE .NH 2 Escape Sequences .PP groff provides plenty of special characters via various escape sequences. A complete list can be found on the man page .B "groff_char" "(7)." . .TS nospaces center tab(|); l l l lfC l l. Sequence | Result | Description _ \ee | \e | backslash \e[Fo] | \[Fo] | left guillemet \e[Fc] | \[Fc] | right guillemet \e[fo] | \[fo] | single left-pointing angle \e[fc] | \[fc] | single right-pointing angle \e[em] | \[em] | em-dash \e[en] | \[en] | en-dash \e[pc] | \[pc] | period centered .TE . .NH 1 ms .PP The largest and most influencal macro package. .NH 2 Preamble .PP .I Technically all parts of the Preamble are optional. In practice it should at least contain a title. .CBT .TL This is a title ~CET .PP Any number of authors (including none) can be specified. My convention is to put that .B before the abstract. .CBT .AU tropf .AU another co-author ~CET .PP The abstract should only be a couple of sentences. .CBT .AB This document is on $topic. It gives a general overview and shows an example. .AE ~CET .PP Generally I add the .CW ".DA" macro right after the abstract. It prints the date of document generation on every page. Combined with make only regenerating updated documents, this automatically prints the last edited date for every document. .NOTE That apparently does not work on the html export. . .NH 2 Document Structure .NH 3 Headings .PP Headings are specified by a level, 1 being the highest. They are numbered and added to a TOC automatically. For example this section has the following source for its headings: .CBT .NH 1 ms .NH 2 Preamble .NH 2 Document Structure .NH 3 Headings .NH 3 Paragraphs .NH 2 Footnotes ~CET .PP In theory the .CW .SH macro can create an unnumbered subheading. Don't do that though, the styling of that sucks. . .NH 3 Paragraphs .PP There a multiple paragraph types. The default that almost always should be used is .CW ".PP" "." Instead of complicated text descriptions, below will be some examples. . .PP This paragraph uses .B ".PP" "." .LOREM . .LP This paragraph uses .B ".LP" "." .LOREM . .QP This paragraph uses .B ".QP" "." .LOREM . .XP This paragraph uses .B ".XP" "." .LOREM . .IP This paragraph uses .B ".IP" "." Its speciality is being usable for lists. You can use it directly, though generally rather directly use the macros for lists. .LOREM . .NH 2 Highlighting .PP Text can also be styled using macros provided. This is in general .I "more easy" to type, though it breaks the flow of text in the source. One huge advantage is, that it does not require resetting the font back to roman. .CBT Text can also be styled using macros provided. This is in general .I "more easy" to type, though it breaks the flow of text in the source. One huge advantage is, that it does not require resetting the font back to roman. ~CET . .PP The general way the formatting macros work in the ms package is like so: .CBT . "text" "postfix" "prefix" ~CET .PP Using bold text as an example this would result in: .QP .B "text" "postfix" "prefix" .PP There is no space between the postfix, prefix and the actual text. This is mainly handy for formatting things at the .B "end of sentences" "." .CBT There is no space between the postfix, prefix and the actual text. This is mainly handy for formatting things at the .B "end of sentences" "." ~CET .NOTE .B "This behaviour is different from the man macros." .PP .CW can be any of these: .TS nospaces center tab(|); lfC l lfC l. | Result _ B | \fBbold\fR R | \fRroman (regular)\fR I | \fIitalics\fR CW | \fCconstant width\fR BI | \f[BI]bold italics\fR .TE .NOTE Macros are less expressive than the inline styles. .NH 2 Footnotes .PP Sometimes there is an addition to be made in a text. This can be done using a footnote\**. .FS Well, to be honest, this is just an example. There is nothing important to say. .FE .CBT .PP Sometimes there is an addition to be made in a text. This can be done using a footnote\e**. .FS Well, to be honest, this is just an example. There is nothing important to say. .FE ~CET .NOTE Footnotes don't really work in html and look not good in ascii/utf8. Avoid them. . .NH 1 www .PP The www macro package adds some macros for authoring web pages. .NH 2 URLs .PP The .CW ".URL" macro can be used to create links. It is fairly straight forward, as .URL "https://xkcd.com" "this example link to xkcd" "." .CBT It is fairly straight forward, as .URL "https://xkcd.com" "this example link to xkcd" "." ~CET .PP The general syntax is the following, with the text and postfix parameters being optional. .CBT .URL "URI" "text" "postix" ~CET . .NH 2 Lists .PP Lists should generally be preceded by a paragraph of some sort. .NOTE This seems odd. But the html device .I is odd. . .NH 3 Unordered Lists .PP .ULS .LI Exhibit A .LI Exhibit B .ULE . .CBT .PP .ULS .LI Exhibit A .LI Exhibit B .ULE ~CET . .NH 3 Ordered Lists .PP .OLS .LI Item 1 .LI Item 2 .OLE . .CBT .PP .OLS .LI Item 1 .LI Item 2 .OLE ~CET . .NH 1 tbl .PP Tables are handled by a preprocessor in groff named .B tbl (1). The man page on tbl is a really good explanation, so here is just a template to copy and edit. .TS nospaces center tab(|); lfC rB c lfC cI l. text | right bold | centered? = A | italics | left BC | centered | looooooong text _ Sum | looooooooooooong text | not summed .TE . .CBT \.TS nospaces center tab(|); lfC rB c lfC cI l. text | right bold | centered? = A | italics | left BC | centered | looooooong text _ Sum | looooooooooooong text | not summed \.TE ~CET . .NH 1 Custom .PP Macros which are added by my custom macro package. .NH 2 Code Listings .PP Code Listings can be introduced using two macro pairs. One also changes the control character from .CW . to .CW ~ , while the other leaves them be. .NH 3 CB and CE .CB I can .B "use macros here" .CE . .PP produced by .CBT .CE I can .B "use macros here" .CB ~CET . .NH 3 CBT and CET .CBT This section also .B disables the . control character. Though the ~ ~ft I (tilde) ~ft character still allows macro usage. Some macros like .B (actually now ~B) will produce strange text though: ~B bold ~CET . .PP produced by .CB .cc $ .CBT This section also .B disables the . control character. Though the ~ ~ft I (tilde) ~ft character still allows macro usage. Some macros like .B (actually now ~B) will produce strange text though: ~B bold ~CET $cc .CE . .NOTE Code blocks started by .CW .CBT must be ended with .CW ~CET , because .CW .CBT changed the control character to .CW ~ . .NH 2 Notes .PP Notes can be easily added using the .CW .NOTE macro. It also accepts up to nine arguments to add a short note easily. .NOTE A Note looks like this .NOTE Alternatively the multiline style can be utilised. . .CBT .NOTE A Note looks like this .NOTE Alternatively the multiline style can be utilised. ~CET . .NH 2 Other .PP .ULS .LI The Link color is automatically set to the document default color. .LI The .CW .LOREM macro will insert a couple of words to use for testing. .ULE . .NH 1 See also .PP Get used to read man pages. .ULS .LI .B groff (1): lists good documentation, pay attention to the "See Also" section of the man page. . .LI .B groff (7): general groff language documentation . .LI .B groff_ms (7): ms macro package . .LI .B groff_www (7): www macro package . .LI .B tbl (1): excellent groff table explanantion . .LI .URL "../src/tropf.tmac" "my custom macros" (source) .LI The source of .URL "../src/syntax.groff" "this page" and .URL "../src/" "the other pages" of this website. . .LI .URL "https://www.troff.org/TheGroffFriendsHowto.pdf" "The Groff and Friends HOWTO" . .LI .B fortune (6): you need that .ULE