Add introduction.
parent
88b6e082d0
commit
aa5e20cacb
2
Makefile
2
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
|
||||
|
|
|
|||
14
header.ms
14
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?
|
||||
|
|
|
|||
281
macros.ms
281
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' \\$*
|
||||
..
|
||||
|
|
|
|||
99
main.ms
99
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue