From c0b2871b31a6093627247c0fe084ee843f634896 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Sun, 10 Dec 2017 12:40:01 -0800 Subject: [PATCH] GUACAMOLE-313: Document log format. --- src/guaclog/man/guaclog.1.in | 55 ++++++++++++++++++++++++++++++------ 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/src/guaclog/man/guaclog.1.in b/src/guaclog/man/guaclog.1.in index 11896d59..e5dfa9d0 100644 --- a/src/guaclog/man/guaclog.1.in +++ b/src/guaclog/man/guaclog.1.in @@ -29,8 +29,8 @@ guaclog \- Guacamole input log interpreter .SH DESCRIPTION .B guaclog is an interpreter which accepts Guacamole protocol dumps, such as those saved -when input logging is enabled on a Guacamole connection, writing human-readable -text logs as output. +when input logging is enabled for a Guacamole session recording, writing +human-readable text logs as output. .B guaclog is essentially an implementation of a Guacamole client which accepts its input from files instead of a network connection, however unlike @@ -42,19 +42,56 @@ file named \fIFILE\fR.txt. Existing files will not be overwritten; the interpreting process for any input file will be aborted if it would result in overwriting an existing file. .P -Guacamole acquires a write lock on input logs as they are being written. By +Guacamole acquires a write lock on recordings as they are being written. By default, .B guaclog will check whether the each input file is locked and will refuse to read and -interpret an input file if it appears to be an in-progress log. This behavior -can be overridden by specifying the \fB-f\fR option. Interpreting an -in-progress log will still work; the resulting human-readable text file will -simply cover the user's session only up to the current point in time. +interpret an input file if it appears to be an in-progress recording. This +behavior can be overridden by specifying the \fB-f\fR option. Interpreting an +in-progress recording will still work; the resulting human-readable text file +will simply cover the user's session only up to the current point in time. . .SH OPTIONS .TP \fB-f\fR Overrides the default behavior of .B guaclog -such that input files will be interpreted even if they appear to be logs of -in-progress Guacamole sessions. +such that input files will be interpreted even if they appear to be recordings +of in-progress Guacamole sessions. +. +.SH OUTPUT FORMAT +The output format of +.B guaclog +is meant to match what the user would have typed within a typical text editor +as closely as possible, while also representing non-printable characters and +keyboard shortcuts in a human-readable way. +.P +All output is on one line, with new lines started only as a result of the user +pressing enter/return. Keys which produce printable characters are translated +into their corresponding Unicode codepoints and encoded as UTF-8, while +non-printable characters are enclosed within angle brackets and represented +with their human-readable names. Keyboard shortcuts which are made up of more +than one key are enclosed within angle brackets, with each key within the +shortcut separated by plus signs. +.P +Spaces and newlines are included as their Unicode character, except when +represented within a keyboard shortcut, in which case their human-readable +names are used instead. As the output of pressing tab can be easily mistaken +for spaces, and as pressing tab frequently has special meaning within +applications, tab is always represented by its human-readable name. +.P +Modifiers are output as part of keyboard shortcuts only. Simple pressing and +releasing of a modifier will be ignored, as are presses of shift or AltGr while +typing. +.P +For example, if the user typed "Hello WORLD!", selected everything by pressing +Ctrl+a, copied the selected text by pressing Ctrl+c, switched to another +application by pressing Alt+Shift+Tab, and then pasted the previously-copied +text by pressing Ctrl+v, the resulting log from +.B +guaclog +would look like: +.PP +.RS 0 +Hello WORLD! +