COPRIS(1) 0.9-750-g267ee9a-dirty COPRIS(1) NAME copris - a converting printer server SYNOPSIS copris [options] [printer device or output file] copris --dump-commands > new_feature_file.ini DESCRIPTION COPRIS is a printer server and text conversion program that bridges the gap between modern, UTF-8-encoded, Markdown-formatted text and (older) dot-matrix and thermal printers. When provided with the appropriate configuration files and options, COPRIS reads plain text from a local source or the network (with a built-in TCP socket server), applies optional processing methods to it and sends it to the destination device (or file). Two main text processing methods stand out in COPRIS; they are: Character recoding via encoding files Older printers usually don’t support multi-byte UTF-8-encoded text. Rather, they use code pages and customised character sets which may vary between different manufacturers. COPRIS can load a character encoding file that is used to recode received text. By writing or se‐ lecting a premade one for your printer and locale, you allow COPRIS to recode (replace) re‐ ceived characters with appropriate locale-specific ones, understood by your printer. This is particularly useful in cases where printer distributors swapped lesser-used ASCII characters (such as ~ @ {) with those from the national alphabet, so they could be typed out directly from the non-localised keyboard. By finding similar-looking characters in printer’s character set, you may, crudely, regain those lost characters. However, encoding files aren’t tied only to locale conversions, you may use them to remap any character. Examples include typographic quotation marks, em dashes, copyright symbol and others, commonly found in character sets of various printers. Markdown formatting via printer feature files Many printers support commands (escape codes) for formatting printed text (e.g. Epson has its ESC/P control language). COPRIS can read a printer feature file that specifies such commands, invoked by following Markdown attributes: • bold and italic emphasis via asterisks (*, **, ***) or underscores (_, __, ___) • up to 4 levels of headings via number signs (#, ##, ###, ####) • blockquotes via greater-than signs and a space (> ) • inline code via single backticks (`) • code blocks via triple backticks (```) – or four spaces, but those are disabled by default • links via angle brackets (< >) Any command can be bound to mentioned attributes. If desired, bold emphasis can trigger double-width text, headings may change the font face or size and links can be made under‐ lined. There are no limits, as long as your printer feature file contains commands that are understood by the printer (or any other destination device). You might have noticed that only a subset of the Markdown specification is supported. CO‐ PRIS intentionally doesn’t alter text layout (white space, paragraphs etc.), since there’s no markup/layout engine. You may freely format your input plain-text files to your liking, and COPRIS will preserve the spacing and newlines (just be warned about four leading spaces triggering a code block). FILE FORMAT Encoding and printer feature files are expected to be in the INI file format: # Comment key1 = whitespace separated values key2 = whitespace separated values ; inline comment ... Left-hand keys should be written out directly as UTF-8 characters or strings, right-hand values are expected to be in either decimal, octal (prefixed by a 0) or hexadecimal base (prefixed with 0x). Don’t prepend zeroes to decimal numbers for alignment, as they’ll be interpreted as octal numbers. Instead, use any amount of spaces (or tabulators). One line can contain exactly one definition/command. In case you need a key to resolve to a blank value, set @ as the value (e.g. if you want to remove certain characters from the text, or omit rendering some Markdown attributes). Here are some examples: Å = 0xC5 ; for an encoding file F_BOLD_OFF = 0x1B 0x45 ; for a printer feature file F_H3_ON = @ ; ditto THE ENCODING FILE Before making one, check if COPRIS already includes one for your locale (encodings directory in the source tree). The format of an encoding file is as follows. Start the line by entering your desired char‐ acter, either via the keyboard or copied from somewhere else. Follow by an equals sign. Then, enter the numerical value of the same character your printer will understand. Here’s an example excerpt of the YUSCII encoding: # Left-hand letters are readable to us, however, their UTF-8 codes # are unknown to the printer. Therefore, COPRIS replaces them with # the right-hand values, here represented in hexadecimal. Č = 0x5E ; replacing ^ Ž = 0x40 ; replacing @ Š = 0x7B ; replacing [ You might have noticed that YUSCII overrides some ASCII characters. Luckily, printer char‐ acter sets often consist of additional characters (Greek letters, box drawing and maths sym‐ bols etc.), which can be also specified in an encoding file to imitate the lost ones: ^ = 0x27 ; replacement is an acute accent @ = 0xE8 ; replacement is the Greek letter Phi ... Have you transcribed a national or a well known encoding COPRIS doesn’t yet include? Con‐ tributions are always welcome! You may find out that your printer supports a code page, appropriate for your locale, but it isn’t selected by default when you turn it on. Read on, the chapter about printer feature files explains session commands which can be used for setting up the printer. THE PRINTER FEATURE FILE As with encoding files, COPRIS’ source tree might have the right one in the feature-files/ directory. If the file name seems appropriate, check the first few lines of the file to see if your printer/use case is supported. Else, consult the printer’s manual. There should be a section on escape codes. Generate a sample printer feature file (copris --dump-commands > my-printer.ini). Uncomment the appro‐ priate commands and append values from the manual, in the same way as with encoding files. Example from Epson’s LX-300 manual, page A-14 (91): ASCII Dec. Hex. Description ---------------------------------------- ESC 4 52 34 Select Italic Mode ESC 5 53 35 Cancel Italic Mode The corresponding printer feature file lines are: # lx300.ini F_ITALIC_ON = 0x1B 0x34 ; hexadecimal notation, 0x1B = ESC F_ITALIC_OFF = 27 53 ; decimal notation, 27 = ESC Variables in printer feature files You can use existing command names as variables, as long as you define the command before using it as a variable. Furthermore, you may define your own custom variables and use them in existing commands. For COPRIS to recognise them, they must be prefixed with C_! Vari‐ ables may be interweaved with commands. Examples: # lx300.ini - continued C_UNDERLINE_ON = 0x1B 0x2D 0x31 C_UNDERLINE_OFF = 0x1B 0x2D 0x30 F_H1_ON = C_UNDERLINE_ON F_ITALIC_ON F_H1_OFF = F_ITALIC_OFF C_UNDERLINE_OFF Session commands COPRIS provides two command pairs for sending repetitive settings to the printer. They may be used to set the code page, text margins, line spacing, font face, character density, ini‐ tialise/reset the printer and so on: • S_AT_STARTUP and S_AT_SHUTDOWN - sent to the printer once after COPRIS starts and once be‐ fore it exits • S_BEFORE_TEXT and S_AFTER_TEXT - sent to the printer each time text is received, in order S_BEFORE_TEXT - received text - S_AFTER_TEXT Examples: # lx300.ini - continued S_AT_STARTUP = 0x07 ; sound the bell (beeper) S_AFTER_TEXT = 0x0C ; trigger form feed after printing VARIABLES, NUMERICAL VALUES AND COMMENTS If you’ve defined a printer feature file, and it includes custom variables (prefixed with C_), you may use them directly in input text. To allow for that, begin your text with a line, containing COPRIS ENABLE-VARIABLES. This is called the modeline and tells COPRIS to process variables in input text. You may then call variables in the text file by prepending a dollar sign to them. I.e., if your variable is C_SERIF, $C_SERIF should be used in text. If you want to call multiple, write them out space-separated. Note that anything between the dollar sign and the new line is interpreted as a variable (or a series of them). Furthermore, apart from already-defined variables, numerical values can be included in text. They must be written out in the same way as variables - prefixed with a dollar sign, and, if specifying a multitude of them, separated by white spaces. They must be in either decimal, octal or hexadecimal notation, as they would be in a printer feature file. Lastly, comments can be passed in text. They again consist of a dollar sign, which is then followed by a number sign and your comment message. Here are examples of all three notations: COPRIS ENABLE-VARIABLES (must be included at the top) $# This reduces line spacing: $C_ESC 0x33 25 (feature file has a C_ESC command defined) Mixing variables and text Be wary of mixing variables and text in a sentence. Variables will only get detected prop‐ erly if they’re at the end of the sentence, not followed by any punctuation. Meaning: Word count is $C_WC (works normally) The sum is $C_WC words. (fails - expects a variable named '$C_WC words.') For reliable interpretation of variables, dedicate a whole line just for them, and make use of Markdown for mixing text and commands. COPRIS will skip parsing variables without the correct prefix (letter and underscore) and copy them out to the output. If you’d like to do the same to a variable with one of the correct prefixes, escape it by prepending it another dollar symbol. The modeline It is expected in the first line of received text. Its format is: COPRIS [ optional 2nd option ] Previous documentation already mentioned its use for for enabling variables. It serves one other purpose, disabling parsing Markdown in text. Here are both modeline options and their short forms: • ENABLE-VARIABLES; ENABLE-VARS • DISABLE-MARKDOWN; DISABLE-MD Letters are case-insensitive and the order of options isn’t important. Thus, following lines are the same: • COPRIS ENABLE-VARIABLES DISABLE-MARKDOWN • copris disable-md enable-vars COMMAND LINE OPTIONS -p, --port NUMBER Run COPRIS as a network server on port NUMBER. Superuser privileges are required if NUMBER is less than 1024. -e, --encoding FILE Recode characters in received text according to definitions from encoding FILE. This option can be specified multiple times with different FILEs. --ignore-missing If recoding characters, do not terminate the program if received text contains any possibly unwanted multi-byte characters that were not handled by specified FILEs. -f, --feature FILE Process Markdown markup and variables in received text and apply session commands ac‐ cording to printer feature FILE. This option can be specified multiple times with different FILEs. To use commands from FILE as variables in received text, they must be prefixed with a predefined symbol, which is shown when invoking copris --version. This feature only works when the received text starts with COPRIS ENABLE-VARIABLES. To use commands from FILE but ignore parsing Markdown in received text, it should be‐ gin with COPRIS DISABLE-MARKDOWN. Read the Modeline chapter for more information. --dump-commands Show all possible printer feature commands in INI file format (e.g. to be piped into a new printer feature file you are making). -d, --daemon If running as a network server, do not exit after the first connection. -l, --limit NUMBER If running as a network server, limit number of received bytes to NUMBER. --cutoff-limit If limit is active, cut text on NUMBER count instead of discarding the whole chunk. -v, --verbose Show informative status messages. If specified twice, show even more messages. -q, --quiet Do not show any unnecessary messages, except warnings and fatal errors, routed to stderr. This also omits notes, shown if COPRIS assumes it is not invoked properly. -h, --help Show a short option summary. -V, --version Show program version, author and build-time options. Do not specify a port number if you want to read from standard input. Likewise, omit the output file to have text echoed out to standard output (or piped elsewhere). EXAMPLES OF INVOKING COPRIS Notice: COPRIS is in active development. Some features are still missing, others have not been thoroughly tested yet. Command line option arguments may change in future. Version 1.0 will be tagged when the feature set will be deemed complete. Run as a simple server on port 8080, perform no text recoding, output received data to the serial port and exit after one connection. Note that superuser privileges are required if the specified port is smaller than 1024. copris -p 8080 /dev/ttyS0 Serve on port 8080 as a daemon (do not exit after first connection), recode text using the slovene.ini encoding file, limit any incoming text to a maximum of 100 characters and print received data to the terminal. Note that text limit works only when running as a server. copris -p 8080 -d -e slovene.ini -l 100 Read local file font-showcase.md using the printer feature file epson-escp.ini. Interpret any possible user commands, found in the local file. Output formatted text to an USB printer interface on the local computer: copris -f epson-escp.ini -c /dev/usb/lp0 < font-showcase.md KNOWN DEFICIENCIES • no warning is produced if there’s a typo in the modeline, or an unknown option mixed with valid ones • DOS/Windows style line endings (\r\n) aren’t supported - process input text through dos2unix(1) if necessary • markup in Markdown quotes is ignored • since signals aren’t caught, COPRIS doesn’t exit cleanly when interrupted • when sending data over the network, not all errors are send back to the sender DEVELOPMENT COPRIS’ development repository resides at ⟨https://github.com/bertronika/copris⟩. SEE ALSO stty(1), intercopris(1) 2024-11-04 COPRIS(1)