mirror of
https://github.com/adambard/learnxinyminutes-docs.git
synced 2024-12-23 17:41:41 +00:00
Merge 8f5e3f8635 into 7069599e41
This commit is contained in:
Jeff Parent
GitHub
commit
8d65b26dda
274
roff.html.markdown
Normal file
274
roff.html.markdown
Normal file
@ -0,0 +1,274 @@
|
|||||||
|
---
|
||||||
|
langauge: roff
|
||||||
|
contributors:
|
||||||
|
- ["Jeff Parent", "https://github.com/jecxjo"]
|
||||||
|
filename: learnroff.ms
|
||||||
|
---
|
||||||
|
|
||||||
|
```groff
|
||||||
|
.\" All comments start with a \"
|
||||||
|
.\" There are no multi-line comments. Comments can be inserted at the end of
|
||||||
|
.\" any line.
|
||||||
|
|
||||||
|
.\" roff is NOT a "What You See Is What You Get" word processing software like
|
||||||
|
.\" MS Word, or OpenOffice Writer.
|
||||||
|
|
||||||
|
.\" Every roff command starts with a new line and a period (.) or a single
|
||||||
|
.\" quote ('). Any line that doesn't start with a period or quote is considered
|
||||||
|
.\" normal text.
|
||||||
|
|
||||||
|
.\" roff documents start by deciding which macro package to use. There are
|
||||||
|
.\" many, all designed for different purposes and different types of documents.
|
||||||
|
.\" The most common one is the man macro package which most manpages are
|
||||||
|
.\" created from.
|
||||||
|
|
||||||
|
.\" The ms package is designed for creating for general purpose documents like
|
||||||
|
.\" papers, letters and books. It is the default package for groff. The me
|
||||||
|
.\" package is designed for creating technical documents. See `man 1 groff_me`
|
||||||
|
.\" or `man 1 groff_ms` for more details.
|
||||||
|
|
||||||
|
.\" To build this document into a pdf use the following command:
|
||||||
|
.\" groff -p -e -t -ms -Tpdf learnroff.ms > learnroff.pdf
|
||||||
|
|
||||||
|
.TL \" Sets the title of the document
|
||||||
|
LearnXinYMinutes - roff Edition
|
||||||
|
|
||||||
|
.AU \" Sets the author
|
||||||
|
Jeff Parent
|
||||||
|
|
||||||
|
.AI \" Sets the author's institution
|
||||||
|
ACME Corp
|
||||||
|
|
||||||
|
.AB \" Begins the abstract
|
||||||
|
roff is a typesetting system used to create documents using plain text and
|
||||||
|
outputting PDF, HTML, DVI and other formats with a simple Unix tool. It
|
||||||
|
supports basic typesettings as well as advanced features like tables, graphs
|
||||||
|
and equations.
|
||||||
|
.AE \" Ends the abstract
|
||||||
|
|
||||||
|
.tp \" Triggers the title page
|
||||||
|
|
||||||
|
.NH 1 \" Triggers a heading, level 1 (e.g 1. Introduction)
|
||||||
|
Introduction
|
||||||
|
.LP \" Starts a new paragraph
|
||||||
|
Welcome to the wonderful typesetting world of roff.
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
A section
|
||||||
|
.LP
|
||||||
|
This is a section. Sections are used to divide a document into smaller parts.
|
||||||
|
|
||||||
|
.NH 2 \" Triggers a heading, level 2 (e.g. 1.1 Subsection)
|
||||||
|
A subsection
|
||||||
|
.LP
|
||||||
|
This is a subsection. There can be many subsections with varying levels of
|
||||||
|
depth.
|
||||||
|
|
||||||
|
.NH 2
|
||||||
|
Another subsection
|
||||||
|
.LP
|
||||||
|
More text can go here.
|
||||||
|
|
||||||
|
.NH S 2 9 2
|
||||||
|
Some sections may need an explicit section number
|
||||||
|
.LP
|
||||||
|
However most cases you can rely on the automatic numbering. There is also
|
||||||
|
support for number/letter combinations.
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Some notes about text
|
||||||
|
.LP
|
||||||
|
roff does a good job handling text. It will automatically wrap text if the line
|
||||||
|
gets too long and will also handle text
|
||||||
|
that has newlines
|
||||||
|
in it. If you
|
||||||
|
.br
|
||||||
|
needs
|
||||||
|
.br
|
||||||
|
to
|
||||||
|
.br
|
||||||
|
break
|
||||||
|
.br
|
||||||
|
you add a .br command to the source code.
|
||||||
|
|
||||||
|
.LP
|
||||||
|
Separate paragraphs by the .LP command. This will add a blank line and start
|
||||||
|
the text on the left most margin.
|
||||||
|
|
||||||
|
.PP
|
||||||
|
Using the .PP command a paragraph is started by indenting the first line. All
|
||||||
|
additional lines will be at the left most margin.
|
||||||
|
|
||||||
|
.QP
|
||||||
|
The .QP command is used to start a paragraph where all lines are indented on
|
||||||
|
both the left and right sides of the document. This is a good way to quote text
|
||||||
|
or specify some sort of significance to the text.
|
||||||
|
|
||||||
|
.XP
|
||||||
|
The opposite of .PP is the .XP macro. As you can see this paragraph indents all
|
||||||
|
lines except for the first one. This is knowing as an \*Qextended\*Q paragraph
|
||||||
|
or a hanging indent.
|
||||||
|
|
||||||
|
.sp 4 \" Adds 4 lines of space
|
||||||
|
Sometimes you need to add more space. That is what the .sp command is for.
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Typography
|
||||||
|
.LP
|
||||||
|
|
||||||
|
roff supports many of the common typographic features all typesetting software
|
||||||
|
does. You can
|
||||||
|
.B bold
|
||||||
|
a word, or you can
|
||||||
|
.I italicize
|
||||||
|
a word. You can also
|
||||||
|
.BI "bold italicize"
|
||||||
|
a phrase or use
|
||||||
|
.CW "Common Width"
|
||||||
|
for showing commands. There is support for Super and Sub scripting as well and
|
||||||
|
it looks like this\*[{]Super Script\*[}] and this\*[<]Sub Script\*[>].
|
||||||
|
Unfortunately some typesetting is done with commands and others through escaped
|
||||||
|
characters.
|
||||||
|
.LP
|
||||||
|
Each set of macros has their own ways of handling typesetting features, roff
|
||||||
|
has a lot of low level commands so check out the documentation for more info.
|
||||||
|
The convention is that lowercase commands are low level built in operations
|
||||||
|
while uppercase commands are from the macro package.
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Lists
|
||||||
|
.LP
|
||||||
|
Lists are easy to implement in roff. There are two types of lists, bulleted and
|
||||||
|
numeric.
|
||||||
|
|
||||||
|
.IP \[bu] 3 \" the \[bu] is a bullet character
|
||||||
|
Item 1
|
||||||
|
.IP \[bu] 3
|
||||||
|
Item 2
|
||||||
|
.RS \" Starts a new list inside a list
|
||||||
|
.IP \[bu] 3
|
||||||
|
Sub Item 1
|
||||||
|
.RE
|
||||||
|
.IP \[bu] 3
|
||||||
|
Item 3
|
||||||
|
.LP
|
||||||
|
|
||||||
|
.\" We can auto numerate the list or manually set the values
|
||||||
|
.nr step 0 1 \" Setting the step counter to 0, incrementing by 1
|
||||||
|
|
||||||
|
.IP \n+[step] 3 \" Increment the step counter by 1 and set the indentation to 3
|
||||||
|
Apple.
|
||||||
|
.IP \n+[step] 3
|
||||||
|
Bananna
|
||||||
|
.IP \n+[step] 3
|
||||||
|
Cherry
|
||||||
|
.IP "Words Not Numbers" 3
|
||||||
|
This is a list item without a number
|
||||||
|
.LP \" End of list, starting new paragraph
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Math
|
||||||
|
.LP
|
||||||
|
roff was created for typesetting memos and technical documents. It was created
|
||||||
|
at Bell Labs as a word processor for all the technical stuff they were doing.
|
||||||
|
As such, we need to be able to add special symbols to our paper!
|
||||||
|
.LP
|
||||||
|
Math is often a big part of writing technical documents. roff has support for
|
||||||
|
this both as inline characters as well as equation figures. Unlike other
|
||||||
|
typesetting software, roff relies on independent preprocessors to handle things
|
||||||
|
like Math Equations. The .EQ macro starts an equation section and the .EN macro
|
||||||
|
ends it. See
|
||||||
|
.CW "man 1 eqn"
|
||||||
|
for details on how to use the eqn preprocessor.
|
||||||
|
.EQ
|
||||||
|
a sup 2 + b sup 2 = c sup 2
|
||||||
|
.EN
|
||||||
|
.LP
|
||||||
|
Greek letter can be written inline such as \(*x, \(*b, \(*g and \(*s. Within an
|
||||||
|
equation you can use these symbols as well.
|
||||||
|
.EQ
|
||||||
|
Area^of^a^Circle = pi r sup 2
|
||||||
|
.EN
|
||||||
|
Operators are an essential part of a mathematical document. Let's write an
|
||||||
|
equation to see how that is done:
|
||||||
|
.EQ
|
||||||
|
cos { 2 theta } = cos sup 2 { theta } - sin sup 2 { theta }
|
||||||
|
.EN
|
||||||
|
Fractions (Numerator-Denominators) can be written in this form:
|
||||||
|
.EQ
|
||||||
|
10 over 7
|
||||||
|
.EN
|
||||||
|
Summation and Integrals are written with the sum and int commands:
|
||||||
|
.EQ
|
||||||
|
sum from {i = 0} to 5 {f(i)}
|
||||||
|
.EN
|
||||||
|
.EQ
|
||||||
|
int from 0 to inf { e sup { -x } d x }
|
||||||
|
.EN
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Tables
|
||||||
|
.LP
|
||||||
|
|
||||||
|
Tables are created using the
|
||||||
|
.CW tbl
|
||||||
|
preprocessor. To include a table use the .TS and .TE macros.
|
||||||
|
|
||||||
|
.TS
|
||||||
|
center box;
|
||||||
|
c | c | c
|
||||||
|
l | n | r.
|
||||||
|
Name Age Location
|
||||||
|
_
|
||||||
|
John Doe 30 New York
|
||||||
|
Jane Smith 25 Los Angeles
|
||||||
|
Sam Brown 40 Chicago
|
||||||
|
.TE
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Diagrams
|
||||||
|
.LP
|
||||||
|
|
||||||
|
Diagrams are also supported, using the
|
||||||
|
.CW pic
|
||||||
|
preprocessor. To include a block diagram use the .PS and .PE macros.
|
||||||
|
|
||||||
|
.PS
|
||||||
|
box "Starting";
|
||||||
|
arrow;
|
||||||
|
circle "B1";
|
||||||
|
arrow;
|
||||||
|
ellipse "End";
|
||||||
|
.PE
|
||||||
|
|
||||||
|
.LP
|
||||||
|
There is also the ability to generate a graph.
|
||||||
|
|
||||||
|
.PS
|
||||||
|
pi = atan2(0, -1);
|
||||||
|
for i = 0 to 2 * pi by 0.1 do {
|
||||||
|
"-" at (i/2, 0);
|
||||||
|
"." at (i/2, sin(i)/2);
|
||||||
|
":" at (i/2, cos(i)/2);
|
||||||
|
}
|
||||||
|
.PE
|
||||||
|
|
||||||
|
.NH 1
|
||||||
|
Other Preprocessors
|
||||||
|
.LP
|
||||||
|
There are a few other preprocessors available to roff.
|
||||||
|
.CW chem
|
||||||
|
is used to create chemical structure diagrams.
|
||||||
|
.CW grn
|
||||||
|
is used for creating pictures.
|
||||||
|
.CW refer
|
||||||
|
is used for creating bibliographies.
|
||||||
|
```
|
||||||
|
|
||||||
|
## More on roff
|
||||||
|
|
||||||
|
* [The GNU Troff Manual](https://www.gnu.org/software/groff/manual/groff.html)
|
||||||
|
* [A Guide to Typesetting Mathematics using GNU eqn](https://lists.gnu.org/archive/html/groff/2013-10/pdfTyBN2VWR1c.pdf)
|
||||||
|
* [Making Pictures with GNU PIC](https://pikchr.org/home/uv/gpic.pdf)
|
||||||
|
* [man groff_me](https://linux.die.net/man/7/groff_me)
|
||||||
|
* [man groff_ms](https://linux.die.net/man/7/groff_ms)
|
||||||
Loading…
Reference in New Issue
Block a user