[Done] The Sauce of
git clone
Log | Files | Refs | README | LICENSE

commit 9b11ca9fd94a485d851bc4249ab4a6082355d1a2
parent 674d1ae6e0751cbfe6360a32deb3d40c2a8dd227
Author: Joël Lupien (Jojolepro) <>
Date:   Thu,  9 Apr 2020 23:18:09 -0400

Add groff blog post

Asrc/blog/2020-04-09_simple_school_documents/index.txt | 184+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 184 insertions(+), 0 deletions(-)

diff --git a/src/blog/2020-04-09_simple_school_documents/index.txt b/src/blog/2020-04-09_simple_school_documents/index.txt @@ -0,0 +1,184 @@ +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 "". + +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.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 ( +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.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.pdf + +Boom! A pretty table. Flip all the tables! + +Including Images +-------------------------------------------------------------------------------- + +Last but not least, we will learn to include (postscript) images! + +.PSPIC + +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 | 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.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!!