aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/grosciteco.tes
diff options
context:
space:
mode:
authorRobin Haberkorn <robin.haberkorn@googlemail.com>2016-02-26 02:02:50 +0100
committerRobin Haberkorn <robin.haberkorn@googlemail.com>2016-11-18 07:05:52 +0100
commite7867fb0d9979c550e6e3d7597ece73b680c4af6 (patch)
treedc7a273abc5dd75ecdd94bc62419cd966f38b6d0 /doc/grosciteco.tes
parentc0fe49457d37e4c51cd4fd829895a60ae24bc8af (diff)
downloadsciteco-e7867fb0d9979c550e6e3d7597ece73b680c4af6.tar.gz
implemented self-documenting (online) help system
* the new "?" (help) command can be used to look up help topics. * help topics are index from $SCITECOPATH/women/*.woman.tec files. * looking up a help topic opens the corresponding "womanpage" and jumps to the position of the topic (it acts like an anchor into the document). * styling is performed by *.woman.tec files. * Setting up the Scintilla view and munging the *.tec file is performed by the new "woman.tes" lexer. On supporting UIs (Gtk), womanpages are shown in a variable-width font. * Woman pages are usually not hand-written, but generated from manpages. A special Groff post-processor grosciteco has been introduced for this purpose. It is much like grotty, but can output SciTECO macros for styling the document (ie. the *.woman.tec files). It is documented in its own man-page. * grosciteco also introduces sciteco.tmac - special Troff macros for controlling the formatting of the document in SciTECO. It also defines .SCITECO_TOPIC which can be used to mark up help topics/terms in Troff markup. * Woman pages are generated/formatted by grosciteco at compile-time, so they will work on platforms without Groff (ie. as on windows). * Groff has been added as a hard compile-time requirement. * The sciteco(1) and sciteco(7) man pages have been augmented with help topic anchors.
Diffstat (limited to 'doc/grosciteco.tes')
-rwxr-xr-xdoc/grosciteco.tes283
1 files changed, 283 insertions, 0 deletions
diff --git a/doc/grosciteco.tes b/doc/grosciteco.tes
new file mode 100755
index 0000000..d84c6ab
--- /dev/null
+++ b/doc/grosciteco.tes
@@ -0,0 +1,283 @@
+#!/usr/bin/env sciteco -m
+!* grosciteco.tes <output-woman> <output-tec> <input> *!
+
+!* Process command-line options *!
+LR 0X[output-woman] 2LR 0X[output-tec] 2LR 0X[input] HK
+EBQ[input]
+
+! skip whitespace characters !
+@#sw{
+ <0A-^^ "N 1; ' :C;>
+}
+
+!* skip N (string) arguments beginning with current one *!
+@#sa{
+ "~1'<
+ <0A-^^ "= 1; ' 0A-10"= 1; ' :C;> :M#sw
+ >
+}
+
+!* get next integer argument, skipping it *!
+@#gi{
+ \ (0A-^^-"= :C ' <0A"D :C; | 1; '> :M#sw)
+}
+
+!* skip end of command *!
+@#sc{
+ 0A-10"= :C '
+}
+
+0U[text.lines] 0U[pos.v] 0U[pos.h]
+
+!* move to (pos.h,pos.v) relative to origin, making space if necessary *!
+@[move]{ [.n
+ U.n J
+ Q[pos.v]-Q[text.lines]">
+ ZJ Q[pos.v]-Q[text.lines]<I^J>
+ Q[pos.v]U[text.lines]
+ |
+ Q[pos.v]L
+ '
+ Q[pos.h]<.-Z"= I  | 0A-10"= I  | C' '>
+ Q.n<.-Z"= 1; ' 0A-10"= 1; ' D>
+].n }
+
+@[style]{ [.l
+ U.l Q[font]-Q[default-style]"N
+ .-Q.lESSTARTSTYLING Q[font],Q.lESSETSTYLING
+ '
+].l }
+
+[topics]
+
+!*
+ * Special characters
+ * FIXME: Use UTF8 characters once available
+ *!
+[glyphs.**]*
+[glyphs.\-]-
+[glyphs.aa]'
+[glyphs.dq]"
+[glyphs.hy]-
+[glyphs.la]<
+[glyphs.ra]>
+[glyphs.lq]"
+[glyphs.rq]"
+[glyphs.rs]\
+[glyphs.+]+
+
+!* process formatter commands *!
+@[format]{ <
+ .-Z"= 1; '
+ 0AU[cmd] C
+ Ocmd.U[cmd]
+
+ !cmd.x!
+ :M#sw
+ 0AU[cmd] C
+ Ocmd.xU[cmd]
+
+ !cmd.xT!
+ 2:M#sa :M#sc F<
+ !cmd.xr!
+ :M#sa :M#giU[res] :M#giU[res.h] :M#giU[res.v] :M#sc F<
+ !cmd.xi!
+ :M#sa :M#sc F<
+ !cmd.xF!
+ L F<
+ !cmd.xX!
+ :M#sw .(W).X.w
+ Ocmd.xXQ.w
+ !cmd.xXsciteco_topic!
+ !*
+ * FIXME: The buffer position of this topic might still
+ * change due to movement commands (esp. when formatting
+ * a table). Only the line+column should no longer change.
+ * Either store line+column or use markers.
+ *!
+ [* EB 0:M[move] .U.d ]*
+ :EU[topics]\.d:
+ C :X[topics]
+ L F<
+ !cmd.xXsciteco_tt!
+ [* EB 0:M[move] .U[ttstart] ]*
+ L F<
+ !cmd.xXsciteco_tt_end!
+ [* EB 0:M[move]
+ .-Q[ttstart]<
+ Q[ttstart]ESSTARTSTYLING Q[ttstart]ESGETSTYLEAT+16,1ESSETSTYLING
+ %[ttstart]>
+ ]*
+ L F<
+ !cmd.xXtty!
+ !cmd.xXdevtag!
+ L F<
+
+ !cmd.xf!
+ :M#sa :M#giU.n Q.n+16U.#nt .(:M#sa).X[font] :M#sc
+ :Q[fonts.\.n]"F F< ' -U[fonts.\.n]
+ @:EU[styles]{\.#ntESSTYLESETFONTCourier^J}
+ Ocmd.xfQ[font]
+ !cmd.xfR!
+ Q.nU[default-style]
+ @:EU[styles]{16ESSTYLESETFONTCourier^J}
+ F<
+ !cmd.xfB!
+ @:EU[styles]{1,\.nESSTYLESETBOLD 1,\.#ntESSTYLESETBOLD^J}
+ F<
+ !cmd.xfBI!
+ @:EU[styles]{1,\.nESSTYLESETBOLD 1,\.#ntESSTYLESETBOLD^J}
+ !cmd.xfI!
+ @:EU[styles]{1,\.nESSTYLESETITALIC 1,\.#ntESSTYLESETITALIC^J}
+ @:EU[styles]{0EJ-1"= 1,\.nESSTYLESETUNDERLINE 1,\.#ntESSTYLESETUNDERLINE '^J}
+ F<
+
+ !cmd.xt!
+ :M#sa :M#sc F<
+ !cmd.xs!
+ 1;
+
+ !cmd.p!
+ :M#sw :M#gi Q[pos.v]U[origin.v] :M#sc F<
+
+ !cmd.f!
+ :M#sw :M#giU[font] :M#sc F<
+
+ !cmd.s!
+ :M#sw :M#gi :M#sc F<
+
+ !cmd.V!
+ :M#sw :M#gi/Q[res.v]-1+Q[origin.v]U[pos.v] :M#sc F<
+
+ !cmd.v!
+ :M#sw :M#gi/Q[res.v]%[pos.v] :M#sc F<
+
+ !cmd.H!
+ :M#sw :M#gi/Q[res.h]U[pos.h] :M#sc F<
+
+ !cmd.h!
+ :M#sw :M#gi/Q[res.h]%[pos.h] :M#sc F<
+
+ !cmd.m!
+ :M#sw
+ 0AU[cmd] C
+ Ocmd.mU[cmd]
+
+ !cmd.md!
+ :M#sc F<
+
+ !cmd.D!
+ :M#sw
+ 0AU[cmd] C
+ Ocmd.DU[cmd]
+
+ !cmd.DF!
+ :M#sw
+ 0AU[cmd] C
+ Ocmd.DFU[cmd]
+
+ !cmd.DFd!
+ :M#sc F<
+
+ !cmd.Dl!
+ :M#sw :M#gi/Q[res.h]+Q[pos.h]U.[to.h] :M#gi/Q[res.v]+Q[pos.v]U.[to.v] :M#sc
+ [* EB
+ Q.[to.h]-Q[pos.h]"=
+ ! vertical line !
+ Q.[to.v]-Q[pos.v]"< Q[pos.v]U.v Q.[to.v]U[pos.v] | Q.[to.v]U.v '
+ 1:M[move] I+ %[pos.v]
+ Q.v-Q[pos.v]<
+ 1:M[move] I| %[pos.v]
+ >
+ 1:M[move] I+
+ Q.[to.v]U[pos.v]
+ |
+ ! horizontal line !
+ Q.[to.h]-Q[pos.h]"< Q[pos.h]U.h Q.[to.h]U[pos.h] | Q.[to.h]U.h '
+ 1:M[move] I+ %[pos.h]
+ Q.h-Q[pos.h]<
+ 1:M[move] I- %[pos.h]
+ >
+ 1:M[move] I+
+ Q.[to.h]U[pos.h]
+ '
+ ]* F<
+
+ !cmd.t!
+ :M#sw .(:M#sa).X.w
+ [* EB :Q.w:M[move]
+ G.w :Q.w:M[style] ]*
+ :Q.w%[pos.h] :M#sc F<
+
+ !cmd.C!
+ :M#sw .(:M#sa).X.w
+ [* EB 1:M[move]
+ G[glyphs.Q.w] 1:M[style] ]* :M#sc F<
+
+ !cmd.c!
+ :M#sw 0AU.w C
+ [* EB 1:M[move]
+ G[glyphs.U.w] 1:M[style] ]* :M#sc F<
+
+ !cmd.n!
+ :M#sw :M#gi :M#gi :M#sc F<
+
+ !cmd.w!
+ :M#sc F<
+> }
+
+!*
+ * Inline local macro invocations in [format]
+ * This speeds up runtime by 25%
+ *!
+EQ[format]
+ J<FR:M[move]Q[move];>
+ J<FR:M[style]Q[style];>
+ J<FR:M#saQ#sa;>
+ J<FR:M#giQ#gi;>
+ J<FR:M#swQ#sw;>
+ J<FR:M#scQ#sc;>
+ !*
+ * Compress whitespace, kind of dangerous:
+ * J<FRS ;>
+ *!
+Q*U*
+
+:M[format]
+
+!*
+ * Generate the styling instructions based on the styles
+ * of the womanpage buffer. The styles are configured according
+ * to their font positions (already in `styles`).
+ * Styles are NOT generated in `styles` immediately during
+ * formatting, since the buffer positions of text to style
+ * can still change with `move` operations that add whitespace.
+ * Also, here we can generate a minimal list of styling operations
+ * ending up with much smaller *.tec files.
+ * TODO: The size can still be improved by using SCI_SETSTYLINGEX
+ * if appropriate.
+ *!
+EB J 0U#cs 0U#cd
+<
+ .ESGETSTYLEATUs Qs"< Qs= '
+ .-Z"< Qs-Q#cs"= C F< ' '
+ Q#cs"N
+ .-Q#cd Ul
+ @:EU[styles]{\#cdESSTARTSTYLING \#cs,\lESSETSTYLING^J}
+ '
+ QsU#cs .U#cd
+:C;>
+
+!*
+ * Save the clear-text part of the document into <output-woman>
+ *!
+EWQ[output-woman]
+
+EQ[styles]
+
+!* Generate topic index *!
+J I!*Q[topics]*!^J
+
+EWQ[output-tec]
+
+-EX