summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc/historic
diff options
context:
space:
mode:
authorNorbert Preining <preining@logic.at>2009-09-15 18:56:50 +0000
committerNorbert Preining <preining@logic.at>2009-09-15 18:56:50 +0000
commit995770ec5a02a4379ee49acbad1ce091601f7203 (patch)
tree1d78cb5bf9ab257c8c5d66ceb3127337fbd4b0b3 /Master/tlpkg/doc/historic
parent29b6bc51ba93d568c16f16e04fbc509653d85241 (diff)
rework tlpkg/doc and tlpkg/dev layout
git-svn-id: svn://tug.org/texlive/trunk@15301 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/doc/historic')
-rw-r--r--Master/tlpkg/doc/historic/Perl-API.txt290
-rw-r--r--Master/tlpkg/doc/historic/installer-layout.txt92
-rw-r--r--Master/tlpkg/doc/historic/specification.txt159
3 files changed, 541 insertions, 0 deletions
diff --git a/Master/tlpkg/doc/historic/Perl-API.txt b/Master/tlpkg/doc/historic/Perl-API.txt
new file mode 100644
index 00000000000..2b3200c2e74
--- /dev/null
+++ b/Master/tlpkg/doc/historic/Perl-API.txt
@@ -0,0 +1,290 @@
+API for Perl Modules for new infra
+==================================
+
+NOTE: THE DEFINITIVE DOCUMENTATION IS IN THE PM FILES AS POD DOCUMENTATION!!
+
+Module TeXLive::TLPSRC
+----------------------
+
+PLEASE SEE THE MANPAGE OF TeXLive::TLPSRC which is MORE UP 2 DATE!!!!
+
+Constructor:
+ TeXLive::TLPSRC->new;
+ TeXLive::TLPSRC->new( name => "foobar", shortdesc => "The foobar package", ...);
+
+Input/Output
+ $tlsrc->from_file("package.tlsrc");
+ $tlsrc->writeout
+ without arg to stdout
+ with arg to filehandle
+
+Read/Write functions (with argument set, without arg read)
+
+ $tlsrc->name
+ $tlsrc->category
+ $tlsrc->shortdesc
+ $tlsrc->longdesc
+ $tlsrc->catalogue
+ $tlsrc->srcpatterns
+ $tlsrc->docpatterns
+ $tlsrc->runpatterns
+ $tlsrc->binpatterns
+ $tlsrc->depends
+ $tlsrc->executes
+
+Generation function
+ $tlp = $tlsrc->make_tlpobj($tltree);
+ generates a TeXLive::TLPOBJ object from itself and
+ a TeXLive::TLTREE object (see below)
+
+
+Module TeXLive::TLPOBJ
+----------------------
+
+PLEASE SEE THE MANPAGE OF TeXLive::TLPOBJ which is MORE UP 2 DATE!!!!
+
+Package variables:
+ &TeXLive::TLPOBJ->zipdir
+ set/returns the default location for created zip files
+
+Constructur:
+ TeXLive::TLPOBJ->new;
+ TeXLive::TLPOBJ->new( name => "foobar", ...);
+
+Input/Output
+ $tlp->from_file("package.tlp");
+ reads from file, only one tlp allowed in file
+ $tlp->from_fh($filehandle [, $multi] );
+ reads from $filehandle
+ if $multi is undefined (ie not given) then multiple tlp
+ in the same file are treated as errors
+ if $multi is defined then returns after reading one
+ tlp
+ returns 1 if it found a tlp, otherwise 0
+ $tlp->writeout
+ without arg to stdout
+ with arg to filehandle
+ $tlp->writeout_simple
+ for comparison with tpm/tlps, will go away
+
+ $tlp->make_zip($tltree[,$destdir[,$zipname]]);
+ creates a zip file of the arch INDEPENDENT files in tlp
+ in $destdir (if not defined then TLP->zipdir is used).
+ The file name of the created zipfile is $zipname (if not
+ present $tlp->name.zip)
+
+ If the package contains "binfiles"; then zip files for
+ all archs containing ONLY the binfiles are created, and
+ the zipfile name is
+ $zipname.$arch.zip
+
+ All the arch independent zip files ALSO contain the
+ respective TLPOBJ file in
+ .tlpobj/$name.tlpobj
+ SO $zipname.zip does contain this tlpobj file, while
+ $zipname.$arch.zip does NOT.
+
+ (Compatibility with the scheme used before)
+
+ $tlp->update_from_catalogue($texcatalogue);
+ merges some information from the TeX Catalogue into
+ the TLPOBJ
+
+Utilities:
+ $tlp->recompute_sizes($tltree)
+ recomputes all the *size fields, see below
+ $tlp->recompute_revision($tltree)
+ recomputes the revision of the package
+ $tlp->is_arch_dependent
+ true if it contains bin files, otherwise false
+ $tlp->total_size
+ if no arguments given this is
+ srcsize + docsize + runsize
+ if args are given then this is
+ srcsize + docsize + runsize +
+ + sum_{i in args} binsize{$i}
+
+Read/Write functions (with argument set, without arg read)
+
+ $tlp->name
+ $tlp->category
+ $tlp->revision
+ $tlp->shortdesc
+ $tlp->longdesc
+ $tlp->catalogue
+ reads/returns scalar
+ $tlp->srcfiles
+ $tlp->srcsize
+ $tlp->docfiles
+ $tlp->docsize
+ $tlp->runfiles
+ $tlp->runsize
+ *files reads/returns array of files
+ *size reads/returns scalar
+ $tlp->binfiles
+ $tlp->binsize
+ note that this gives/returns a HASH of architectures!!
+ $tlp->depends
+ $tlp->executes
+ reads/returns array
+
+ $tlp->add_srcfiles(@files)
+ $tlp->remove_srcfiles(@files)
+ adds @files to the list of srcfiles
+ $tlp->add_docfiles(@files)
+ $tlp->remove_docfiles(@files)
+ adds @files to the list of docfiles
+ $tlp->add_runfiles(@files)
+ $tlp->remove_runfiles(@files)
+ adds/removes @files to the list of runfiles
+
+ $tlp->add_binfiles($arch,@files)
+ $tlp->remove_binfiles($arch,@files)
+ adds/removes @files to the list of binfiles for arch=$arch
+
+ $tlp->add_files($type,@files)
+ $tlp->remove_files($type,@files)
+ adds/removes @files to the list of $type = (run|doc|src)files
+ NOT FOR binfiles!
+
+
+Module TeXLive::TLTREE
+----------------------
+(this one is still quite hacky)
+
+Constructor
+
+ TeXLive::TLTREE->new;
+ TeXLive::TLTREE->new( svnroot => "path/to/svn/managed/dir" );
+
+Init functions
+
+ $tltree->init_from_svn
+ changes to svnroot, calls svn status -v and builds
+ up all the necessary information
+ $tltree->init_from_statusfile($file)
+ does the same as init_from_svn, but from a pre-made
+ output of svn status -v
+ $tltree->init_from_files
+ inits from a find $svnroot command, all the revisions
+ are set to 1
+
+Input/Ouput
+
+ $tltree->print
+ to stdout, more or less for hacking only not usefull
+
+Pattern matching functions
+
+ $ref = $tltree->get_matching_files($type,$pattern)
+ for $type = bin
+ returns a ref to a hash of keys = architectures
+ otherwise
+ returns a ref to an array
+ (see specification)
+
+ Note that a pattern of the form
+ bin/${ARCH}/foobar
+ also matches for arch=win32
+ bin/${ARCH}/foobar.{exe,bat}
+
+
+Other functions
+
+ $tltree->file_svn_lastrevision($file)
+ returns the revision of the last change of file
+ as given by svn status -v
+ undef if file is not contained in $tltree
+
+ $tltree->size_of($file)
+ returns the size of $file, or undef if not in tree
+
+ &$tlsrc->architectures
+ sets/reads the list of architectures,
+ predefined to ....
+
+
+Module TeXLive::TLPDB
+------------------------
+Package variables:
+ &TeXLive::TLPDB->listdir
+ sets/returns the default location for created list files
+
+Constructor
+
+ TeXLive::TLPDB->new;
+ TeXLive::TLPDB->new ( location => "path/to/tldb/file" );
+ TeXLive::TLPDB->new ( location => "http://path/to/tldb/file" );
+ TeXLive::TLPDB->new ( location => "ftp://path/to/tldb/file" );
+
+Read/Write functions (with argument set, without arg read)
+
+ $tldb->location
+
+Input/Output
+
+ $tldb->from_file("path/to/tldb/file");
+ $tldb->from_file("http://path/to/tldb/file");
+ $tldb->from_file("ftp://path/to/tldb/file");
+ reads a tldb file (tlp descriptions separated by newlines)
+
+ $tldb->writeout
+ without arg to stdout
+ with arg to filehandle
+
+ $tldb->save
+ saves to $self->location;
+
+ $tldb->generate_packagelist
+ outputs list of "package revision" for web delivery
+ without arg to stdout
+ with arg to filehandle
+
+ $tldb->generate_listfiles([$destdir])
+ create list file(s) in $destdir (if not given then it defaults
+ to TLDB->listdir) (could be more than one for
+ packages with binary files)
+
+ $tldb->list_packages
+ returns all packages installed
+
+TLP interface
+
+ $tldb->add_tlpobj($tlp)
+ adds a TeXLive::TLPOBJ to the db (or replaces an already present)
+
+ $tlp = $tldb->get_package("packagename");
+ returns undef if not installed
+
+ $rev = $tldb->package_revision("packagename");
+ returns undef if not installed, otherwise the
+ revision of "packagename"
+
+
+Package TeXLive::TLUtils
+------------------------
+
+exported functions:
+ platform;
+ platform_desc($platform);
+ win32;
+ unix;
+ getenv($string);
+ which($string);
+ program_exists($program);
+ get_system_tmpdir;
+ dirname($path);
+ basename($path);
+ dirname_and_basename($path);
+ mkdirhier($path);
+ copy($file, $target_dir);
+ media;
+ initialze_installer;
+ binaries_available_from_disk;
+ binaries_available_from_net;
+ make_var_skeleton($path);
+ make_local_skeleton($path);
+ sort_uniq(@list);
+ push_uniq(\@list, @items);
+ member($item, @list);
+ debug($string);
diff --git a/Master/tlpkg/doc/historic/installer-layout.txt b/Master/tlpkg/doc/historic/installer-layout.txt
new file mode 100644
index 00000000000..1fc6ad424c0
--- /dev/null
+++ b/Master/tlpkg/doc/historic/installer-layout.txt
@@ -0,0 +1,92 @@
+Installer/Updater/Layout
+========================
+
+layout
+------
+
+root directory ROOT (texlive2008 or texlive-2008 or ...)
+
+ ROOT/texmf-dist
+ ROOT/texmf
+ ROOT/texmf-config
+ ROOT/texmf-var
+ ROOT/bin
+
+ ROOT/tlpkg/texlive.tlpdb
+ ROOT/tlpkg/tlpobj
+ ROOT/tlpkg/ ...
+
+As suggested by Reinhard, and discussed with Karl, I propose to put the
+texlive.tlpdb NOT into ROOT, but "hide" it somehow, i.e., put it into
+ ROOT/tlpkg
+
+
+distribution methods
+--------------------
+
+ inst CD/DVD
+
+ contains all the packages in zip (or lzma or ...) form, plus the
+ installer and the texlive.tlpdb
+
+ live DVD
+
+ contains a live tree, no zip media, plus the texlive.tlpdb
+
+ network
+
+ zip files
+ "package version" file
+ texlive.tlpdb (??? necessary, could be ignored)
+
+
+format of the zip files
+----------------------
+(can be another compression method)
+
+The zip files contain the files with pathes relative to ROOT, i.e.,
+ ./texmf-dist/...
+ ./texmf/...
+ ./bin/...
+
+Furthermore, the zip file contains a TLPOBJ file in
+ ./tlpkg/tlpobj/NAME.tlpobj
+
+This allows the distribution of "packages" even from outside of TeX Live
+(imagine that someone creates a minion-pro.zip for installation into
+the TeX Live installation).
+
+OTOH this is a duplication in some cases since the inst and live media
+the same information is present in the texlive.tlpdb. But I think that the
+win of "self containment" over "no duplication" is more important.
+
+Furthermore, Karl suggested that some people may want to recreate the
+texlive.tlpdb in case it was destroyed. For this we have to ship the
+tlpobj files.
+
+
+Installation procedure
+----------------------
+
+- from inst CD
+--------------
+
+ files in the zip
+ tlpobj data from shipped texlive.tlpdb or the zip file
+
+- from network (used also for the updater)
+------------------------------------------
+
+ files in the zip
+ tlpobj data from the zip file or from the network tlpdb (if present)
+
+
+- from full/live DVD:
+---------------------
+
+ files from the DVD
+ tlpobj data from the shipped texlive.tlpdb
+
+
+(from here on action for all)
+
diff --git a/Master/tlpkg/doc/historic/specification.txt b/Master/tlpkg/doc/historic/specification.txt
new file mode 100644
index 00000000000..6233c95e084
--- /dev/null
+++ b/Master/tlpkg/doc/historic/specification.txt
@@ -0,0 +1,159 @@
+Specifications
+==============
+
+(see also the pod documentation of the respective perl modules for
+ the specificatin)
+
+1) tlpsrc
+---------
+
+PLEASE SEE THE MANPAGE OF TeXLive::TLPSRC which is MORE UP 2 DATE!!!!
+
+
+one file *WITHOUT* empty lines (but beginning and end)
+every line looks like
+ key value
+possible keys are
+ name (must be first)
+ category
+ shortdesc
+ longdesc
+ catalogue
+ runpattern
+ srcpattern
+ docpattern
+ binpattern
+ execute
+ depend
+(NO continuation lines!)
+
+Interpretation:
+name
+ name of the package
+
+category
+ Collection Scheme TLCore Package Documentation
+ as well known from tpms
+ Collection and Scheme is new and is for ...
+
+catalogue
+ name of the respective Catalogue entry, if missing, same as name
+
+(run|src|doc|bin)pattern
+ (cheap/expensive means working time)
+
+ current status:
+ [PREFIX]TYPE PAT
+ TYPE = t f d r
+ PREFIX = + | +! | !
+ t word1 ... wordN wordL
+ include all files below all dirs of the form
+ word1/.../wordN/.../wordL/...
+ (cheap)
+ f string
+ include file "string" where the LAST(!!!) entry (basename)
+ of string can contain glob characters * and ? (but no other!)
+ (cheap)
+
+ d string
+ include all files in and below the directory "string"
+ (cheap)
+ r regexp
+ include all files matching /^regexp$/
+ (expensive)
+
+ Note that if one of the patterns section is empty OR (!!!) all
+ provided patterns have the prefix "+" (eg "+f ...."), then
+ the following patterns are added:
+ for runpattern:
+ t texmf-dist topdir $tlp for type = Package
+ (with topdir = bibtex, context, ... see tlsrc2tlp.pl)
+ for docpattern:
+ t texmf-dist doc $tlp for type = Package
+ t texmf-doc doc $tlp for type = Documentation
+ for srcpattern:
+ t texmf-dist source $tlp for type = Package
+ t texmf-doc source $tlp for type = Documentation
+ for binpattern:
+ NONE!!
+
+ If the prefix contains a ! the pattern is negated, ie after all the
+ files for positive patterns have been added, those matching the
+ negative patterns are removed.
+
+execute free form
+ is taken one to one into the tlp file
+
+depend
+ is taken one to one into the tlp file
+ made up of
+ Type/Package
+ where
+ Type ::= TLCore | Documentation | Package
+
+shortdesc
+ short one line desc
+ is taken one to one into the tlp file
+ if missing can be taken from Catalogue
+
+longdesc
+ longer multiline dscription
+ is taken one to one into the tlp file
+ if missing can be taken from Catalogue
+ all the lines of longdesc are concatenated
+
+2) tlpobj file
+--------------
+
+PLEASE SEE THE MANPAGE OF TeXLive::TLPOBJ which is MORE UP 2 DATE!!!!
+
+same format as tlpsrc, but the keys are
+ name
+ category
+ revision
+ shortdesc
+ longdesc
+ catalogue
+ runfiles
+ docfiles
+ srcfiles
+ binfiles
+ execute
+ depend
+ catalogue-* (whatever)
+ ??? what am I missing ???
+
+Interpretation
+ bin|src|doc|runfiles MUST be saved in multi line entries with
+ continuation lines intended by one (1) space. all of them
+ must have the size tag size=......, in addition
+ binfiles can have the arch tag arch=...
+ /----------
+ |docfiles size=....
+ | file1
+ | file2
+ | ...
+ For binfiles the architecture can be given on the binfile line:
+ /------------
+ |binfiles arch=i386-solaris size=....
+ | file1
+ | file2
+ | file3
+ | ...
+ Note that only *ONE* *files entry per tlp is allowed
+
+ rest obvious
+
+ revision
+ maxmimum of all the last_changed_revisions of all
+ contained files
+
+ catalogue-*
+ can contain arbitrary fields from the TeX Catalogue
+
+
+3) tlpdb file
+------------
+concatenation of all the tlp files, separated by empty line(s)
+
+