From aa5e20cacb9010fee25c5e9234631518db799af7 Mon Sep 17 00:00:00 2001
From: Karchnu <karchnu@karchnu.fr>
Date: Fri, 29 Oct 2021 04:24:15 +0200
Subject: [PATCH] Add introduction.

---
 Makefile  |   2 +-
 header.ms |  14 +--
 macros.ms | 281 +++++++++++++++++++++++++++++-------------------------
 main.ms   |  99 +++++++++++++++++--
 4 files changed, 247 insertions(+), 149 deletions(-)

diff --git a/Makefile b/Makefile
index 8e6ef23..ae7405d 100644
--- a/Makefile
+++ b/Makefile
@@ -5,4 +5,4 @@ export ODIR SRC
 include Makefile.in
 
 upload:
-	scp $(SRC).pdf tacos:/var/www/htdocs/t.karchnu.fr/doc/
+	scp $(ODIR)/$(SRC).pdf tacos:/var/www/htdocs/t.karchnu.fr/doc/grofftut.pdf
diff --git a/header.ms b/header.ms
index 27bf733..9cebfbe 100644
--- a/header.ms
+++ b/header.ms
@@ -5,16 +5,12 @@ Philippe Pittoli
 .  \" In case you don't want an abstract:
 .  \" .AB no
 .AB
-This document provides a few hints on how to start writing documentation with
-.B troff .
-It represents your first steps with the tool, and the simplest commands are presented along with some personal macros to help you getting started.
-.SHINE "Take what you need from this document."
-
+This document is a brief demonstration of what
+.B troff
+can do.
+The simplest commands are presented along with some personal macros.
+.SHINE "Take what you need."
 The source code of this document contains many useful comments.
-.br
-Also, it is customary in old tools such as troff to read the source code and hack your way.
-Once you're familiar with the basics, if you need something that isn't in the official troff documentation, don't hesitate to read provided macros (mines, but also ms macros as well, for instance).
-You'll quickly learn a lot.
 .LP
 Lastly compiled the
 .SHINE \n(dy/\n(mo/2021 \" is \n(yr broken?
diff --git a/macros.ms b/macros.ms
index eab81e7..384c30f 100644
--- a/macros.ms
+++ b/macros.ms
@@ -2,12 +2,28 @@
 .nr PO 0.5i   \" page offset default 1i
 .nr LL 7.5i   \" line length default 6i
 .nr FM 0.5i   \" page foot margin default 1i
+.nr DI 0
+.nr FF 3   \" footnotes' type: numbered, with point, indented
+.
+.
+.nr LIST_NUMBER 0
+.
 .R1
 no-label-in-reference
 accumulate
 .R2
-.nr DI 0
-.nr FF 3   \" footnotes' type: numbered, with point, indented
+.
+. \" COLORS
+.defcolor darkgreen rgb 0.1 0.5 0.2
+.defcolor darkblue  rgb 0.3 0.3 0.7
+.defcolor darkred   rgb 0.7 0.3 0.3
+.
+.defcolor citation       rgb 0.4 0.4 0.4
+.defcolor citationbar    rgb 0.3 0.3 0.7
+.defcolor explanation    rgb 0.7 0.4 0.4
+.defcolor explanationbar rgb 0.8 0.3 0.3
+.
+.
 .de BELLOWEXPLANATION1
 .sp 0.5
 .ps 7     \" point size (~= font size)
@@ -18,11 +34,125 @@ accumulate
 .ps 9
 .vs 11p
 ..
-.defcolor darkgreen rgb 0.1 0.5 0.2
-.defcolor darkblue  rgb 0.3 0.3 0.7
-.defcolor darkred   rgb 0.7 0.3 0.3
-.de CONSTRUCTOR
-.gcolor darkred
+.
+.de BULLET         \" Bullet points
+.IP \(bu 2
+..
+.de ENDBULLET
+.in -2   \" indent
+..
+.
+.de ENUM           \" Numbered list
+.nr LIST_NUMBER +1
+.IP \\n[LIST_NUMBER] 2
+..
+.de ENDENUM
+.nr LIST_NUMBER 0
+.in -2   \" indent
+..
+.
+.de b1     \" Begin code box
+.B1
+.sp 0.2
+.ft CW
+..
+.de b2     \" End code box
+.sp 0.5
+.B2
+.ft
+..
+.
+.de CITATION1
+.KS          \" start a keep
+.ft I        \" citation in italics
+.mk C        \" set a marker for line drawing
+.in +1       \" indent a bit
+.gcolor citation
+..
+.de CITATION2
+.mk D        \" set second marker to come back here
+.ft          \" back to previous font
+.in -1       \" remove indent
+.gcolor      \" remove previous color
+.gcolor citationbar
+\r\L'|\\nCu' \" draw line (\r moves upward, \L draw the line, ...)
+.sp '|\\nDu' \" return to the second marker
+.gcolor      \" remove previous color
+.sp -2       \" get two lines back
+.KE          \" end of the keep
+..
+.
+.de NAMECITATION
+.ps -2
+\(em\h'1'\\$*
+.ps
+..
+.
+.de EXPLANATION1
+.KS          \" start a keep
+.ft B        \" citation in italics
+.mk C        \" set a marker for line drawing
+.in +1       \" indent a bit
+.gcolor explanation
+..
+.de EXPLANATION2
+.ft          \" back to previous font
+.in -1       \" remove indent
+.gcolor      \" remove previous color
+.gcolor explanationbar
+\r\L'|\\nCu' \" draw line (\r moves upward, \L draw the line, ...)
+.gcolor      \" remove previous color
+.sp -1       \" get two lines back
+.KE          \" end of the keep
+..
+.
+.de METAINFO1
+.ft CW    \" constant width font
+.ps 8     \" small font
+.vs 9p    \" smaller vertical spacing between lines
+..
+.de METAINFO2
+.sp 1
+.vs      \" come back to the previous vertical spacing
+.ps      \" come back to the previous point size
+.ft      \" come back to the previous font
+.sp -1   \" return one line above
+..
+.
+.
+.de PRETTY_PERCENTAGE
+\v'-.7m\s[\\n(.s*6u/10u]+.7m'\\$1\v'-.7m\s0+.7m'\
+\(f/\s[\\n(.s*6u/10u]\\$2\s0
+..
+.de TWO_COLUMNS
+.2C
+.nr pg@fn-colw \\n[pg@colw]   \" footnotes' column width
+..
+.de HORIZONTALLINE
+\l'15'
+..
+.de SMALLFONT
+.ps 8
+.vs 9p
+..
+.de NORMALFONT
+.vs
+.ps
+..
+.de COMMAND1
+.b1
+..
+.de COMMAND2
+.b2
+..
+.de COMMANDNAME
+.I "\\$1"
+..
+.de FUNCTION
+.I "\\$1" "\\$2"
+..
+.de TYPE
+.gcolor darkgreen
 .ps 8
 .ft CW
 \\$1
@@ -30,8 +160,18 @@ accumulate
 .gcolor
 .ps
 ..
-.de TYPE
-.gcolor darkgreen
+.de TYPECLASS
+.I "\\$1" "\\$2"
+..
+.de OPERATOR
+.I "\\$1" "\\$2"
+..
+.de QUESTION
+.I "\\$1" "\\$2"
+\h'5p'
+..
+.de CONSTRUCTOR
+.gcolor darkred
 .ps 8
 .ft CW
 \\$1
@@ -63,124 +203,7 @@ accumulate
 To be defined or to finish.
 .ft R
 ..
-\# Bullet points
-.de BULLET
-.IP \(bu 2
-..
-.de ENDBULLET
-.in -2   \" indent
-..
-.
-\# Begin code box
-.de b1
-.B1
-.sp 0.2
-.ft CW
-..
-.
-\# End code box
-.de b2
-.sp 0.5
-.B2
-.ft
-..
-.de HORIZONTALLINE
-\l'15'
-..
-.de SMALLFONT
-.ps 8
-.vs 9p
-..
-.de NORMALFONT
-.vs
-.ps
-..
-.de COMMAND1
-.b1
-..
-.de COMMAND2
-.b2
-..
-.de COMMANDNAME
-.I "\\$1"
-..
-.de FUNCTION
-.I "\\$1" "\\$2"
-..
-.de TYPECLASS
-.I "\\$1" "\\$2"
-..
-.de OPERATOR
-.I "\\$1" "\\$2"
-..
-.de QUESTION
-.I "\\$1" "\\$2"
-\h'5p'
-..
-.\" MS Accents
-.\".AM
-.defcolor citation    rgb 0.4 0.4 0.4
-.defcolor citationbar rgb 0.3 0.3 0.7
-.de CITATION1
-.KS          \" start a keep
-.ft I        \" citation in italics
-.mk C        \" set a marker for line drawing
-.in +1       \" indent a bit
-.gcolor citation
-..
-.de CITATION2
-.mk D        \" set second marker to come back here
-.ft          \" back to previous font
-.in -1       \" remove indent
-.gcolor      \" remove previous color
-.gcolor citationbar
-\r\L'|\\nCu' \" draw line (\r moves upward, \L draw the line, ...)
-.sp '|\\nDu' \" return to the second marker
-.gcolor      \" remove previous color
-.sp -2       \" get two lines back
-.KE          \" end of the keep
-..
-.de NAMECITATION
-.ps -2
-\(em\h'1'\\$*
-.ps
-..
-.defcolor explanation    rgb 0.7 0.4 0.4
-.defcolor explanationbar rgb 0.8 0.3 0.3
-.de EXPLANATION1
-.KS          \" start a keep
-.ft B        \" citation in italics
-.mk C        \" set a marker for line drawing
-.in +1       \" indent a bit
-.gcolor explanation
-..
-.de EXPLANATION2
-.ft          \" back to previous font
-.in -1       \" remove indent
-.gcolor      \" remove previous color
-.gcolor explanationbar
-\r\L'|\\nCu' \" draw line (\r moves upward, \L draw the line, ...)
-.gcolor      \" remove previous color
-.sp -1       \" get two lines back
-.KE          \" end of the keep
-..
-.de METAINFO1
-.ft CW    \" constant width font
-.ps 8     \" small font
-.vs 9p    \" smaller vertical spacing between lines
-..
-.de METAINFO2
-
-.vs      \" come back to the previous vertical spacing
-.ps      \" come back to the previous point size
-.ft      \" come back to the previous font
-.sp -1   \" return one line above
-..
-.de PRETTY_PERCENTAGE
-\v'-.7m\s[\\n(.s*6u/10u]+.7m'\\$1\v'-.7m\s0+.7m'\
-\(f/\s[\\n(.s*6u/10u]\\$2\s0
-..
-.de TWO_COLUMNS
-.2C
-.nr pg@fn-colw \\n[pg@colw]   \" footnotes' column width
+.de ARROW
+.br
+\(->\h'5p' \\$*
 ..
diff --git a/main.ms b/main.ms
index 48fb333..5034224 100644
--- a/main.ms
+++ b/main.ms
@@ -4,6 +4,59 @@
 .so macros.ms   \" First, let's import some macros.
 .so header.ms
 .TWO_COLUMNS
+.NH   \" new section
+Before we start
+.PP
+.QUESTION "Why a PDF instead of a website?"
+Documentation is about providing information in a comprehensive manner.
+There are different ways, roughly summarised in the following as
+.I website
+and
+.I book
+(maybe as a PDF document and not a physical book, but you get the idea).
+
+.TS
+allbox tab(:);
+c | c
+c | lew(2.8i).
+Doc. : Perks
+Web :T{
+Quick and easy to create and share,
+very small contributions are shared,
+easily updated
+T}
+Book :T{
+All related informations in a single place,
+collectible,
+very little updates
+T}
+.TE
+
+From the constraint of having to deliver a final document that cannot be updated, comes one of the biggest perks of books.
+Authors are forced to write to the best of their abilities.
+
+.TS
+allbox tab(:);
+c | c
+c | lew(2.8i).
+Doc. : Flaws
+Web :T{
+All differents,
+perishable,
+non easily collectible for backups,
+scattered information (articles),
+often not pedagogical or with little effort put in explanations,
+hard to follow updates
+T}
+Book :T{
+Way harder to write
+T}
+.TE
+
+Books can be written using a lot of different tools, including \fILaTeX\f[] or WYSIWYG editors such as \fILibreoffice\f[].
+None are simpler or withstood the test of time better than troff.
+Troff still works almost as its debuts in 1972, and as of today, it produces high quality documents with little effort or complexity.
+
 .NH   \" new section
 Sections and paragraphs
 .PP  \" new paragraph (with indentation on first line)
@@ -150,6 +203,27 @@ points
  .ENDBULLET
 .METAINFO2
 
+.HORIZONTALLINE
+
+Numbered lists
+.ENUM
+Orange
+.ENUM
+Apple
+.ENUM
+Pear
+.ENDENUM
+
+.METAINFO1
+ .ENUM
+ Orange
+ .ENUM
+ Apple
+ .ENUM
+ Pear
+ .ENDENUM
+.METAINFO2
+
 .NH
 Source code syntax highlighting
 .PP
@@ -392,21 +466,26 @@ Only PDF can be included, so images need to be converted beforehand.
  .PDFPIC -R "./are-you.pdf" 3.5
 .METAINFO2
 .
-.nr figurespace 17
-.sp \n[figurespace]
-.PDFPIC -R "./are-you.pdf" 3.5
+.nr figurespace 15
 .sp \n[figurespace]
+.PDFPIC -R "./are-you.pdf" 3.2
+.sv \n[figurespace]
 
 .METAINFO1
 Note: for now, on my system, I need a hack.
 The included PDF has no length, despite having installed the poppler-utils package.
-So, I added spaces by hand.
+So, I added vertical spaces by hand (with
+.I sp
+and
+.I sv
+requests).
+The length is an empirical constant.
 I'll try to search for a better way, someday.
 .METAINFO2
 
-.METAINFO1
- .nr figurespace 17
- .sp \\n[figurespace]
- .PDFPIC -R "./are-you.pdf" 3.5
- .sp \\n[figurespace]
-.METAINFO2
+.NH
+Final words
+.PP
+It is customary in old tools such as troff to read the source code and hack your way.
+Once you're familiar with the basics, if you need something that isn't in the official troff documentation, don't hesitate to read provided macros (mines, but also ms macros as well, for instance).
+You'll quickly learn a lot.