\" Generic setup
.DOCTITLE "This is an example document"
.SUBTITLE "For those who care"
.AUTHOR "Oliver Atkinson"
.CHAPTER_STRING "Part"
.MISC "Easily creating good-looking PDFs from vim, or similar terminal text editors." "Using the power of GNU roff (groff) and MOM."
.PRINTSTYLE TYPESET
.DOCTYPE CHAPTER
\" Headers
.RECTO_VERSO
.HEADER_RECTO CENTER "^\E*[$CHAPTER_TITLE]#Pg. \*[PAGE#]^"
.HEADER_VERSO CENTER "^Pg. \*[PAGE#]#\E*[$TITLE]^"
.PAGINATE OFF \" Turn off the normal page numbering (center footnote) because we are putting it in the heading.
\" Headings
.PREFIX_CHAPTER_NUMBER \" Put the chapter number before header numbers
.HEADING_STYLE 1 NUMBER
.HEADING_STYLE 2 NUMBER
.HEADING_STYLE 3 NUMBER
.HEADING_STYLE 4 NUMBER
.HEADING_STYLE 5 NUMBER
.HEADING_STYLE 6 NUMBER
\" Table of contents
.TOC_PADDING 2 \" Space from the end of the ..... to the page number. "....<here>n".
.AUTO_RELOCATE_TOC \" Move the table of contents (TOC) from the end of the document to after the cover pages.
.TOC_HEADER_STRING "Table of Contents"
.PAD_TOC_HEAD_NUMBERS 5 \" Push the headers over to the right 5 spaces to they align with "Part n".
\" misc
.ENDNOTE_MARKER_STYLE NUMBER
.FOOTNOTE_MARKER_STYLE NUMBER
.LINEBREAK_CHAR \[**]*\[**] 1 \" These characters will be output at the end of every chapter.

\" Create custom macro for chapters
.nr RUNNING_CHAPTER_NUM 1
.de NEWCHAPTER 
\" If not the first chapter
. if (\\n[RUNNING_CHAPTER_NUM] > 1) \{\
.  LINEBREAK \" print out symbol signifing the end of a section
.  EL
.  COLLATE \" collect document section together
. \}
. CHAPTER \\n[RUNNING_CHAPTER_NUM]
. CHAPTER_TITLE \\$@
. nr RUNNING_CHAPTER_NUM +1
. START
..

.COVER DOCTITLE SUBTITLE AUTHOR MISC
\" EDIT NOTE: if you wish to use this file as a template. Delete
\" from this comment to the bottom, then write away!
\" Do note that you may want to put .TOC (table of contents) at the end of the document.

.NEWCHAPTER "Why groff?"
.EPIGRAPH
A profound quote
.EPIGRAPH OFF
.PP
.DROPCAP T 2
he idea of groff, is good.
However, the execution is mediocre.
This document, by reading both the source and the final product, are made in hopes that you will be able to sucessfully create a docuemnt using the mom macros.
It will (some what obtusely\c
.FOOTNOTE
As seen right here.
.FOOTNOTE END
) use a wide range of options - such that you can learn as much as possible.
Here are the hurdles we are trying to overcome:
.LIST DIGIT
.ITEM 
What macro set do you want?
.ITEM 
Do you need to use a preprocessor? (For things such as tables)
.ITEM 
Where do you find documentation for your macroset?
MS's is in a mandoc but MOM's is online.
.LIST OFF
Answers:
.LIST DIGIT
.ITEM
We will use the mom macro set.
.ITEM
For most usage, no, but if we need tables then that is something that can be discussed.
.ITEM
The documentation for mom is online (linked throughout this document) and right here!
.LIST OFF
.PP
To start off, I suppose that you should know how to "build" this document.
Open a terminal on nearly and UNIX system and type the following in the same directory as this source file.
(Replacing "this-file" with the acutal file's name.)
.br
.CODE
groff -mom -T pdf this-file.mom > out.pdf
.CODE OFF
.br
.NEWCHAPTER "Now we are styling"
.PP
First thing's first.
We need our basic document outline.
\*[IT]Technically\*[PREV] you can start up a
.CODE
mom
.CODE X
document very quickly.
But I'm not a big fan of the defaults, so I've created this document to adjust those.
Regardless, however you like the superflious aspects of the document, the content will all be set out the same.
.HEADING 1 "Basic macros"
.BLOCKQUOTE
.SPACE
First I will recommend taking this source file, finding the comment "EDIT NOTE" and deleting form there down.
This will give you defaults that look like mine, and setup some fancy extra stuff (mostly documented in the comments.)
.BLOCKQUOTE OFF
.PP
You will first start out with (most likely) a
.CODE
\&.NEWCHAPTER <Title>
.CODE OFF
\&.
This will get the document started, tracking chapter numbers for you.
Therefor, if you end up re-arranging your chapters, or adding another one in the center, you don't have to change the chapter numbers in the document.
Nice!
.PP
After this new chapter you will create a paragraph with
.br
.CODE
\&.PP
.br
<text>
.CODE OFF
.br
This will automatically handle tab-indentation of your paragraphs.
Not indenting the very first of a chapter, but indenting all subsiquent paragraphs.
.HEADING 1 "Headings"
.PP
Use the "heading" macro, we create headings.
.CODE
\&.HEADING <heading level, 1 being biggest> <title>
.CODE OFF
.HEADING 1 "Another top-level heading"
.HEADING 2 "Sub category 1"
.PP
Here we have a sub category.
We use the following code:
.CODE
\&.HEADING 2 "Sub category 1"
.CODE OFF
.HEADING 3 "Very specific heading"
.CODE
\&.HEADING 3 "Very specific heading"
.CODE OFF
.HEADING 2 "Sub category 2"
.PP
As you may have noticed, the chatper number is prefixed onto the heading nubmers.
.HEADING 3 "Specific heading"
.PP
After some more headings, we are now back in a level 3 heading.
.HEADING 1 "Font styles"
.HEADING 2 "Bolid, Italic, etc"
.PP
You will most likely need to use \*[BD]bold\*[PREV], \*[IT]italic\*[PREV], or \*[BDI]bold-italic\*[PREV].
.br
.CODE
\\*[BD]bold\\*[PREV], \\*[IT]italic\\*[PREV], or \\*[BDI]bold-italic\\*[PREV]
.CODE X
.br
.HEADING 2 "Extended styling"
.PP
.DROPCAP T 2
here are also separate ways of doing \*[BOLDER]bold\*[BOLDERX], \*[SLANT]italic\*[SLANTX], or \*[BOLDER]\*[SLANT]bold-italic\*[SLANTX]\*[BOLDERX],
.EXTEND 140
You can also \*[EXT]extend\*[EXTX] a word, but I'm not too sure as to the use-case for this.
These latter ways are considered "hacky" and only to be used if the first option isn't working.
(Because the font doesn't support them.)
.PDF_WWW_LINK https://www.schaffter.ca/mom/momdoc/typesetting.html#modifications-intro "These are documented here."
As you probably noticed, the first character of this paragraph covers 2 lines.
This is called a "dropcap", and is used like this:
.br
.CODE
\&.PP
.br
\&.DROPCAP T 2
.br
here are also separate...
.CODE X
.br
If desired, you can
.PDF_WWW_LINK https://www.schaffter.ca/mom/momdoc/goodies.html#dropcap really
make them fancy.
More you can also make
.UNDERSCORE "a single underscore,"
a\*[SUP]superscript\*[SUPX], or
.SMALLCAPS
Small caps
.SMALLCAPS OFF
\&.
.PP
If you notice in that last paragraph, when we said "\c
.SMALLCAPS
Small caps\c
.SMALLCAPS OFF
", the period was a space away from the word.
This is because by default new lines prepend a space, so that when we have sentinces in our source code, each being
on a differnet line, or just splitting a long sentence like this one across multiple lines, there aren't two words
jammed together.
But, like in the instance we just saw, this isn't \*[IT]always\*[PREV] desirable.
For those cases we use
.CODE
\\c
.CODE X
to prevent the space from appearing.
In the sourcecode for this document the prior sentence looks like this:
.br
.CODE
If you notice in that last paragraph, when we said "\\c
.br
\&.SMALLCAPS
.br
Small caps\\c
.br
\&.SMALLCAPS OFF
.br
", the period was a space away from the word.
.CODE OFF
.br
.HEADING 2 "Breaks"
.PP
There are 2 simple breaks you need to be aware of
.CODE
\&.br
.CODE X
and
.CODE 
\&.bp\c
.CODE X
\&.
These are for break line and break page, respectively.
.bp
.PP
Here I have manually inserted a page break, using the
.CODE
\&.bp
.CODE OFF
macro.
You can think of it as "break page".
.PP
Now that we are on a new page \(em we will see that a heading has appeared!
I have set the defaults here to contain a page number and the current chapter's title.
Then on the opposite side it will have the book's title and the page number.
.bp
.PP
You can see the heading changed on the opposite page.
.HEADING 2 "Colors"
.NEWCOLOR RED #FF0000
.NEWCOLOR GREEN #00FF00
.NEWCOLOR BLUE #0000FF
.PP
I have gone ahead and initalized three colors, \m[red]red\m[black], \m[green]green\m[black], and \m[blue]blue\m[black].
The colors have been initalized by running:
.br
.CODE
\&.NEWCOLOR RED #FF0000
.br
\&.NEWCOLOR GREEN #00FF00
.br
\&.NEWCOLOR BLUE #0000FF
.CODE X
.br
and then by writing the sentence like this:
.br
.CODE
\\m[red]red\\m[black], \\m[green]green\\m[black], and \\m[blue]blue\\m[black].
.CODE OFF
.br
Note that the color "black" is predefined.
.HEADING 1 "Special characters"
.PP
We can also insert special characters such as \[CL]\[SP]\[HE]\[DI] and a great deal more
.PDF_WWW_LINK https://www.man7.org/linux//man-pages/man7/groff_char.7.html "(see here.)"
This is done by entering their escape code.
The above was done by
.CODE
\\[CL]\\[SP]\\[HE]\\[DI]
.CODE X
.HEADING 1 "Footnotes"
.PP
Footnotes are perhaps one of the most\c
.FOOTNOTE
probably
.FOOTNOTE END
 useful things.
.br
.CODE
Something you are writing\\c
.br
\&.FOOTNOTE
.br
then need to make a note on
.br
\&.FOOTNOTE END
.br
then continue your sentence.
.CODE X
.br
.NEWCHAPTER "Other useful links"

.PDF_WWW_LINK https://www.schaffter.ca/mom/pdf/mom-pdf.pdf "Short document on using MOM"

.PDF_WWW_LINK https://www.schaffter.ca/mom/momdoc/toc.html "Offical documentation"

.TOC