Encode...ArabTeX(3pm)

📦
version 14.2 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 Encode::Arabic::ArabTeX 💖

okay bestie, welcome to Encode::Arabic::ArabTeX, a 3pm Perl manual page, and it's giving interpreter of the ArabTeX notation of Arabic. yes. that. buckle up, we're doing transliteration and it's lowkey gorgeous 🦋

✨ NAME ✨

Encode::Arabic::ArabTeX — Interpreter of the ArabTeX notation of Arabic 🌸

🌈 SYNOPSIS 🌈

no cap, here's the whole vibe in code, copied character-for-character because I would never mess with your syntax:

    use Encode::Arabic::ArabTeX;        # imports just like 'use Encode' would, plus extended options

    while ($line = <>) {                # maps the ArabTeX notation for Arabic into the Arabic script

        print encode 'utf8', decode 'arabtex', $line;       # 'ArabTeX' alias 'Lagally' alias 'TeX'
    }

    # ArabTeX lower ASCII transliteration <--> Arabic script in Perl's internal format

    $string = decode 'ArabTeX', $octets;
    $octets = encode 'ArabTeX', $string;

    Encode::Arabic::ArabTeX->encoder('dump' => '!./encoder.code');  # dump the encoder engine to file
    Encode::Arabic::ArabTeX->decoder('load');   # load the decoder engine from module's extra sources

periodt. 💅

👑 DESCRIPTION 👑

So ArabTeX is an excellent extension to TeX/LaTeX made for typesetting the right-to-left scripts of the Orient, and it comes with these lower ASCII transliterations that are super intuitive and comprehensible — honestly the expressive power of the notation is even better than that of the scripts themselves. iconic behaviour. ✨

Encode::Arabic::ArabTeX implements the rules you need for proper interpretation of the ArabTeX notation of Arabic. The conversion itself is done by Encode::Mapper, and the user interface is built on the Encode::Encoding module. the way that division of labour is chef's kiss 🫶

💖 ENCODING BUSINESS 💖

okay so here's the tea: since the ArabTeX notation is not a simple mapping to the graphemes of the Arabic script, encoding the script into the notation is ambiguous. two different strings in the notation may correspond to identical strings in the script. so heuristics must be engaged to decide which of the representations is more appropriate. it's giving detective work 🔍

and along with this bottle-neck, encoding may not be perfectly invertible by the decode operation, due to over-generation or approximations in the encoding algorithm. not everything round-trips, bestie. that's just the deal 😭

but!! there are situations where conversion from the Arabic script to the ArabTeX notation is still convenient and useful. imagine you need to edit the data, enhance it with vowels or other diacritical marks, produce phonetic transcripts and trim the typography of the script ... do it in the ArabTeX notation, having an unrivalled control over your acts! UNRIVALLED CONTROL 💅

nonetheless — and I quote the vibe — encoding is not the very purpose for this module's existence ;) 😌

🦋 DECODING BUSINESS 🦋

The module decodes the ArabTeX notation as defined in the User Manual Version 4.00 of March 11, 2004, <ftp://ftp.informatik.uni-stuttgart.de/pub/arabtex/doc/arabdoc.pdf>. The implementation uses three levels of Encode::Mapper engines to solve the problem:

🧚 Hamza writing

Hamza carriers are determined from the context in accordance with the Arabic orthographical conventions. The first level of mapping expands every "<'>" into the verbatim encoding of the relevant carrier. This level of processing can become optional, if people ever need to encode the hamza carriers explicitly.

Interpretation of geminated hamza "<''>" is correct here, as opposed to ArabTeX itself. In order to deduce the proper spelling rules, we resorted to <http://www.arabic-morphology.com/> and experimented with words like "<ra''asa>", "<ru''isa>", "<tara''usuN>", etc. 🔬

On this level, word-internal occurrences of "<T>" get translated into "<t>", which is an extension to the notation that simplifies some requirements in modeling of the Arabic morphology. cute, right?

🌸 Grapheme generation

The core level includes most of the rules needed, and converts the ArabTeX notation to Arabic graphemes in Unicode. The engine recognizes all the consonants of Modern Standard Arabic, plus the following letters — and yes, I'm keeping every single one, exactly as written:

                    [ "|",           ""         ],              # invisible consonant
                    [ "B",           "\x{0640}" ],              # consonantal ta.twil

                    [ "T",           "\x{0629}" ],              # ta' marbu.ta
                    [ "H",           "\x{0629}" ],              # ta' marbu.ta silent

                    [ "p",           "\x{067E}" ],              # pa'
                    [ "v",           "\x{06A4}" ],              # va'
                    [ "g",           "\x{06AF}" ],              # gaf

                    [ "c",           "\x{0681}" ],              # .ha with hamza
                    [ "^c",          "\x{0686}" ],              # gim with three
                    [ ",c",          "\x{0685}" ],              # _ha with three
                    [ "^z",          "\x{0698}" ],              # zay with three
                    [ "^n",          "\x{06AD}" ],              # kaf with three
                    [ "^l",          "\x{06B5}" ],              # lam with bow above
                    [ ".r",          "\x{0695}" ],              # ra' with bow below

There are many nice features in the notation — like assimilation, gemination, hyphenation — all implemented here. Defective and historical writings of vowels are supported, too! Try yourself if your fonts can handle these ;) 💀 (fr fr, check your fonts first)

Word-initial sequences like "<lV-all>", "<lV-al->", "<lV-al-CC>" and "<lV-aC-C>", where "V" stands for a short, possibly quoted or missing, vowel, and "C" represents a fixed consonant, are processed according to the requirements of the Arabic orthography. Thus, "<li-al-laylaTi>" reduces to "<li-llaylaTi>", "<li-al-rra^guli>" becomes "<lir-ra^guli>", and "<la-al-ma^gdu>" equals "<lal-ma^gdu>", while "<li-alla_dI>" turns into "<lilla_dI>". the glow-up on those strings 🦋✨

🎀 Wasla and ligatures

Wasla is introduced if there is a preceding long or short vowel, and the blank space is one newline, one tabulator, or up to four single spaces. Optionally, diacritical marks in between laam and 'alif go after the latter letter, since most of the current systems rendering the Arabic script do not produce the desired ligatures if the two kinds of graphemes are not adjacent immediately.

💡 heads up: there are modes and options in ArabTeX that have not been dealt with yet in Encode::Arabic::ArabTeX. Still, mutual consistency of the systems is very high. This new release does support vowel quoting and works in the ArabTeX's "\vocalize" mode by default. The other conversion modes are implemented, too, as described below within the "enmode" and "demode" methods.

🌟 EXPORTS, ENGINES & MODES 🌟

The module exports as if "use Encode" also appeared in the package. The "import" options, except for the first-place subsequence of ":xml", ":simple" or ":describe", are just delegated to Encode and imports performed properly. delegation queen 👑

  • if the first element in the list to use is :xml — all XML markup, or rather any data enclosed in the well-paired and non-nested angle brackets "<" and ">", will be preserved. Properties of the Encode::Arabic::ArabTeX engines can be generally controlled through the Encode::Mapper API.
  • in case the next, possibly the first, element in this list is :simple — rules in the engines get simplified so that quotes be mapped to empty strings and infrequent or experimental notations of vowels not be interpreted in the extra manner of ArabTeX. Using ":simple" is recommended for simple every-day tasks where these nuances would have no impact and where full initialization would be bothering. lowkey the move for casual days 🌈
  • the :describe option — calls the Encode::Mapper's "describe" method on the module's engines right after their compilation.

Initialization of the engines takes place the first time they are used, unless they have already been defined. There are two explicit methods for it:

💜 encoder

Initialize or redefine the encoder engine. If no parameters are given, rules in the module are compiled into a list of Encode::Mapper objects. Currently, the "--dump" and "--load" options have some experimental meaning. ⚠️ experimental, bestie, you've been warned.

💜 decoder

See the description of "encoder". yeah. same energy. 🫶

There are five conversion modes currently recognized in this module, and their aliases are mapped according to the module's %modemap hash. Selection of the appropriate mode is done best through the "enmode" and "demode" functions of Encode::Arabic, or with a direct call of the namesake methods in Encode::Arabic::ArabTeX:

    our %Encode::Arabic::ArabTeX::modemap = (           # the module provides these definitions

            'default'       => 3,                           'undef'         => 0,

            'fullvocalize'  => 4,   'full'          => 4,

            'vocalize'      => 3,   'nosukuun'      => 3,

            'novocalize'    => 2,   'novowels'      => 2,   'none'          => 2,

            'noshadda'      => 1,   'noneplus'      => 1,
        );

    # the function calls might be preferred as more comfortable

    Encode::Arabic::demode 'arabtex', 'full';           # like 'encode' and 'decode' of Encode

    Encode::Arabic::ArabTeX->demode('fullvocalize');    # like the Encode::Encoding interfaces

    # how modes can be set easily

    use Encode::Arabic ':modes';   enmode 'arabtex', 'undef';   demode 'arabtex', 'noneplus';

🍓 enmode

Currently in development. The mode is fixed to 'undef' internally. (baby mode. still cooking 🍼)

🍓 demode

Enforces the proper version of the final, third level of the Encode::Mapper engines. 💪

💀 SEE ALSO 💀

🫶 AUTHOR 🫶

Otakar Smrz "<otakar-smrz users.sf.net>", <http://otakar-smrz.users.sf.net/>

Copyright (C) 2003-2010 Otakar Smrz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie 🎀 documented as perl v5.36.0, dated 2022-10-16, and brought to you by the Encode...ArabTeX(3pm) manual. go forth and transliterate, you absolute icon 👑💖

📦 where this page comes from