instant(1)

✨ NAME ✨

instant — bestie, this one manipulates ESIS from a parsed SGML instance. That's the whole vibe. 💅

📜 SYNOPSIS 📜

instant [ -bhuvxHISW ]  [ -t file]  [ -s file]  [ -c file]  [ -o file]
[ -D variable=value ...]  [ -i id]  [ -l directory]  [file]

🦋 DESCRIPTION 🦋

Okay so instant is the program that takes an SGML document instance and does stuff to it — like a whole variety of ways, no cap. It can translate it into a form that a formatting application can actually use, and it can also print information about the instance. Two totally different moods, one icon. 👑

The input to instant is the output of onsgmls, and that format is called Element Structure Information Set (ESIS). That's the name, remember it, it comes up again.

🎀 FLAGS 🎀

These are all the possible command line options for instant, bestie. Unless it says otherwise, output goes to the standard output. 📤

• -t file — Translate the SGML instance into another form, usually one that a formatting application can vibe with. That file is called a translation spec, and it says how the tags should get translated. Peep transpec(5) for that. By convention, names for file use the suffix .ts, for translation spec. ✨
• -s file — Points at a file of mappings for SDATA entities in the instance. The file has two columns, separated by one or more tabs. Lowkey important: spaces can not be used as the separator, because spaces are allowable as the content of the columns. 🙈 The first column is the entity data to map, the second is the string that the data is mapped to. The entity data is typically what's found in public ISO entity sets, like the General Technical and Publishing sets. These mappings are specific to whichever formatting application you're using. Example: to map the em dash entity, [mdash ], in the Publishing set to the TeX representation, the first column would be [mdash ] and the second column ---. Lines beginning with a # are comments and get ignored, and empty lines are also ignored. 🫶
• -c file — Points at a file of string mappings for characters in the instance. Two columns again, but this time separated by white space. First is the character to map, second is the string that the character is mapped to. Again, these mappings are specific to the formatting application used. Lines beginning with a # are comments and are ignored, empty lines too. 💖
• -d — strip newline at the beginning of data records
• -f length — Set the threshold for the length, in characters, of an <Entry>, over which it is called a block of filled text, to length.
• -o file — Write all output (except error and warning messages) to file. By default, output goes to stdout. 📝
• -h — Print a text representation of the hierarchy of the instance elements. The deeper an element is in the tree, the more it is indented. The data content is not printed. 🌳
• -u — Print a summary of the usage of each element in the instance. The info given includes attributes, number of children, and depth in the hierarchy. So much lore. 📊
• -S — Print some statistics about element usage in the instance, including how often each element is used and how much PCDATA is contained. Numbers girlies rise up. 🔢
• -x — Print the context of each element in the instance, from each element all the way to the root of the document tree. Ancestry reveal. 👑
• -v — Validate the SGML instance based on the set of constraints or descriptions in the transpec file. This flag tells instant to turn off normal output, leaving only diagnostics. 🩺
• -l directory — Try to read the translation specs or other files from inside the directory if they're not found in the current directory. This is called the library directory. The environment variable TPT_LIB may also be used to specify this. 📁
• -b — Interactive browser mode. The user gets prompted for actions, which include moving among and examining the various nodes in the hierarchy of the instance, displaying information about them, etc. It's giving choose-your-own-adventure. 🕹️
• -I — List the IDs of all elements in the instance that have an ID. The format is more suitable for other programs than for humans, ngl. Lines show the ID, element GI, filename, and line, separated by colons. (This depends on the -l option to onsgmls which provide filenames and line numbers.) 🤖
• -i id — When translating the instance, begin processing at the element whose ID is id instead of the topmost element. Skip to the good part. ⏭️
• -D variable=value — Define the variable variable with value value.
• -W — Do not print warning messages. 🤫
• -H — Print a help message briefly describing the options. 🆘
• file — Read the instance from the file file. This is expected to be the output of the program onsgmls. If not specified, instant reads the instance from its standard input.

⚠️ Okay real talk: in some cases it makes no sense to combine options. This is especially true if one of the options is to perform a translation. And no checking is done for this. So like... be responsible. No cap. 💀

🧚 INTERACTIVE BROWSER 🧚

These are the commands to the interactive browser, bestie:

• cd args ... — Change to a different element in the hierarchy. cd id id will change to the element whose ID is id. cd N will change to the Nth child element of the current element. Several values of N may be specified, so the program will change to successively descending elements in the hierarchy. The string .. may appear for N to move up a level in the hierarchy (like in a unix file system). A / may be specified for N to change to the top of the hierarchy. 🧭
• cont — Print the context of each element.
• data N — Show the data content (PCDATA, RCDATA, and DATA) of child node N. 🍓
• find spec — Find paths to elements matching spec, where spec may be one of:
  • parent gi — Find all elements whose parent element is gi.
  • child gi — Find all elements which have a child element gi.
  • gi gi — Find all elements whose name is gi.
  • attr name value — Find all elements that have a attribute name that have a value value.
• id ID — Show location of element whose ID is ID. If ID is ?, it will list all IDs with the paths to them. 🔍
• ls — List information about the current element in the hierarchy. This includes element name, line number in instance, context, attributes and their values, child elements, data directly within this element, and the order of the current element among its siblings. Full dossier energy. 📋
• q relation element — Report whether or not the current element has the relation relation to the named element element. Values of relation are the same as for _followrel in transpec reference page. 🤝
• stat — Show statistics about the hierarchy. 📈
• sum — Show a tag usage summary about the hierarchy. 🏷️
• tran transpec outfile — Write translated output using trans spec transpec to file outfile. If outfile is not specified, output is sent to stdout. 💾
• tree — Print a textual representation of the hierarchy of the instance, where deeper elements are indented more. 🌲
• where — Show current position in the hierarchy. 📍
• <control-D> — Exits the program. bye bestie 👋

The stat, sum, tree, cont commands take an optional first argument (of any value), which means to only consider the entire instance instead of the hierarchy from the current element.

🌸 FILES 🌸

• file.ts — Translation specification file. ✨
• file.sdata — SDATA entity mapping file. 🦋
• file.cmap — Character mapping file. 🎀

🌈 RELATED INFORMATION 🌈

transpec(5), onsgmls(1), Standard Generalized Markup Language (SGML), ISO 8879. Go read 'em, iykyk. 📚

And that's the whole page, babe — brought to you from the user cmd corner of the manual set. Stay iconic, go parse something. 💜✨