$ cats nobody@supertxt.net:specs/show-output.s.txt

# Show Outputs

Preformatted blocks are often used to display some code (shell or simple program) along with the expected output from running that code. If both pieces are put into the same preformatted section to highlight that one leads to the other there are certain practical problems that arise. The syntax highlighting, if present, attempts to highlight the output, which is usually not the same syntax as the code itself. Sometimes there is tooling that will allow you to easily copy the entire block with a simple gesture, but that would include the expected output too. Another approach is to separate the two blocks between code and output, but then both need to be juggled and if there's any text in between it can be confusing the relationship between code and output. A new format is needed that will allow both code and output to be glued together into the same block, but permit each portion to be handled independently for certain use cases.

note: The outp format, while specified using SuperTXT, is intentionally decoupled from it so that it can be used in a variety of domains, even other markup/down languages since there are similar difficulties in those domains too.
idea: With outp and a document parser it should be possible to do automated testing on code examples.

## Outp format

The outp format looks like this in the native preformatted block styleof the markup/down language.

<Executable source code or shell commands go here>
---- OUT ----
The expected output goes here. Omit this if the output is empty.
---- ERR ----
The expected error output goes here, or this section omitted entirely if it is empty.

If the executable is not shell code then the shell command can be specified like this, where "$1" represents a file with the file extension of the code (more on file extensions in the next section).

<Code goes here>
---- CMD ----
some cmd "$1" other arguments
---- OUT ----
Hello World

### File extension

The file extension for outp is a composite ".x.outp" where .x is the native file extension of the code at the beginning. There are other examples of composite file extensions, such as SuperTxt itself (i.e. .s.txt) and Unix "tarballs" (e.g. .tar.gz and .tar.xz). Logically, the outp file is configured by the code file extension to determine how to handle the unwrapped code portion in terms of syntax highlighting or other tooling.

The CMD section is expected to be general Unix ".sh" shell command.

For systems that use media types "<code_media_type>+outp" (e.g. "text/x-python+outp") can be used instead of file extensions. Note that the "$1" expansion will need to be converted to the file extension in this case.


You can provide a conventional comment on this document.

ssh nobody@supertxt.net ccmnt specs/show-output.s.txt <<EOF
suggestion: Here's my actionable suggestion.