Add README.

4 files changed, 293 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 80cc949..10e663a 100644
--- a/Makefile
+++ b/Makefile
@@ -5,3 +5,9 @@ xroff: lex.yy.c
 
 lex.yy.c: xroff.lex
 	flex xroff.lex
+
+README: README.t
+	<README.t groff -ms -Tlatin1 | sed "s/\x1b\[[0-9;]*[a-zA-Z]//g" >README
+
+README.t: README.x
+	<README.x ./xroff >README.t
diff --git a/README b/README
new file mode 100644
index 0000000..0c3b9f5
--- /dev/null
+++ b/README
@@ -0,0 +1,132 @@
+
+
+
+
+
+
+
+
+
+             Xroff, an alternative troff syntax
+
+
+                      John Ankarström
+
+
+Introduction
+
+Xroff  is an alternative syntax for troff, visually inspired
+by SGML/XML. It differs from troff's default syntax  in  the
+following ways:
+
+1. Xroff requests begin with a less-than sign and end with a
+   greater-than sign, e.g., <SH 1>. These symbols may be es-
+   caped with a backslash.*
+
+2. Xroff requests may be used inline. The following works as
+   expected: (<ft B>bold<ft R>).**
+
+3. Xroff ignores empty lines.
+
+4. Default troff syntax may be used between <![ and ]>.
+
+The similarities with XML end at the  visual  level.  Unlike
+XML,  xroff is unstructured and imperative. There is no con-
+cept of closing tags.
+
+Example
+
+   <de b>\\fB\\$*\\fR<.>
+
+   <TL>Example document
+   <AU>John Doe
+
+   <AB>Pellentesque dapibus suscipit ligula. Donec posuere augue in quam.
+   Etiam vel tortor sodales tellus ultricies commodo. Suspendisse
+   potenti. Aenean in sem ac leo mollis blandit. Donec neque quam,
+   dignissim in, mollis nec, sagittis eu, wisi.<AE>
+
+   <SH 1>Introduction
+   <LP><b Nullam eu ante> vel est convallis dignissim. Fusce suscipit,
+   wisi nec facilisis facilisis, est dui fermentum leo, quis tempor
+   ligula erat quis odio. Nunc porta vulputate tellus.
+
+-----------
+  * For comparison, default troff  requests  begin
+with  a newline and a control character, usually a
+period or an apostrophe, and end with another new-
+line.
+  ** Before an inline request, xroff automatically
+inserts a \c escape when appropriate.
+
+
+
+                        10 June 2022
+
+
+
+
+
+                             -2-
+
+
+Xroff
+
+The program xroff translates xroff source to troff source.
+
+Xroff-mode
+
+For Emacs users, there is a major mode named xroff-mode that
+provides  syntax  highlighting  for xroff source. To further
+improve the writing experience, I also  recommend  olivetti-
+mode.
+
+Caveats
+
+Xroff  does not treat indented lines specially. As such, in-
+dentation cannot be used to convey structure.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+                        10 June 2022
+
+
diff --git a/README.t b/README.t
new file mode 100644
index 0000000..7bc4f4a
--- /dev/null
+++ b/README.t
@@ -0,0 +1,93 @@
+.ss 12 0
+.nr PI 0
+.nr PD 0.5v
+.if n .nr PD 1v
+.de i
+\\fI\\$*\\fR\c
+..
+.de bi
+\\f(BI\\$*\\fB\c
+..
+.de cw
+\\f(CW\\$*\\fR\c
+..
+.de cwb
+\\f(CB\\$*\\fR\c
+..
+.TL
+.bi Xroff
+, an alternative troff syntax
+.AU
+John Ankarström
+.DA 10 June 2022
+.SH 1
+Introduction
+.LP
+.i Xroff
+ is an alternative syntax for troff, visually inspired by SGML/XML. It differs from troff's default syntax in the following ways:
+.IP 1. 3
+Xroff requests begin with a less-than sign and end with a greater-than sign, e.g., \c
+.cw \<SH 1>
+\&. These symbols may be escaped with a backslash.*
+.IP 2.
+Xroff requests may be used inline. The following works as expected: \c
+.cw "(\<ft B>bold\<ft R>)"
+\&.**
+.IP 3.
+Xroff ignores empty lines.
+.IP 4.
+Default troff syntax may be used between \c
+.cw \<![
+ and \c
+.cw ]>
+\&.
+.LP
+The similarities with XML end at the visual level. Unlike XML, xroff is unstructured and imperative. There is no concept of closing tags.
+.FS *
+For comparison, default troff requests begin with a newline and a control character, usually a period or an apostrophe, and end with another newline.\c
+.FE
+.FS **
+Before an inline request, \c
+.cw xroff
+ automatically inserts a \c
+.cw \\\\c
+ escape when appropriate.\c
+.FE
+.SH 1
+Example
+.IP "" 3
+.nf
+.eo
+<de b>\\fB\\$*\\fR<.>
+
+<TL>Example document
+<AU>John Doe
+
+<AB>Pellentesque dapibus suscipit ligula. Donec posuere augue in quam.
+Etiam vel tortor sodales tellus ultricies commodo. Suspendisse
+potenti. Aenean in sem ac leo mollis blandit. Donec neque quam,
+dignissim in, mollis nec, sagittis eu, wisi.<AE>
+
+<SH 1>Introduction
+<LP><b Nullam eu ante> vel est convallis dignissim. Fusce suscipit,
+wisi nec facilisis facilisis, est dui fermentum leo, quis tempor
+ligula erat quis odio. Nunc porta vulputate tellus.
+.ec
+.SH 1
+.cwb Xroff
+.PP
+The program \c
+.cw xroff
+ translates xroff source to troff source.
+.SH 1
+.cwb Xroff-mode
+.PP
+For Emacs users, there is a major mode named \c
+.cw xroff-mode
+ that provides syntax highlighting for xroff source. To further improve the writing experience, I also recommend \c
+.cw olivetti-mode
+\&.
+.SH 1
+Caveats
+.LP
+Xroff does not treat indented lines specially. As such, indentation cannot be used to convey structure.
diff --git a/README.x b/README.x
new file mode 100644
index 0000000..ea6bfc0
--- /dev/null
+++ b/README.x
@@ -0,0 +1,62 @@
+<!-- -*- mode: xroff; mode: olivetti -*- -->
+
+
+<ss 12 0>
+<nr PI 0>
+<nr PD 0.5v>
+<if n .nr PD 1v>
+<de i>\\fI\\$*\\fR<.>
+<de bi>\\f(BI\\$*\\fB<.>
+<de cw>\\f(CW\\$*\\fR<.>
+<de cwb>\\f(CB\\$*\\fR<.>
+
+
+<TL><bi Xroff>, an alternative troff syntax
+<AU>John Ankarström
+<DA 10 June 2022>
+
+
+<SH 1>Introduction
+<LP><i Xroff> is an alternative syntax for troff, visually inspired by SGML/XML. It differs from troff's default syntax in the following ways:
+
+<IP 1. 3>Xroff requests begin with a less-than sign and end with a greater-than sign, e.g., <cw \<SH 1\>>. These symbols may be escaped with a backslash.*
+<IP 2.>Xroff requests may be used inline. The following works as expected: <cw "(\<ft B\>bold\<ft R\>)">.**
+<IP 3.>Xroff ignores empty lines.
+<IP 4.>Default troff syntax may be used between <cw \<![> and <cw ]\>>.
+
+<LP>The similarities with XML end at the visual level. Unlike XML, xroff is unstructured and imperative. There is no concept of closing tags.
+
+<FS *>For comparison, default troff requests begin with a newline and a control character, usually a period or an apostrophe, and end with another newline.<FE>
+
+<FS **>Before an inline request, <cw xroff> automatically inserts a <cw \\\\c> escape when appropriate.<FE>
+
+
+<SH 1>Example
+<IP "" 3><nf><eo><![
+<de b>\\fB\\$*\\fR<.>
+
+<TL>Example document
+<AU>John Doe
+
+<AB>Pellentesque dapibus suscipit ligula. Donec posuere augue in quam.
+Etiam vel tortor sodales tellus ultricies commodo. Suspendisse
+potenti. Aenean in sem ac leo mollis blandit. Donec neque quam,
+dignissim in, mollis nec, sagittis eu, wisi.<AE>
+
+<SH 1>Introduction
+<LP><b Nullam eu ante> vel est convallis dignissim. Fusce suscipit,
+wisi nec facilisis facilisis, est dui fermentum leo, quis tempor
+ligula erat quis odio. Nunc porta vulputate tellus.
+]><ec>
+
+
+<SH 1><cwb Xroff>
+<PP>The program <cw xroff> translates xroff source to troff source.
+
+
+<SH 1><cwb Xroff-mode>
+<PP>For Emacs users, there is a major mode named <cw xroff-mode> that provides syntax highlighting for xroff source. To further improve the writing experience, I also recommend <cw olivetti-mode>.
+
+
+<SH 1>Caveats
+<LP>Xroff does not treat indented lines specially. As such, indentation cannot be used to convey structure.