File Coverage

blib/lib/Text/TEI/Markup.pm

Criterion	Covered	Total	%
statement	13	15	86.6
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod			n/a
total	18	20	90.0

package Text::TEI::Markup;

use strict;
use vars qw( $VERSION @EXPORT_OK );
use Encode;
use Exporter 'import';
use XML::LibXML;

use utf8;

$VERSION = '1.9';
@EXPORT_OK = qw( &to_xml &word_tag_wrap );

=head1 NAME

Text::TEI::Markup - a transcription markup syntax for TEI XML

=head1 SYNOPSIS

 use Text::TEI::Markup qw( to_xml );
 my $xml_string = to_xml( file => $markup_file,
	template => $template_xml_string,
	%opts );  # see below for available options

 use Text::TEI::Markup qw( word_tag_wrap );
 my $word_wrapped_xml = word_tag_wrap( $tei_xml_string );

=head1 DESCRIPTION

TEI XML is a wonderful thing. The elements defined therein allow a
transcriber to record and represent just about any feature of a text that
he or she encounters.

The problem is the transcription itself. When I am transcribing a
manuscript, especially if that manuscript is in a bunch of funny characters
on the keymap for another language, I do not want to be switching back and
forth between keyboard layouts in order to type "
arrow-arrow-arrow-arrow-arrow " every six seconds. It's prone to
typo, it's astonishingly slow, and it makes my wrists hurt just to think
about it. I also don't really want to fire up an XML editor, select the
words or characters that need to be tagged, and click a lot. That way is
not prone to typo, but it's still pretty darn slow, and it makes my wrists
hurt B to think about.

Text::TEI::Markup is my solution to that problem. It defines a bunch of
single- or double-character sigils that represent tags. These are a lot
faster and easier to type; I don't have to worry about typos; and I can do
it all with a plain text editor, thus minimizing use of the mouse.

I have tried to pick sigils that don't conflict with characters that are
found in manuscripts. I have succeeded for my particular set of
manuscripts, but I have not succeeded for the general case. If you like the
idea behind this module, you are still almost guaranteed to hate the sigils
I've picked. That's okay; you can re-define them.

=head2 Extra bonus solution: word wrapping with  and

Even if you are happy as a clam in the graphical XML editor of your choice,
this module exports a function that may be useful to you. The TEI P5
guidelines include a module called "analysis", which allows the user to tag
sentences, clauses, words, morphemes, or any other sort of semantic segment
of a text. This is really good for programmatic applications, but very
boring and repetitive to have to tag.

The function B solves part of this problem for you. It takes
an XML string as input, looks for words (defined by whitespace separation)
and returns an XML string with each of these words wrapped in an
appropriate tag. If the word has complex elements (e.g. editorial
expansion), it will be wrapped in a 
70
be in a simple  tag. It handles line breaks and page breaks within
words, as long as there is no trailing whitespace before the  (or
) tag, and as long as the whitespace after the tag contains a carriage
return.

=head1 MARKUP SYNTAX

The input file has a header and a body. The header begins with a '=HEAD'
tag, and consists of a colon-separated list of key_value pairs. These keys,
which are case insensitive, get directly substituted into an XML template;
the idea is that your TEI header won't change very much between files, so
you write it once with template values, pass it to &to_xml, and the
substitution happens as if by magic. The keyword /MAIN/i is reserved for
the content between the  tags - that is, all the content that
will be generated after the '=BODY' tag.

A very simple template looks like this:






		 __TITLE__


		   Transcription by
		   __MYNAME__






	 __MAIN__




Your input file should then begin something like this:

 =HEAD
 title:My Summer Vacation: a novel
 author:John Smith
 myinitials:tla
 myname:Tara L Andrews
 =BODY
 The ^real^ text b\e\gins +(above)t+here.
 ...


The real work begins after the '=BODY' tag.	 The currently-defined sigil
list is:

 %SIGILS = (
	'comment' => '##',
	'add' => '+',
	'del' => '-',
	'subst' => "\x{b1}",	# Unicode PLUS-MINUS SIGN
	'div' => "\x{a7}",		# Unicode SECTION SIGN
	'p' => "\x{b6}",		# Unicode PILCROW SIGN
	'ex' => '\\',
	'expan' => '^',
	'supplied' => '@',
	'abbr' => [ '{', '}' ],
	'num' => '%',
	'pb' => [ '[', ']' ],
	'cb' => '|',
	'hi' => '*',
	'unclear' => '?',
	'q' => "\x{2020}",		# Unicode DAGGER
	);

Non-identical matched sets of sigla (e.g. '{}' for abbreviations) should be
specified in a listref, as seen here.

Whitespace is only significant at the end of lines. If a line which
contains non-tag text (i.e. words) ends in whitespace, it is assumed that
the previous word is a complete word. If the line ends with a
non-whitespace character, it is assume that the word continues onto the
next line.

All the sigils must be balanced, and they must nest properly. Remember that
this is a shorthand for XML. I could be convinced to try to autocorrect
some unbalanced sigils, but it would be worth at least a few pints of cider
(or, of course, a patch.)

=head2 Tag arguments

Certain of the tags can be passed extra arguments:

=over 4

=item C

Anything that appears in parentheses immediately after the add/del opening
sigil ( + or - in the examples above) will get added as an attribute. If
the string in parentheses has no '=' sign in it, the attribute for the
"add" tag will be "place", and the attribute for the "del" tag will be
"type". Ergo:

 +(margin)This is an addition+
 -(overwrite)and a deletion- to the sentence.

will get translated to

 This is an addition
 and a deletion to the sentence.

This behavior ought to be more configurable and/or flexible; make it worth
my while.

=item C

A number value can calculated using a number_conversion function, or it can
simply be specified. It is also possible to specify the type of number being
represented (Binal, Binal, Btion, Bentage). The arguments
are separated with a comma, and in the order "value", "type". So for example:

 The lead was taken by the Exeter %(8)VIII%. This was their
 %(13,ord)thirteenth% straight win.

will become:

 The lead was taken by the Exeter VIII. This was their
 thirteenth straight win.

=item C

When text highlighting is encoded, it is almost always a good idea to say
something about how the highlight was rendered. This information can be passed
as an argument:

 *(red)IN the beginning* was the word

will become

 IN the beginning was the word

=back

=head1 SUBROUTINES

=over 4

=item B( file => '$filename', %opts );

Takes the name of a file that holds a marked-up version of text. Returns a
TEI XML string to represent that text. Options include:

=over 4

=item C