From c5696be8bfde10ab214feb13f84846afc8a7b149 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= Date: Fri, 10 Jun 2022 23:43:06 +0200 Subject: Add README. --- Makefile | 6 +++ README | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.t | 93 ++++++++++++++++++++++++++++++++++++++++++++ README.x | 62 ++++++++++++++++++++++++++++++ 4 files changed, 293 insertions(+) create mode 100644 README create mode 100644 README.t create mode 100644 README.x 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 + +README.t: README.x + 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., . These symbols may be es- + caped with a backslash.* + +2. Xroff requests may be used inline. The following works as + expected: (bold).** + +3. Xroff ignores empty lines. + +4. Default troff syntax may be used between . + +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 + + \\fB\\$*\\fR<.> + + Example document + John Doe + + 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. + + Introduction + 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 \ +\&. These symbols may be escaped with a backslash.* +.IP 2. +Xroff requests may be used inline. The following works as expected: \c +.cw "(\bold\)" +\&.** +.IP 3. +Xroff ignores empty lines. +.IP 4. +Default troff syntax may be used between \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 +\\fB\\$*\\fR<.> + +Example document +John Doe + +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. + +Introduction + 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 @@ + + + + + + + +\\fI\\$*\\fR<.> +\\f(BI\\$*\\fB<.> +\\f(CW\\$*\\fR<.> +\\f(CB\\$*\\fR<.> + + +, an alternative troff syntax +John Ankarström + + + +Introduction + is an alternative syntax for troff, visually inspired by SGML/XML. It differs from troff's default syntax in the following ways: + +Xroff requests begin with a less-than sign and end with a greater-than sign, e.g., >. These symbols may be escaped with a backslash.* +Xroff requests may be used inline. The following works as expected: bold\)">.** +Xroff ignores empty lines. +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 concept of closing tags. + +For comparison, default troff requests begin with a newline and a control character, usually a period or an apostrophe, and end with another newline. + +Before an inline request, automatically inserts a escape when appropriate. + + +Example +\\fB\\$*\\fR<.> + +Example document +John Doe + +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. + +Introduction + vel est convallis dignissim. Fusce suscipit, +wisi nec facilisis facilisis, est dui fermentum leo, quis tempor +ligula erat quis odio. Nunc porta vulputate tellus. +]> + + + +The program translates xroff source to troff source. + + + +For Emacs users, there is a major mode named that provides syntax highlighting for xroff source. To further improve the writing experience, I also recommend . + + +Caveats +Xroff does not treat indented lines specially. As such, indentation cannot be used to convey structure. -- cgit v1.2.3