Writing Simple School Documents (Groff Articles)

Hello there!
Today, I will be teaching you how to write documents really quickly using tools
that are most likely already on your linux installation.

You are using linux... aren't you?

Anyways, today I will be showing you the Groff tool using examples.
Let's get started.

Headers

Every good document starts with a header! Let's do this now.
Create a file called "article.ms".

Insert the following lines into it using your favorite editor:

.TL
My KKool title
.AU
My Name
.AI
My Institution Name
.NH 1
Some Heading Text
.PP
This is text in a paragraph.

Pretty simple right?

Getting the result

To generate a pdf from this, use the following command:

$ groff -ms -Tpdf article.ms > article.pdf

Now, this might need a bit of explanation.
Groff is the command we are using. It is used to translate text into... well
formatted text.
The -ms flag indicates that we want to use the "ms" macro. This is what allows
groff to understand what .TL, .AU, .AI and .NH mean
(however, .PP is provided by groff.)
The -Tpdf option means that we want to output to be in pdf format.
Last but not least, we specify our input file (article.ms).
Finally, we redirect the output of groff into an actual file.

Creating Headers With Multiple Levels

Try the following:

.NH 1
.NH 1
.NH 2
.NH 2
.NH 2
.NH 3
.NH 3
.NH 3
.NH 3

This should be self explanatory once you see the results. :)

Creating Blocks Of Code

Sometimes, you want to insert text using a monospace font (constant width)
that doesn't get formatted. For this, you can use the following:

.DS
.ft CW
fn my_kkool_function(int a, int b) {
    ...
}
.ft
.DE

Let's see what happens here:
.DS    Creates a block where automatic formatting is disabled.
.ft CW Changes the font to a Constant-Width font.
.ft    Changes the font back to normal.
.DE    Ends the block, re-enabling automatic text formatting.

Writing Mathematical Equations

For this, we will be using a macro package called "eqn".

.EQ
n*(n-1) over 2
.EN

I assume the macro names stands for .EQuation and .ENd
To see the result however, we will need to modify our command and enable our
eqn package. Here is the new command:

$ groff -e -ms -Tpdf article.ms > article.pdf

Now, you should see a (kind of) pretty equation. :)

Inline Mathematical Equations

Now, let's say that you want your equation to show up in the middle of a
sentence. What you can do is set a "delimiter" which you will insert in your
text that will turn on and off the eqn mode. Let's see how that works.

Insert the following all the way at the top of the document:

.EQ
delim $$
.EN

Then, somewhere in your text, do something like this:

blablabla...blabla $2*2=4$ blablabla...

Voilà!

Tables? Tables!!

Tables:

.TS
tab(,),allbox;
ccc.
a,b,c,
d,e,f,
.TE

Wow, what is all of that??
As you might expect by now, .TS and .TE are the start and the end of the table.
Then we have a line that configures the option of the table.
tab(,) means that we are separating each value using a comma ",".
allbox means that we have a box around all the table cells.
Then, the second line defines the column. Here, "c" indicates "centered".
Finally, we have our cell values separated by commas.

To build our pdf file, we will yet again need to add another macro. This time,
it is the -t (for table) macro. Here is our new command:

groff -t -e -ms -Tpdf article.ms > article.pdf

Boom! A pretty table. Flip all the tables!

Including Images

Last but not least, we will learn to include (postscript) images!

.PSPIC your_picture.ps

For the images to show up,
we will need to change the output format to postscript and then convert that
postscript file to a pdf. This is simpler than it sounds.

groff -t -e -ms -Tps article.ms | ps2pdf - article.pdf

Using Special Characters (éèëïù...)

Special characters will have a hard time using the default settings.
Using the a preprocessor called preconv, we can fix this easily.
Simply add -k to our command and we are done! :)

groff -t -e -k -ms -Tpdf article.ms > article.pdf

Going Further

Sadly, the documentation is very sparse and its not obvious to go through it
all.
Here are some man pages to get you started:
-groff(1) the groff command.
-groff(7) the groff format.
-groff_man(7) for writing manual pages.
-groff_ms(7) for writing articles/manuscripts.
-eqn(1) math equations.
-tbl(1) Tables! Tables! Tables!!! GOTTA FLIP!!