[groff] 29/40: roff(7): Import intro material from groff.texi.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit db411803c7df6af1ddf665d4fce4d1f26a2e2396
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Feb 5 10:32:42 2022 +1100

    roff(7): Import intro material from groff.texi.
    
    * Now that we have more fundamental material in place, push the "Page
      Geometry" stuff down into a subsection of that name.
---
 man/roff.7.man | 262 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 261 insertions(+), 1 deletion(-)

diff --git a/man/roff.7.man b/man/roff.7.man
index f2cf0f41..5caae706 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -93,7 +93,267 @@ and recommends materials for further reading.
 .SH Concepts
 .\" ====================================================================
 .
-.\" TODO: Break this into subsections when we get more material.
+.\" BEGIN Keep roughly parallel with groff.texi nodes "Text" through
+.\" "Tab Stops".
+.I roff
+input files contain text interspersed with instructions to control the
+formatter.
+.
+Even in the absence of such instructions,
+a
+.I roff
+formatter still processes its input in several ways,
+by filling,
+hyphenating,
+breaking,
+and adjusting it,
+and supplementing it with inter-sentence space.
+.
+These processes are basic to typesetting,
+and can be controlled at the input document's discretion.
+.
+.
+.P
+The formatter reads its input character by character,
+collecting words as it goes,
+and fits as many words together on an output line as it can\[em]this
+is known as
+.I filling.
+.
+To a
+.I roff
+system,
+a
+.I word
+is any sequence of one or more characters that aren't
+spaces,
+tabs,
+or newlines.
+.
+Words are separated by
+spaces,
+tabs,
+newlines,
+or
+file boundaries.
+.
+.
+.P
+A
+.I roff
+formatter attempts to detect the boundaries between sentences,
+and supplies additional inter-sentence space between them.
+.
+It does this by flagging certain characters
+(normally
+.RB \[lq] ! \[rq],
+.RB \[lq] ? \[rq],
+and
+.RB \[lq] . \[rq])
+as potentially ending a sentence.
+.
+When the formatter encounters one of these
+.I end-of-sentence characters
+at the end of a line,
+or one of them is followed by two spaces on the same input line,
+it appends an inter-word space
+followed by an inter-sentence space in the formatted output.
+.
+The non-printing input break escape sequence
+.B \[rs]&
+can be used after an end-of-sentence character to defeat end-of-sentence 
detection on a per-instance basis.
+.
+Normally,
+the occurrence of a visible non-end-of-sentence character
+(as opposed to a space or tab)
+immediately after an end-of-sentence
+character cancels detection of the end of a sentence.
+.
+However,
+several characters are treated
+.I transparently
+after the occurence of an end-of-sentence character.
+.
+That is,
+a
+.I roff
+does not cancel end-of-sentence detection when it processes them.
+.
+This is because such characters are often used as footnote markers or to
+close quotations and parentheticals.
+.
+The default set is
+.BR \[dq] ,
+.BR \[aq] ,
+.BR ) ,
+.BR ] ,
+.BR * ,
+.BR \[rs][dg] ,
+.BR \[rs][dd] ,
+.BR \[rs][rq] ,
+and
+.BR \[rs][cg] .
+.
+The last four are examples of
+.I special characters,
+escape sequences whose purpose is to obtain glyphs that are not easily
+typed at the keyboard,
+or which have special meaning to the formatter
+(like
+.B \[rs]
+itself).
+.
+.
+.P
+When an output line is nearly full,
+it is uncommon for the next word collected from the input to exactly
+fill it\[em]typically,
+there is room left over only for part of the next word.
+.
+The process of splitting a word so that it appears partially on one line
+(with a hyphen to indicate to the reader that the word has been broken)
+with its remainder on the next is
+.I hyphenation.
+.
+Hyphenation points can be manually specified;
+.I groff
+also uses a hyphenation algorithm and language-specific pattern files to
+decide which words can be hyphenated and where.
+.
+Hyphenation does not always occur even when the hyphenation rules for a
+word allow it;
+it can be disabled,
+and when not disabled there are several parameters that can prevent it
+in certain circumstances.
+.
+.
+.P
+Once an output line has been filled,
+whether or not hyphenation has occurred on that line,
+the next word read from the input will be placed on a different output
+line;
+this is called a
+.I break.
+.
+In this document and in
+.I roff
+discussions generally,
+a \[lq]break\[rq] if not further qualified always refers to the
+termination of an output line.
+.
+When the formatter is filling text,
+it introduces breaks automatically to keep output lines from exceeding
+the configured line length.
+.
+After an automatic break,
+a
+.I roff
+formatter
+.I adjusts
+the line if applicable
+(see below),
+and then resumes collecting and filling text on the next output line.
+.
+.
+.br
+.ne 2v
+.P
+Sometimes,
+a line cannot be broken automatically.
+.
+This usually does not happen with natural language text unless the
+output line length has been manipulated to be extremely short,
+but it can with specialized text like program source code.
+.
+.I groff
+provides a means of telling the formatter where the line may be broken
+without hyphens.
+.
+This is done with the non-printing break point escape sequence
+.BR \[rs]: .
+.
+.
+.P
+.\" What if the document author wants to stop filling lines temporarily,
+.\" for instance to start a new paragraph?  There are several solutions.
+There are several ways to cause a break at a predictable location.
+.
+A blank input line not only causes a break,
+but by default it also outputs a one-line vertical space
+(effectively a blank output line).
+.
+Macro packages may discourage or disable this \[lq]blank line
+method\[rq] of paragraphing in favor of their own macros.
+.
+A line that begins with one or more spaces causes a break.
+.
+The spaces are output at the beginning of the next line without being
+.I adjusted
+(see below).
+.
+Again, macro packages may provide other methods of producing indented 
paragraphs.
+.
+Trailing spaces on
+.I text lines
+(see below)
+are ignored.
+.
+The end of an input file causes a break.
+.
+.
+.P
+After the formatter performs an automatic line break,
+it then tries to
+.I adjust
+the line:
+inter-word spaces are widened until the text reaches the right margin.
+.
+Extra spaces between words are preserved.
+.
+Leading and trailing spaces are handled as noted above.
+.
+Text can be aligned to the left or right margins or centered using
+.I requests.
+.
+.
+.P
+A
+.I roff
+formatter translates horizontal tab characters,
+also called simply \[lq]tabs\[rq],
+in the input into movements to the next tab stop.
+.
+These tab stops are by default located every half inch measured from the
+current position on the input line.
+.
+With them,
+simple tables can be made.
+.
+However,
+this method can be deceptive,
+as the appearance
+(and width)
+of the text in an editor and the results from the formatter can vary
+greatly,
+particularly when proportional typefaces are used.
+.
+A tab character does not cause a break and therefore does not interrupt
+filling.
+.
+The formatter provides facilities for sophisticated table composition;
+there are many details to track
+when using the \[lq]tab\[rq] and \[lq]field\[rq] low-level features,
+so most users turn to the
+.MR @g@tbl @MAN1EXT@
+preprocessor for table construction.
+.\" END Keep roughly parallel with groff.texi nodes "Text" through "Tab
+.\" Stops".
+.
+.
+.\" ====================================================================
+.SS "Page geometry"
+.\" ====================================================================
+.
 .\" BEGIN Keep parallel with groff.texi node "Page Geometry".
 .I roff
 systems format text under certain assumptions about the size of the