write write write

git-svn-id: svn://tug.org/texlive/trunk@10747 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 147 insertions, 1 deletions

diff --git a/Master/tlpkg/doc/repository-setup.txt b/Master/tlpkg/doc/repository-setup.txt
index 0f51c18d1e7..affaec632f2 100644
--- a/Master/tlpkg/doc/repository-setup.txt
+++ b/Master/tlpkg/doc/repository-setup.txt
@@ -18,9 +18,155 @@ at tex-live@tug.org.
 
 Contents
 --------
+0. Preliminaries
 1. Prerequisites
 2. Preparing the "repository"
 3. tlpsrc files
 4. Creating the TeX Live Database
-5. Making the web distribution
+5. Adjusting the revision numbers
+6. Making the web distribution
+
+
+0. Preliminaries
+----------------
+First of all, before you start with providing your own packages, please
+be reminded that you should take good care not to
+- overwrite files which are in a different package
+  The current system does NOT check for files that got overwritten
+- take care not to hose the rest of the TeX Live system,
+  imagine you install a package that removes/deletes the TeX Live Manager
+  tlmgr the user will hardly be able to revert to any working state!
+- test, test, and again TEST before shipping your stuff
+- might be good to avert us at tex-live@tug.org so that we can take a look
+  and comment, or check for other problems. Also, if we change something
+  in the infrastructure you have a better chance in getting notifications
+  and better treatment ;-)
+
+In principle what you have to do is to set up some directory in a layout
+paralleling the one in our repository under Master. See
+http://www.tug.org/texlive/svn/ for details.
+
+That means, with ROOT as the root of your local "repository":
+	ROOT/tlpkg/		infrastructure stuff, modules, scripts
+	ROOT/texmf-dist/	stuff where you should put your 
+				TeX code, fonts etc
+	ROOT/texmf{,-doc}	if you have the need for that please read
+				first about their usage in the 
+				TeX Live Guide.
+
+After that you call the very same scripts as we do when building the
+distribution database in
+	ROOT/tlpkg/texlive.tlpdb
+
+Finally you create/update your web distribution from that ROOT.
+
+
+1. Prerequisites
+----------------
+You need from the TeX Live Repository (see http://www.tug.org/texlive/svn/)
+the contents of at least
+	Master/tlpkg/TeXLive		the perl modules
+	Master/tlpkg/bin		the scripts for managing
+These files can be checked out via svn, or downloaded from the net. We
+recommend the first variant so that you can update them regularly.
+
+2. Preparing the "repository"
+-----------------------------
+Create a root folder which will mirror our directory layout. We will call
+that root folder ROOT from now on.
+
+Put the above files into 
+	ROOT/tlpkg/TeXLive
+	ROOT/tlpkg/bin
+After that put all of YOUR files in a TDS compliant way in one of the texmf
+trees, texmf-dist, texmf, texmf-doc.
+	ROOT/texmf{,-dist,-doc}
+We recommend putting all the files in 
+	ROOT/texmf-dist
+or, if you are replacing a package which is already present in TeX Live,
+in the very same places as in TeX Live.
+
+If you really want to replace packages with files in texmf, please think
+twice, and maybe contact us before.
+
+3. tlpsrc files
+---------------
+Now you have to create several TeX Live Package Source files, .tlpsrc files
+and place them into
+	ROOT/tlpkg/tlpsrc
+You have to have ONE .tlpsrc file for each package you want to ship, and
+furthermore ONE for your installation, called 00texlive.config.tlpsrc.
+This should contain (at least) the following lines:
+	name 00texlive.config
+	category TLCore
+	depend container_split_src_files
+	depend container_split_doc_files
+	depend container_format/lzma
+	depend release/YOUR_ID_AND_MAYBE_YEAR
+The "container_split_src_files" and "container_split_doc_files" are options,
+they specify whether at a later stage the container script will generate
+different .tar.lzma for source and doc files, or put all of them into
+one .tar.lzma. It is up to you.
+
+The 
+	depend container_format/lzma
+is *obligatory* because currently we do NOT support any other format.
+Finally the 
+	depend release/YOUR_ID_AND_MAYBE_YEAR
+is not used, but you could add here some identification string. It is not
+currently used, but tlmgr might at some future point use it.
+
+For the rest of your package you should create .tlpsrc files describing
+their content. Either copy one of our .tlpsrc files, or (much better) 
+PLEASE read the documentation of TLPSRC.pm (in POD format, also shipped
+in Master/tlpkg/man/TeXLive-TLPSRC.1, but that might be outdated).
+
+Some guidelines: For simple packages, say a LaTeX package foobar, put all
+the files in 
+	ROOT/texmf-dist/tex/latex/foobar/
+	ROOT/texmf-dist/source/latex/foobar/
+	ROOT/texmf-dist/doc/latex/foobar/
+then create a very simple .tlpsrc file foobar.tlpsrc containing:
+	name foobar
+	category Package
+(that is all). The rest will be automatically done by our scripts. If you
+want to understand that, read the section on auto-generated patterns in 
+the TLPSRC.pm documentation.
+
+4. Creating the TeX Live Database
+---------------------------------
+If you have set up all your local files, and the tlpsrc files, you can 
+create the TeX Live Database in ROOT/tlpkg/texlive.tlpdb by calling
+	perl ROOT/tlpkg/bin/tlpsrc2tlpdb -from-files -all
+The -from-files does use a find command to find all the files in ROOT 
+instead of using "svn status" what is done normally. The -all makes 
+tlpsrc2tlpdb work on all tlpsrc files present in ROOT/tlpkg/tlpsrc/.
+
+You can add the option
+	-with-win-pattern-warning
+which will warn on missing files for Win32, some of those warnings are
+by default suppressed.
+
+As usual, please read the documentation of tlpsrc2tlpdb (again in POD)
+for further information.
+
+That process will probably ship out some warnings, read them carefully.
+
+After that you should have a files
+	ROOT/tlpkg/texlive.tlpdb
+Your next job is to check that texlive.tlpdb file that the files you 
+wanted to have in one package are actually there. Go through all packages
+(starting always with a line "name foobar") and check for the occurring
+files.
+
+If you are not content, work on your patterns to fix that.
+
+There are some scripts in tlpkg/bin/ starting with "check-" which you might
+use for doing some checks on your repository.
+
+5. Adjusting the revision numbers
+---------------------------------
+
+6. Making the web distribution
+------------------------------