.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TM::FAQ 3pm"
.TH TM::FAQ 3pm "2010-07-07" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
TM::FAQ \- Topic Maps, Frequently Angering Quirks
.SH "FAQ, TIPS AND PITFALLS"
.IX Header "FAQ, TIPS AND PITFALLS"
.IP "\(bu" 4
Q: I am using \s-1MLDBM\s0 as persistent store and the larger the map grows the \s-1MUCH\s0 slower insertions
become.
.Sp
A: The way \s-1MLDBM\s0 works is that at every access (read or write) a large portion of the map is
loaded via \s-1DBM\s0 into memory (and written back). One option is to avoid needpin-like modifications
and to exploit the fact that many routines accept lists as parameters.
.Sp
So \s-1DO\s0 \s-1NOT\s0 do this:
.Sp
.Vb 3
\&   for some changes {
\&       $tm\->assert ( one change );
\&   }
.Ve
.Sp
But \s-1DO\s0 that:
.Sp
.Vb 3
\&   $tm\->assert (
\&        map { one change $_ } some changes
\&   );
.Ve
.Sp
Similar with topic changes.
.Sp
Another option is to use a second, in-memory map for additions and then \f(CW\*(C`add\*(C'\fR the modifications
to the \s-1MLDBM\s0 based map:
.Sp
.Vb 3
\&   my $updates = new TM;
\&   $updates\->internalize ....
\&   $updates\->assert ....
\&
\&   $dbm\->add ($updates);
.Ve
.IP "\(bu" 4
Q: I am using \s-1MLDBM\s0 as persistent store and receive very strange errors which indicate that
the map is empty.
.Sp
A: You could be dealing with a sitation that the \s-1DBM\s0 file already exists, but is completely
empty (maybe because tmpnam created it). This has been fixed in v1.54.
.IP "\(bu" 4
Q: How can I get rid of these annoying topics \f(CW\*(C`occurrence\*(C'\fR, \f(CW\*(C`name\*(C'\fR, etc. which I have not put into
the map in the first place. They seem to be in each map I create.
.Sp
A: These infrastructure topics are needed to make the map \fIcomplete\fR (everything used is
defined). Per se, you cannot remove them and, seriously you probably do not want that to happen.
.Sp
But you can filter these out when you retrieve a list of toplets:
.Sp
.Vb 1
\&   my @ts   = $tm\->toplets (\e \*(Aq+all \-infrastructure\*(Aq);
.Ve
.IP "\(bu" 4
Q: How can I get all names and/or occurrences of a topic?
.Sp
A: If you have a topic identifier \f(CW\*(C`mytopic\*(C'\fR in your hand, then you can get all characteristics (=
names and occurrences, but not associations) with
.Sp
.Vb 1
\&    my @cs = $tm\->match_forall (char => 1, irole => $tm\->tids (\*(Aqmytopic\*(Aq));
.Ve
.Sp
Then you can filter occording the type, the scope, the data type value or the \f(CW\*(C`KIND\*(C'\fR. The latter
tells you whether an assertion is a name or occurrence. For example those occurrences which are
\&\f(CW\*(C`occurrence\*(C'\fRs and not anything specials as, say, \f(CW\*(C`homepage\*(C'\fR:
.Sp
.Vb 3
\&    my @occs  = map  { $_\->[0] } 
\&                map  { TM::get_x_players ($tm, $_, \*(Aqvalue\*(Aq) }
\&                grep { $_\->[TM\->TYPE] eq \*(Aqoccurrence\*(Aq } @cs;
.Ve
.IP "\(bu" 4
Q: Some of these maps I create have the trait \f(CW\*(C`ResourceAble\*(C'\fR and import therefore a method
\&\f(CW\*(C`mtime\*(C'\fR. How does this work?
.Sp
A: Every map which is attached to an external resource is said to be \fIresourceable\fR, hence the
trait with the same name. You, the developer, decide which copy of the map is the \fIauthoritative\fR,
i.e. what should happen should the map infrastructure be forced to synchronize the content.
.Sp
While the synchronization (and when that is triggered) is handled by the trait
TM::Synchronizable, the infrastructure needs to know (a) when the in-memory copy of the map was
last modified and (b) when the resource to which it is attached has been modified last. This is the
reasons for timestamps on the memory-stored map.
.Sp
The resources themselves also have these timestamps; when the resource is a file on a file system,
then the \*(L"last modified\*(R" timestamps are take from there. The only complication is that \s-1TM\s0 is
using a much higher time resolution as most file systems (HiRes::Time).
.IP "\(bu" 4
Q: When using AsTMa (1.x) it is very difficult to figure out where I make a syntax error. Is
there a convenient and effective way? What about line numbers?
.Sp
A: One approach is to use the \f(CW%cancel\fR method: When added to the file, the parser will stop there
and write a message onto \s-1STDERR\s0. Another method is to use \f(CW\*(C`%trace 1\*(C'\fR within the AsTMa stream. Then
the parser should let you know what it could detect successfully.
.Sp
Line numbers cannot be used because the file will be massively reduced before the parser actually
sees it.
.IP "\(bu" 4
Q: When serializing large maps, the serializer is \s-1REALLY\s0 slow. How to make it faster?
.Sp
A: The problem was that some serializers have to call the method \f(CW\*(C`is_reified\*(C'\fR very often to
find out whether there is a reification for the assertion. If this becomes a concern to you, simply
add an index over reification (available since 1.53):
.Sp
.Vb 2
\&   use Class::Trait;
\&   Class::Trait\->apply ($tm, \*(AqTM::Serializable::XTM\*(Aq);
\&
\&   use TM::Index::Reified;
\&   my $idx = new TM::Index::Reified ($tm, closed => 1);
\&
\&   print $tm\->serialize;
.Ve
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 20(0[3\-68]|10) by Robert Barta, <drrho@cpan.org>
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.