diff options
| -rw-r--r-- | Makefile | 6 | ||||
| -rw-r--r-- | README | 132 | ||||
| -rw-r--r-- | README.t | 93 | ||||
| -rw-r--r-- | README.x | 62 |
4 files changed, 293 insertions, 0 deletions
@@ -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 @@ -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. |