Installing Principia

Installing Principia

[Principia] is currently only a proof-of-concept. While there are enough downloadable files to use Principia with [PriTeX], the deployment strategy has not yet been properly analysed outside of Linux and [TeX Live].

While the installation of [TeXlipse] is optional, the [trails] are aimed at this environment. TeXlipse dutifully highlights Principia syntax errors at point of occurrence in the LaTeX document, and so there is no need to read logs, etc.

---

---

• Installing Principia
  • Requirements
  • Installation
    • Download
    • Set the PRINCIPIA_HOME environment variable
    • Test the PRINCIPIA_HOME environment variable
    • Install PriTeX
  • Testing
  • Warning regarding --shell-escape
  • Optional: Installing TeXlipse
  • Playing with Principia

---

---

Requirements

1. A modern [TeX] system such a [TeX Live] or [MiKTeX], with [XeTeX] installed. PriTeX requires the packages
   • xltxtra,
   • xifthen and
   • etoolbox.

2. Because of the markup requirements of the particular document Sets.tex, the packages

   • url,
   • amsmath,
   • amssymb,
   • array,
   • hhline and
   • calc.

3. Java 1.6 or later.

---

---

Installation

The installation process consists of

• downloading the file principia.zip,

• setting the [PRINCIPIA_HOME] environment variable,

• testing the [PRINCIPIA_HOME] environment variable and

• installing the PriTeX LaTeX package file into the particular TeX engine.

---

Download

Download the file principia.zip and extract the content in a useful location [INSTALL_BASEDIR], for example the user home directory. The extracted files will all fall under a subdirectory called principia of [INSTALL_BASEDIR]. This directory is called the [PRINCIPIA_HOME] directory.

---

Set the PRINCIPIA_HOME environment variable

Set the environment variable [PRINCIPIA_HOME_VAR] to [PRINCIPIA_HOME].

• On most Linux systems this can be done permanently for a particular user, by editing (and possible creating) the hidden file .pam_environment in the user home directory.

  • Add the line "PRINCIPIA_HOME=[INSTALL_BASEDIR]/principia" (without quotation marks and the particular value of [INSTALL_BASEDIR]).
  • Logout and login again for the variable to be recognised.

• In Windows,

  • Right-click My Computer, and then click Properties.
  • Click the Advanced tab.
  • Click Environment variables.
  • Click New to add a new variable. The name is PRINCIPIA_HOME and the value is [INSTALL_BASEDIR]\principia (using the particular value of [INSTALL_BASEDIR]).

---

Test the PRINCIPIA_HOME environment variable

Since so much depends on this environment variable, it should be tested before continuing.

Issue the following command from a terminal.

• Linux cd $PRINCIPIA_HOME

• Windows cd %PRINCIPIA_HOME%

If the variable has been properly set the current directory will now be the Principia home directory.

List the directory.

• Linux ls

• Windows dir

If set correctly the Principia subdirectories will be listed, including bin, examples and install.

---

Install PriTeX

Install the LaTeX package pritex.sty into the particular TeX system. This file is located in the directory

• Linux $PRINCIPIA_HOME/install/texmf/tex/latex/pritex

• Windows %PRINCIPIA_HOME%\install\texmf\tex\latex\pritex

For more details and simplifying scripts see

• [Install PriTeX. TeX Live details.]
• [Install PriTeX. MiKTeX details.]

---

---

Testing

The installation process can be tested from a terminal, by processing the file [Sets.tex] under XeTeX.

• Change into the directory containing this file.

  • Linux cd $PRINCIPIA_HOME/examples/src/principia/sets
  • Windows cd %PRINCIPIA_HOME%\examples\src\principia\sets

• Run XeTeX on the file Sets.tex

  • xelatex --shell-escape Sets.tex

• If all has worked correctly, the following line will appear in the output.

  • [main] INFO org.principia.bin.pritex.RunPritex - Starting Principia.

• There should now be a file Sets.pdf in the directory.

• There will be warnings regarding cross references and citations. Run BibTeX and then reprocess the document twice. This reprocessing has nothing to do with Principia which only requires a single processing.

  • bibtex Sets
  • xelatex --shell-escape Sets.tex
  • xelatex --shell-escape Sets.tex

• After the final processing, there should be no errors or warnings other than overfull boxes.

• View the PDF document.

---

Warning regarding --shell-escape

TeXperts will notice, with concern, the TeX option --shell-escape. This option enables the execution of any operating system command from within a LaTeX document via the [write8] extension. PriTeX uses this mechanism to invoke the Principia system which runs on a Java virtual machine [JVM]. This exposes, however, a serious security risk, given the way shell escaping is currently implemented, since it allows malicious operating system level programs to be embedded inside LaTeX documents.

• Should Principia ever prove popular, this security issue will be resolved by the community.

For now, we advise the following.

• Do not change the default options of your LaTeX environment to shell escape generally. Rather, permit this option on a document-by-document basis.

• Documents that are processed under the --shell-escape option, should not include or import documents from untrusted sources. Only use standard [CTAN] packages.

• Use the Principia [import] mechanism rather than a physical LaTeX include or import.

• Do not allow shell escaping outside of your experimentations with Principia.

See [write8] for a detailed discussion.

---

Optional: Installing TeXlipse

If all installation and testing steps have been completed successfully, PriTeX documents can be processed by XeTeX from the command prompt.

It should now be possible to configure your favourite editor to use Principia and PriTeX.

The [trails] are designed with [TeXlipse] as editor. In order to best utilise these examples, install TeXlipse and [Eclipse].

• [Installing Eclipse and TeXlipse]

---

Playing with Principia

If all has worked, you are in a position to begin discovering more about Principia.

• [Playing with Principia].

• Analyse [Sets.tex].