Add some documentation to the transform

[LesML] / sh / lesml.sh

#!/usr/bin/env sh
# @(#)💄📝 Les·M·L       sh/lesml.sh     2026-03-31T01:28:11Z
# SPDX-FileCopyrightText: 2023, 2024, 2026 Lady <https://www.ladys.computer/about/#lady>
# SPDX-License-Identifier: MPL-2.0

## ⁌ The 💄📝 Les·M·L shell script
##
## ∎ Copyright © 2023–2024, 2026 Lady [@ Ladys Computer].
##
## ⋮ This Source Code Form is subject to the terms of the Mozilla
##   Public License, version 2.0.
## If a copy of the M·P·L was not distributed with this file, You can
##   obtain one at {🔗<https://mozilla.org/MPL/2.0/>}.
##
## Usage :⁠—
##
## »|sh$sh ./sh/lesml.sh [--] [filename]
##
## This script provides a simple solution for converting a Les·M·L file
##   into X·H·T·M·L.

set -o 'errexit'

## `LANG´ and `LC_ALL´ are set to `C´ because this script assumes
##   working with U·T·F‐8 strings as opaque series of bytes.

LANG=C
LC_ALL=C

## § Configuration
##
## All of the commands used by this script are overridable with your
##   own implementations by setting the corresponding `cmd_COMMAND´
##   variable.

: "${cmd_DIRNAME:=dirname}"
: "${cmd_PRINTF:=printf}"
: "${cmd_REALPATH:=realpath}"
: "${cmd_SED:=sed}"
: "${cmd_TEST:=test}"
: "${cmd_TR:=tr}"
: "${cmd_XSLTPROC:=xsltproc}"

## In order to run, this program needs to know the location of the
##   💄📝 Les·M·L transform, which is calculated below.
## This location can be manually configured by setting the `path_LESML´
##   or `path_TRANSFORM´ environment variables.

thisfile="$(
  "${cmd_REALPATH}" -- "${0}"
)"
thisdir="$(
  "${cmd_DIRNAME}" -- "${thisfile}"
)"

defaultlesml="$(
  "${cmd_REALPATH}" -- "${thisdir}"'/..'
)"
: "${path_LESML:=${defaultlesml}}"

defaulttransform="${path_LESML}"'/xslt/lesml.xslt'
: "${path_TRANSFORM:=${defaulttransform}}"

## The (unregistered) media type for Les·M·L files is `text/lesml´.
## By overriding both the media type and the transform, one can re·use
##   this script for processing other kinds of files with X·S·L·T.

: "${name_MEDIATYPE:=text/lesml}"

## § Parameter processing
##
## A leading `--´ is allowed (and ignored).
## Otherwise, the first parameter is the source filename.

if "${cmd_TEST}" "${1}" = '--'
then :
  shift
fi

## If no input file is provided, it defaults to `-´ (standard input).

if "${cmd_TEST}" -n "${1}" && "${cmd_TEST}" "${1}" != '-'
then :
  inputfile="$(
    "${cmd_REALPATH}" -- "${1}"
  )"
else :
  inputfile='-'
fi

## § Implementation
##
## ※ This implementation is derived from
##   {🔗⛩📰 书社<https://git.ladys.computer/Shushe/>} code written
##   2023–2024.
##
## The `sanitizeprog´ variable contains a Sed program for sanitizing
##   an arbitrary string into characters which are valid in X·M·L.
## Ideally this would be written using dollar‐single‐quote literals,
##   but Mac·O·S Dash is outdated and does not support them.

sanitizeprog="$(
  "${cmd_PRINTF}" '%b' \
    's/]]>/]]]]><!\\[CDATA\\[>/g\n' \
    's/\0357\0277\0276/�/g\n' \
    's/\0357\0277\0277/�/g\n' \
    '$!s/\r$//g\n' \
    's/\r/\\n/g\n' \
    '$!s/\0302\0205$//g\n' \
    's/\0302\0205/\\n/g\n' \
    's/\0342\0200\0250/\\n/g\n' \
    's/[\0001\0002\0003\0004\0005\0006\0007\0010]/�/g\n' \
    's/[\0016\0017\0020\0021\0022\0023\0024\0025\0026\0027]/�/g\n' \
    's/[\0031\0032\0033\0034\0035\0036\0037]/�/g'
)"

## A compound statement is used to group together the wrapping X·M·L
##   and the sanitized input into one output which can be piped to
##   `xsltproc´.

{
  "${cmd_PRINTF}" '%s\n%s%s%s' \
    '<?xml version="1.0"?>' \
    '<script xmlns="http://www.w3.org/1999/xhtml" type="' \
    "${name_MEDIATYPE}" \
    '"><![CDATA['
  if "${cmd_TEST}" "${inputfile}" = '-'
  then :
    "${cmd_TR}" '\000\013\014' '\032\011\012'
  else :
    "${cmd_TR}" '\000\013\014' '\032\011\012' <"${inputfile}"
  fi |
  "${cmd_SED}" "${sanitizeprog}"
  "${cmd_PRINTF}" '%s\n' ']]></script>'
} |
"${cmd_XSLTPROC}" --nonet --nowrite --novalid \
  "${path_TRANSFORM}" \
  -