diff options
Diffstat (limited to 'doc/sciteco.1.in')
| -rw-r--r-- | doc/sciteco.1.in | 125 |
1 files changed, 105 insertions, 20 deletions
diff --git a/doc/sciteco.1.in b/doc/sciteco.1.in index f57415c..e47ca93 100644 --- a/doc/sciteco.1.in +++ b/doc/sciteco.1.in @@ -16,6 +16,10 @@ Scintilla-based \fBT\fPext \fBE\fPditor and \fBCO\fPrrector .SCITECO_TOPIC "sciteco" .SY @PACKAGE@ .OP "-h|--help" +.OP "-v|--version" +.OP "-q|--quiet" +.OP "-i|--stdin" +.OP "-o|--stdout" .OP "-e|--eval" macro .OP "-m|--mung" .OP "--no-profile" @@ -59,12 +63,13 @@ invoked as scripts by using a Hash-Bang line like .RS .SCITECO_TT .EX -#!@bindir@/sciteco -m +#!@bindir@/@PACKAGE@ -m .SCITECO_TT_END .EE .RE . .LP +.SCITECO_TOPIC argv arguments Note that UNIX Hash-Bang lines will only pass a \fBsingle\fP argument to the interpreter before the script's file name, so all required \*(ST options must be mangled into a single argument with their single-letter names. @@ -72,27 +77,29 @@ Passing option-like arguments (beginning with a dash) to scripts may cause problems because \*(ST might try to interpret these options. \*(ST thus stops parsing at the first non-option argument (which will always be the munged file name in a script invocation). -. -.LP -.SCITECO_TOPIC argv arguments -Upon startup \*(ST's buffer ring contains only one unnamed empty buffer. -All command line arguments after the \*(ST options are passed as -.I arguments -to the munged macro by placing each argument on its own line in -the buffer. -The \fIscript\fP file name expected when \(lq--mung\(rq is given -is currently \fBnot\fP considered a macro argument. -In any case the current buffer position (called -.IR dot ) -is left at the beginning of the buffer. Optionally \(lq\-\-\(rq might be used to explicitly separate \*(ST options and macro arguments, but is never passed down as a macro argument. Since it's sometimes useful to pass down \(rq\-\-\(rq to the profile macro, you can use \(lq\-S\(rq, which is equivalent to \(lq\-\- \-\-\(rq. +All remaining arguments after the built-in processing of options +are passed to the executed macro using an array of global Q-registers \fB^A\fIx\fR. +The \fIscript\fP file name expected when \(lq\-\-mung\(rq is given +is currently \fBnot\fP included in this array. +Q-register \fB^A0\fP is the name of the current process as passed to C +programs in \(lqargv[0]\(rq. +. +.LP +Upon startup \*(ST's buffer ring always contains only one unnamed buffer. +If \(lq\-\-stdin\(rq is given, \*(ST first reads from \fIstdin\fP until end-of-file +into the unnamed buffer. +This is includes automatic EOL translation just like when using the \fBEB\fP command +and can therefore be disabled by specifying \(lq\-\-8bit\(rq. +If reading from \fIstdin\fP results in any text additions, the buffer is left \fIdirty\fP. +The current position (called dot) is always left at the beginning of the buffer. . .LP If the munged macro does not request program termination using the -\fBEX\fP command or exits using \fB^C\fP, \*(ST will automatically +\fBEX\fP command or exits using \fB^C^C\fP, \*(ST will automatically switch into its graphical \fIinteractive\fP mode. \*(ST may be built with different graphical user interfaces, including Curses and GTK+ based ones. @@ -119,7 +126,7 @@ to these streams while in interactive mode, or messages are continued to be written to these streams (in addition to being displayed in the GUI). .IP \(bu Messages logged to \fIstdout\fP or \fIstderr\fP \(em except -for messages written explicitly via some \*(ST command \(em +for \(lquser\(rq-level messages (written explicitly via some \*(ST command) \(em are prefixed with a string signifying the message's severity. In interactive mode, messages are also shown in a GUI-dependant manner. @@ -141,6 +148,10 @@ Batch mode does not have these restrictions. .IP \(bu A few commands that modify the command line are only available in interactive mode. +.IP \(bu +A few commands like \fB^C\fP are disallowed in interactive mode +when run from the command-line macro or behave slightly +differently compared to batch mode (e.g. \fB$$\fP or \fB==\fP). .RE . .LP @@ -179,6 +190,29 @@ option. .IP "\fB-h\fR, \fB--help\fR" .SCITECO_TOPIC "-h" "--help" Display a short help text on the console. +.IP "\fB-v\fR, \fB--version\fR" +.SCITECO_TOPIC "-v" "--version" +Display the \*(ST version in an easy to parse way. +See also the \fBEO\fP command. +.IP "\fB-q\fR, \fB--quiet\fR" +.SCITECO_TOPIC "-q" "--quiet" +Do not print any messages to \fIstdout\fP except for \(lquser\(rq-level +messages, i.e. messages printed via \fBT\fP, \fB^T\fP and related +commands. +This is useful when piping the output of \*(ST into other programs. +.IP "\fB-i\fR, \fB--stdin\fR" +.SCITECO_TOPIC "-i" "--stdin" +Reads from \fIstdin\fP into the unnamed buffer before executing any macro. +Allows to easily integrate \*(ST into an UNIX pipeline, at least +if you don't need to process infinite streams. +This normalizes end-of-line (EOL) characters just like when opening +any other file. +.IP "\fB-o\fR, \fB--stdout\fR" +.SCITECO_TOPIC "-o" "--stdout" +\# FIXME: Perhaps this should imply --quiet? +Prints the current document's contents to \fIstdout\fP immediately before +terminating the program, restoring the original EOL characters. +This is also useful when piping the output of \*(ST into other programs. .IP "\fB-e\fR, \fB--eval\fR \fImacro" .SCITECO_TOPIC "-e" "--eval" Evaluate (execute) @@ -223,7 +257,12 @@ Execute \(lqsciteco --help\(rq for more details. .SCITECO_TOPIC status . \*(ST will return a non-null exit code if an error occurred during -batch mode processing. +batch mode processing \(em usually 1 on UNIX. +Otherwise the top value on the numeric stack will determine +the process' exit code as if passed to libc's +.BR exit (3) +function. +On UNIX systems only numbers between 0 and 255 may be meaningfull. . . .SH ENVIRONMENT @@ -411,12 +450,22 @@ and opening files specified on the command line. .B $SCITECOPATH/*.tes Standard library macros. .TP -.SCITECO_TOPIC savepoint +.BI # filename # +Recovery file: +After a configurable recovery interval \*(ST dumps up all modified buffers +(unsaved changes), that have not been dumped previously. +These files should be ignored by version control systems and may +be left around after crashes and unexpected restarts. +See \fB6EJ\fP for more details. +.TP +.SCITECO_TOPIC savepoint backup .BI .teco- n - filename ~ Save point files created by \*(ST when saving files during interactive execution have this format. On Windows, these files have the hidden attribute set. -Savepoint files are temporary and should be ignored by version +They are internally used when rubbing out file saves +and are conceptually similar to backup files in other editors. +However they are temporary and should be ignored by version control systems, etc. .TP .SCITECO_TOPIC ".teco_session" session @@ -492,6 +541,42 @@ In order to execute a stand-alone script or custom profile macro: .EE .RE . +.LP +The easiest way to integrate \*(ST into an UNIX pipeline is +by using the \(lq--quiet --stdin --stdout\(rq or \(lq-qio\(rq +parameters. +For instance in order to prefix all lines with a line number: +.RS +.SCITECO_TT +.EX +dmesg | @PACKAGE@ -qioe '<%a\\@I/ / :L;>' +.SCITECO_TT_END +.EE +.RE +. +.LP +This also works in interactive mode, so \(lq@PACKAGE@ -i\(rq +allows you to interactively edit text read from \fIstdin\fP. +Suppose you would want to print only those lines from \fIstdin\fP +matching \(lqiwm0:\(rq: +.RS +.SCITECO_TT +.EX +dmesg | @PACKAGE@ -qie '<@S/iwm0:/; :L; -T>' +.SCITECO_TT_END +.EE +.RE +. +.LP +In order to query the installation path of the standard library, +which is useful for authors of third-party macro packages: +.RS +.SCITECO_TT +.EX +@PACKAGE@ -qe ':G[$SCITECOPATH]' +.SCITECO_TT_END +.EE +.RE . .SH SEE ALSO . @@ -527,7 +612,7 @@ DEC Standard TECO-11 .SH AUTHOR . This manpage and the \*(ST program was written by -.MT robin.haberkorn@googlemail.com +.MT rhaberkorn@fmsbw.de Robin Haberkorn .ME . \# EOF
\ No newline at end of file |