diff options
author | Robin Haberkorn <robin.haberkorn@googlemail.com> | 2016-02-26 02:02:50 +0100 |
---|---|---|
committer | Robin Haberkorn <robin.haberkorn@googlemail.com> | 2016-11-18 07:05:52 +0100 |
commit | e7867fb0d9979c550e6e3d7597ece73b680c4af6 (patch) | |
tree | dc7a273abc5dd75ecdd94bc62419cd966f38b6d0 /doc/grosciteco.tes | |
parent | c0fe49457d37e4c51cd4fd829895a60ae24bc8af (diff) | |
download | sciteco-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-x | doc/grosciteco.tes | 283 |
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 |