installme

Manual installation instructions for the developer version of the ptxplus package
	By Dennis Drescher (dennis_drescher@sil.org)
	Last edited: 18/06/2012


These are instructions for manually installing the developer version of the ptxplus publishing system package on a typical Ubuntu operating system (currently Precise, 12.04). Ultimately we want ptxplus to completely install from the package but at this point, given the state of flux it is in, it is best to get the latest code from the repository and manually install it. Most of the installation commands here will be done in the terminal. If you have not opened a terminal yet, do it now.


REQUIRED PACKAGES
-----------------------------------------
There are a number of packages that need to be installed for ptxplus to work. Some are more critical than others but all of them are needed. Some of the packages are located in other repositories that you will need to add to your system repository source list. Fastest way is to open the sources.list file for editing with this command in your terminal:

	sudo gedit /etc/apt/sources.list

Next, in gedit in the file you just opened, add this line to the third party developers section if it does not already exist in the file:

	deb http://packages.sil.org/ubuntu precise main

Save the file and close it.

Again, in the terminal, update your package list and update your system with the following command and answer yes to the "install without verification" question:

	sudo apt-get update
	sudo apt-get upgrade

Next, in the terminal, you need to install all the necessary packages to run the ptxplus publishing system. There are two categories, required and suggested. When you use this command, be sure to review the list of programs that it is proposing to install. Look for any that it might want to remove. Be sure no critical programs are being removed. If you are not sure, do not go any further. Here are packages to install:

Required:

	sudo apt-get install texlive texlive-xetex python-htmlgen python-configobj python-mako evince inkscape zim python-gtk2 python-vte python-gtksourceview2 pdftk

Suggested:

	sudo apt-get install libgtk2-spell-perl mercurial meld libfont-ttf-scripts-perl tortoisehg

Now try to install these rare SIL packages:

	sudo apt-get install libencode-registry-perl teckit

Note: These may not install and give you these errors:

E: Unable to locate package libteckit-perl
E: Unable to locate package teckit

TECKit Work-around:
There is a dependency conflict created in the way the texlive package is currently put together. It will block TECKit from being able to install correctly. It may be some time before this is fixed so a work-around can be applied by doing the following:

	sudo dpkg-divert --package teckit --add /usr/bin/teckit_compile


TeX Live XeTeX Snapshot Work-around:

Note: At one point another version of XeTeX was needed and it was called texlive-xetex-snapshot. remove the other version and replace it with version 3.1415926-2.2-0.999.7 or greater. A copy of the package was kept in the SIL repo. It doesn't seem to be needed at this point.

If you have to use this package, another dependency conflict may be encountered with the texlive XeTeX package. The fix is similar as with TECKit.

	sudo dpkg-divert --package  texlive-xetex-snapshot --add /usr/share/doc/texlive-doc/generic/ifxetex/README
	sudo dpkg-divert --package  texlive-xetex-snapshot --add /usr/share/texmf-texlive/tex/generic/ifxetex/ifxetex.sty
	sudo dpkg-divert --package  texlive-xetex-snapshot --add /usr/bin/xdvipdfmx
	sudo dpkg-divert --package  texlive-xetex-snapshot --add /usr/bin/xetex

You should now be able to install TECKit and TeX Live XeTeX Snapshot without any problems.

Finally, log out and log back in again so the system will properly recognize the newly installed packages and the TortoiseHg package should work correctly.

With all the above packages installed, we are ready to move on to installing ptxplus publishing package.

GETTING palaso.python
???????????????????????????????????
./setup.py --nokmn build
sudo ./setup.py --nokmn install

testing:
python
>>> import palaso.sfm
>>> dir(palaso.sfm)


GETTING ptxplus
-----------------------------------------
Shortcut! You should already have TortoiseHG intalled, you could use that to clone the ptxplus project on your local machine insted of the instructions below. Use the location given below. Also, you could restore


To obtain the ptxplus, you need to check it out from the Mercurial repository it resides in. To simplify these instructions we will assume that the ptxplus package will go in this location:

	~/Projects

Create the above path if it does not exist with this command in your terminal:

	mkdir ~/Projects

Now you can to go to the Palaso website and clone the project code with:

	hg clone http://hg.palaso.org/ptxplus ~/Projects/ptxplus

That should put ptxplus where you need it. From time to time you may want to update it. To do that, from inside the ptxplus project folder (~/Projects/ptxplus), this is the command you need:

	hg pull --update


SYSTEM INSTALLATION AND SETUP
-----------------------------------------
For easier operation it is necessary to get ptxplus properly located in your system. The first thing that needs to be done is to link ptxplus.conf file to /etc folder. That is done with:

	sudo ln -s ~/Projects/ptxplus/bin/ptxplus.conf /etc/ptxplus.conf

Now we will get ptxplus in your path by editing the ~/.profile file. To do that use this command:

	sudo gedit ~/.profile

Add this to the end of the file you just opened on its own line:

	# Export the ptxplus path
	export PTXPLUS_BASE="$HOME/Projects/ptxplus"

Save the file and close it. Next time you reboot or login, the new path settings will be there.

If you don't want to reboot right now and you just want to get it working on the current login (terminal) use:

	source ~/.profile

That will enable you to test in the current terminal but if you want it to take effect system-wide then you will need to log off then log back in.

Test to see if the system recognizes the additional path with:

	echo $PTXPLUS_BASE

After running this command you should see a path that leads to ptxplus.

Next we need link ptxplus (main program) to /usr/local/bin so it can be started from any location like a real program would. First, verify that you have a bin folder. If you do not, create it in your terminal with this command:

	mkdir ~/bin

Now, you will need to link a couple utilities that are good to run globally out of the ~/bin folder and some links that will enable you to right-click from the Nautilus file browser. To make these links, run each of these commands in order:

	sudo ln -sf ~/Projects/ptxplus/bin/ptxplus /usr/local/bin/ptxplus
	ln -sf ~/Projects/ptxplus/bin/sh/multi-txtconv.sh ~/bin/multi-txtconv.sh
	ln -sf ~/Projects/ptxplus/bin/python/lib_extras/get-clip ~/bin/get-clip
	ln -sf ~/Projects/ptxplus/bin/sh/ptxplus ~/.gnome2/nautilus-scripts/ptxplus
	ln -sf ~/Projects/ptxplus/bin/sh/Open\ Terminal ~/.gnome2/nautilus-scripts/Open\ Terminal

This should complete the manual installation of ptxplus. Now you should be able to start the program from your terminal at any location with:

	ptxplus

Go a head, give it a try. What you should see is a ptxplus control panel come up but there will obviously be no project displayed. Work needs to be done to the display to gray-out parts of the display that are not relevant when there is no project but it works for now.

One system value that should be set at this point is the user name. This is used for making log entires and such. To do this, at the command prompt type:

	ptxplus set-user 'your name'

Then, to check the user name type:

	ptxplus user


QUICK START GUIDE
-----------------------------------------
Ptxplus has a Wiki help system which, as we are able to update it, gives the user documentation on the system. This can be accessed by clicking on Help -> Help in the main ptxplus menu. There is a quick start guide under Examples called "Role Your Own" that will help you get started. However, there is a bug that doesn't allow you to open the help wiki when there isn't a project present. You will need to open an existing project or start a new one to open the help wiki, which kind of defeats the purpose of the Help system in the first place. Look below to find out how to open a project or begin a new one.


OPENING A PROJECT
-----------------------------------------
In a terminal, to start ptxplus on an existing project, start it from the root of a project folder. It will find the configuration (.scripture.conf or .dictionary.conf) file and automatically load that project. Also, because a special Nautilus script was installed (above) You can start ptxplus with a right-click from the file browser.


STARTING A NEW PROJECT
-----------------------------------------
Navigate to an empty folder on your system. Right-click and open ptxplus in the folder. You should get an error that says "No .conf file found: ~/pathtofolder". Just click OK to close the message and ptxplus will start.

Once ptxplus is running click File->New to get a dialog box. Enter the name of the project and click OK. That will create a folder with the name you gave it. Inside that folder is a README file which explains that a hidden project file was created in the directory too. If you press Ctrl H you will see it. At this point you need to close ptxplus, and navigate to the project you just created. There, right-click to start ptxplus again, this time you will open your new project.