OSX(1)

📦 version 1.5.2, in opensuse-leap 16.0

💅 OSX(1) 💅 — the SGML → XML glow-up, explained by your favorite Unix bestie 🦋

🎀 NAME 🎀

osx — an SGML to XML converter. that's the whole vibe, no cap. ✨

🌸 SYNOPSIS 🌸

osx [-CeghnRvx] [-aname] [-Aarchitecture] [-bencoding] [-ccatalog_file]
    [-ddirectory] [-Ddirectory] [-iname] [-ffile] [-ldtd_file]
    [-wwarning_type] [-xxml_output_option...] [sysid...]

💖 DESCRIPTION 💖

okay so bestie, osx converts SGML to XML. it parses and validates the SGML document contained in

…and yes, that sentence genuinely just ends there in the source. not me leaving you on read 😭 it's giving mystery, it's giving cliffhanger, it's giving the sysid goes here probably. moving on!

then it writes an equivalent XML document to the standard output. 🫶 and — super important — osx will warn about SGML constructs which have no XML equivalent. it will literally tell you "bestie that fit does not translate" and honestly? we love a converter with opinions. 💅

Part of an SGML System Conforming to International Standard ISO 8879 -- Standard Generalized Markup Language. An SGML Extended Facilities system conforming to Annex A of International Standard ISO/IEC 10744 -- Hypermedia/Time-based Structuring Language.

like, that's the pedigree. it's an icon, it's a legend, it's ISO-certified. 👑

✨ OPTIONS ✨

The following options are available, and we are going through every single one, because we don't skip. 🍓

  • -aname, --activate=name — make doctype or linkname name active. go girl, activate. 💫
  • -Aname, --architecture=name — parse with respect to architecture name. architectural realness. 🏛️
  • -bencoding, --encoding=encoding — use the BCTF encoding for output. by default osx uses UTF-8. (so if you say nothing, it's UTF-8 o'clock, periodt.) 🌈
  • -csysid, --catalog=sysid — map public identifiers and entity names to system identifiers using the catalog entry file whose system identifier is sysid. catalog said "I'll find it for you", and honestly, iconic behaviour. 📚
  • -C, --catalogs — this has the same effect as in onsgmls(1). (iykyk 🫶)
  • -ddirectory, --entity_output_location=directory — place output files in directory. put them away, put them away. 🗂️
  • -Ddirectory, --directory=directory — search directory for files specified in system identifiers. this has the same effect as in onsgmls(1).
  • -e, --open-entities — describe open entities in error messages. spill the tea about what's still open. ☕
  • -Emax_errors, --max-errors=max_errors — give up after max_errors errors. we all have a limit, bestie. 💀
  • -ffile, --error-file=file — redirect errors to file. this is useful mainly with shells that do not support redirection of stderr. a whole workaround moment.
  • -g, --open-elements — describe open elements in error messages. same energy as -e but for elements. 🫶
  • -h, --help — display a help text and exit. the "hey bestie what's going on" button. 🙈
  • -iname, --include=name — this has the same effect as in onsgmls(1).
  • -ldtd-file, --dtd_location=dtd-file — specify that the resulting XML file should conform to the DTD in dtd-file. (note: the synopsis spells it -ldtd_file, the option list spells it -ldtd-file — both are exactly as written, don't come for me 🎀)
  • -n, --error-numbers — show error numbers in error messages. receipts with reference numbers. 🧾
  • --references — show references in error messages.
  • -R, --restricted — this has the same effect as in onsgmls(1).
  • -v, --version — print the version number and exit. main character announcement. 👑
  • -wtype, --warning=type — control warnings and errors according to type. this has the same effect as in onsgmls(1).
  • -xxml_output_option, --xml-output-option=xml_output_option — control the XML output according to the value of xml_output_option, as follows:
    • no-nl-in-tag — don't use newlines inside start-tags. usually osx uses newlines inside start-tags so as to reduce the probability of excessively long lines. (short king behaviour)
    • id — output attribute declarations for ID attributes.
    • notation — output declarations for notations.
    • ndata — output declarations for external data entities. XML requires these to be NDATA. osx will warn about CDATA and SDATA external data entities and output them as NDATA entities. it said "adapting, not abandoning". 💅
    • cdata — use XML CDATA sections for CDATA marked sections and for elements with a declared content of CDATA.
    • comment — output comment declarations. comment declarations in the DTD will not be output. (the DTD comments are on do-not-disturb 🚫)
    • lower — prefer lower case. names that were subjected to upper-case substitution by SGML will be folded to lower case. this does not include reserved names; XML requires these to be in upper-case. so like, chill lowercase vibes, but reserved names stay LOUD. 📣
    • pi-escape — escape &<> in the contents of processing instructions using the amp, lt and gt entities. this allows processing instructions to contain the string >?, but requires that applications handle the escapes. trade-off queen. ⚖️
    • empty — use the <e/> syntax for element types e declared as EMPTY.
    • attlist — output an ATTLIST declaration for every element specifying the type of all attributes. the default will always be #IMPLIED. every element gets an outfit breakdown. 👗
    • report-input-sources — output a processing instruction to report when an input source other than the main file is opened or closed in the instance. do not report any input source changes in the DTD.
    • report-entities — output a processing instruction to report when an external entity reference has been resolved in the instance. do not report any entity resolutions in the DTD.
    • no-expand-external — preserve external entities, write a declaration driver file named "extEntities.dtf", and include that file in the instance's internal subset.
    • no-expand-internal — preserve internal entities, write a declaration driver file named "intEntities.dtf", and include that file in the instance's internal subset.
    • no-external-decl — do not include the external entities declaration driver file in the instance's internal subset.
    • no-internal-decl — do not include the internal entities declaration driver file in the instance's internal subset.
    • no-output-outside-outdir — when preserving external entities, do not write output files outside the specified output directory ("." by default). in other words, if an external entity's system identifier includes enough instances of ".." to cause osx to write a file outside (above) the output directory, exit (by default osx will issue a warning but will write the file and continue. 🚨 (and yes, that parenthesis never closes in the source. we love her anyway.)
    • no-overwrite — when preserving internal or external entities, multiple output files will be written. if this option is specified, do not overwrite existing files; instead, attempt to append a number to the end of the original filename to create a unique filename. exit with an error if too many (100) such files already exist. one hundred is the limit, and that's that. 💯
    • preserve-case — preserve casing as specified in the DTD for element names; attribute names; attribute values which are token lists.
    • sdata-as-pis — when translating SDATA entities (whether expanding them or providing a definition for them in the output's internal subset), express them as processing instructions instead of as general internal entities.
multiple -x options are allowed. stack them, layer them, accessorize. 💅✨

👀 SEE ALSO 👀

onsgmls(1), ospam(1), onsgmlnorm(1), ospent(1)

the whole friend group. go say hi. 🫶

💜 AUTHORS 💜

  • James Clark — Author.
  • Ian Castle <ian.castle@openjade.org> — Author.

two absolute legends. we stan. 👑

and that's the whole page, bestie!! 🦋 thanks for reading, you ate. this one came to you from OpenJade, dated November 2002, and it's filed under OSX(1) — mwah, take care of her, she's iconic. 💖💅✨

📦 where this page comes from