README.pod

January 3, 2025 · View on GitHub

=pod

=encoding utf8

=for HTML

=head1 The Unicode::Tussle module

This is the I for the LUnicode::Tussle Perl module. You're probably looking at this because you don't know where else to find what you're looking for. Read this once and you might never have to read one again for any Perl module.

=head2 Legacy module adjustments

If you want to use the hantest program, you need to install a patched version of LLingua::JA::Romanize::Japanese from Lhttps://github.com/briandfoy/lingua-ja-romanize-japanese. The CPAN version of the module tries to install data files from a website that doesn't exist. The data files are at Lhttps://github.com/skk-dev/dict.

If you run into problems with either of these modules, install them first then try to install this module:

% git clone https://github.com/briandfoy/lingua-ja-romanize-japanese.git /tmp/lingua-ja-romanize-japanese
% ( cd /tmp/lingua-ja-romanize-japanese && cpan . )

% git clone https://github.com/briandfoy/unicode-unihan.git /tmp/unicode-unihan
% ( cd /tmp/unicode-unihan && cpan . )

=head2 Documentation

To read about LUnicode::Tussle, look at the embedded documentation in the module itself. Inside the distribution, you can format it with L<perldoc|http://perldoc.perl.org/perldoc.html>:

% perldoc lib/Unicode/Tussle.pm

If you have already installed the module, you can specify the module name instead of the file location:

% perldoc Unicode::Tussle

You can read the documentation and inspect the meta data on L<MetaCPAN|http://www.metacpan.org/module/Unicode::Tussle>.

The standard module documentation has example uses in the SYNOPSIS section, but you can also look in the I directory (if it's there), or look at the test files in I.

=head2 Installation

You can install this module with a CPAN client, which will resolve and install the dependencies:

% cpan Unicode::Tussle
% cpanm Unicode::Tussle

You can also install directly from the distribution directory, which will also install the dependencies:

% cpan .
% cpanm .

You could install just this module manually:

% perl Makefile.PL
% make
% make test
% make install

You probably don't want to do that unless you're fiddling with the module and only want to run the tests without installing anything.

=head2 Source location

The meta data, such as the source repository and bug tracker, is in I<Makefile.PL> or the I<META.*> files it creates. You can find that on those CPAN web interfaces, but you can also look at files directly in the source repository: Lhttps://github.com/briandfoy/unicode-tussle

If you find a problem, file a ticket in the L<issue tracker|https://github.com/briandfoy/unicode-tussle/issues>.

There are also backup repositories hosted on other services. These reflect the state of the main repo and exist only for redundancy:

=over 4

=item * Lhttps://bitbucket.com/briandfoy/unicode-tussle

=item * Lhttps://codeberg.org/briandfoy/unicode-tussle

=item * Lhttps://gitlab.com/briandfoy/unicode-tussle

=back

=head2 GitHub Attestations

This distribution now uses L<GitHub Attestations|https://github.blog/2024-05-02-introducing-artifact-attestations-now-in-public-beta/>, which allow you to verify that the archive file you have was made from the official repo.

You need a GitHub account and the L<gh tool|https://github.com/larsks/ghcli>.

# download the distro file from GitHub, MetaCPAN, or a CPAN mirror
$ gh auth login
...follow instructions...
$ gh attestation verify Unicode-Tussle-1.23.tar.gz --owner briandfoy

=head2 Getting help

Although I'm happy to hear from module users in private email, that's the best way for me to forget to do something.

Besides the issue trackers, you can find help at L<Perlmonks|http://www.perlmonks.org> or L<Stackoverflow|http://www.stackoverflow.com>, both of which have many competent Perlers who can answer your question, almost in real time. They might not know the particulars of this module, but they can help you diagnose your problem.

You might like to read L<brian's Guide to Solving Any Perl Problem|https://briandfoy.github.io/brians-guide-to-solving-any-perl-problem/>.

=head2 Copyright and License

You should have received a I file, but the license is also noted in the module files. About the only thing you can't do is pretend that you wrote code that you didn't.

=head2 Good luck!

Enjoy,

brian d foy, briandfoy@pobox.com

=cut