RST: Installation Guide

From DPWiki
Jump to navigation Jump to search
Exquisite-khelpcenter.png Note

RST is no longer used at DP. Information on this page is out of date.

This is where we explain how to install Python and related support tools for RST on Windows and on Mac/Linux.

Package Descriptions

These are the instructions for installing software to support RST on Windows. Python is required for all other packages. Most DP users will only install rst2html to generate HTML from their RST source.

python

Most PPers are familiar with Perl, the computer language used in GuiGuts. Python just another computer language. It is the language used for the other tools shown on this page. Users must install Python to be able to use these tools. There are two versions of Python out right now: version 2 and version 3. All instructions in this section presume you will be using Python version 2. Most users will be using 2.7, the latest stable release.

epubmaker

epubmaker is a locally installable subset of the software used at Project Gutenberg to convert between formats. Epubmaker can convert:

  • from HTML to EPUB, or
  • from RST to HTML, EPUB, and plain text in utf-8, iso-8859-1 and us-ascii flavours.

PPers can use the plain text files for checking with the usual DP tools.

You can check which version of epubmaker is current at: http://pypi.python.org/pypi/epubmaker

dp2rst

dp2rst is a command-line tool that will take the text downloaded from DP and convert as much as it can into RST format. Click HERE for more information.

Windows Installation

Guiguts Version 1.0.0 (guiguts-win-epub-1.0.0.zip) bundles ePubMaker avoiding the steps below.

Python

Windows XP

These instructions are for a new install of Python on a Window XP system only. If you already have a version installed (other than PYTHON 3 which will not run the rst2html.py program at this time), you don't need to download the latest version (2.7.1), unless you want to. I am using version 2.6.2 with no problems.

To install Python 2.7 on Windows XP systems:

  • go HERE to the Python download page.
  • download the "Windows X86 MSI installer (2.7)."
  • when downloaded, double-click to install.

Next, add Python 2.7 to your PATH statement:

  • click Start | Control Panel | System | Advanced | Environment Variables.
  • find and double-click on the "PATH" line in the "System variables" box.
  • right arrow to the end of the PATH line and type in ";C:\Python27" without the quotes. Make sure there is no space before or after the semi-colon. (there is no dot between 2 and 7)
  • click OK three times.

To check installation:

  • click Start | Run and enter "cmd" (no quotes) and press the ENTER key.
  • in the command window that pops up, type "python --version" (without the quotes) and press the ENTER key.
  • Python should announce itself.

epubmaker

The epubmaker program requires Python setup tools. From http://pypi.python.org/pypi/setuptools download "setuptools-0.6c11.win32-py2.7.exe" (or any newer version) and run it.

The epubmaker program requires Groff to generate text files. From http://gnuwin32.sourceforge.net/packages/groff.htm download "Complete package, except sources - Setup" (groff-1.20.1-setup.exe) and run it. Select all the default options and install.

Modify the path statement (similar to as done above for Python) 

 Start | Control Panel | System | Advanced | Environment Variables.
 Click "Path" in the User variables at the top.
 Click "Edit"
 Add a semicolon if there isn't one at the end already and then type this:
 
 C:\Python27;C:\Python27\Scripts;C:\Program Files\GnuWin32\bin;
 
 click Ok three times.

Note: If you are on a 64-bit Windows system you may also need to separately install two Python packages, PIL and LXML. You can find the executable installers for the 64-bit versions (as well as 32-bit versions) of these packages at http://www.lfd.uci.edu/~gohlke/pythonlibs/

Try the command below to install epubmaker, but if it fails with error messages about PIL or LXML you'll need to manually download and install them, then retry the epubmaker installation.

Open a command window and type 

 easy_install epubmaker

Check the installation: 

 epubmaker --help

NOTE: beginning with epubmaker version 0.3.18, you MUST also update the version of DOCUTILS to 0.8. Use this at the command prompt: 

 easy_install -U docutils

epubmaker uses Tidy to create the epub files. If you have installed Guiguts it should include Tidy already; otherwise you will need to follow these instructions to install it. Once you have a version of Tidy installed, modify the path statement again: 

 Start | Control Panel | System | Advanced | Environment Variables.
 Click "Path" in the User variables at the top.
 Click "Edit"
 Add a semicolon if there isn't one at the end already and then type the directory:
 
 C:\Program Files\guiguts\tidy; [or wherever tidy has been installed to]

Mac Installation

These are the instructions for installing software to support RST on Mac. Python is required and may be either a 2.6 version or a 2.7 version. Users of 2.5 should upgrade. This writeup assumes Python 2.7, though users who already have 2.6 installed may skip the section on installing Python and use "2.6" instead of "2.7" in the epubmaker installation section.

Python

Python comes pre-installed on Mac OS X, but due to Apple's release cycle, it's often one or even two years old. The overwhelming recommendation of the "MacPython" community is to upgrade your Python by downloading and installing a newer version from the Python standard release page. Software for RST described on this page is compatible with Python 2.7. It is not compatible with Python 3.

On that page, click on the link for "Python 2.7.1 (November 27th, 2010)". Then scroll down to the link for "Mac Installer disk image (2.7.1) for OS X 10.6 and later". That will bring down python-2.7.1-macosx10.6.dmg to your downloads folder. Open that and double-click the Python.mpkg icon. The installer puts the applications in "Python 2.7" in your Applications folder, command-line tools in /usr/local/bin and the underlying machinery in /Library/Frameworks/Python.framework.

Test your install by typing "python --version" in a terminal. It should report "Python 2.7" or later, such as "2.7.1".

epubmaker

Try "easy_install --help" to see if you already have it available. If you don't have easy_install already, get the setuptools package as a Python egg from http://pypi.python.org/pypi/setuptools#downloads. These installation instructions are for Python 2.7. Choose "setuptools-0.6c11-py2.7.egg"

This may download the egg with a ".sh" extension. If so, rename it to remove the ".sh". Run it as a shellscript: 

 sh setuptools-0.6c11-py2.7.egg

Check the installation with "easy_install --help".

Install groff. Use darwin ports with the command: 

 sudo port install groff

Now install epubmaker with 

 easy_install epubmaker

Test with 

 epubmaker --help

If you are using epubmaker to generate PDFs you need to install TexLive. Go to http://mirror.ctan.org/systems/texlive/tlnet and download the file install-tl.zip. It will be in your downloads folder. Open Downloads,double-click on install-tl.zip and it will extract into a subfolder. On mine, it was unzipped into "install-tl-20110208"

Then open a terminal and type 

 > cd ~/Downloads/install-tl-20110208/
 > perl install-tl

This will open the TeX Live installation wizard. Follow the instructions. When in doubt use the defaults. This will take quite a while--upwards of two hours. When it's done, it will announce "Welcome to TeX Live!"

To test it, put a source file and any images in a working folder (in this case "work") and generate the pdf with 

 > epubmaker --make=pdf work/filename.rst"

The result will be 99999-pdf.pdf

Remember that you cannot have the source files and image folder in the same location as the target files (as of 0.3.10).

Linux Installation (Debian based)

Prerequisites: (you may already have some of these installed, but installing them again doesn't do any damage.) Note: Epubmaker does not work with python 3 yet. If your distribution uses python 3 as default (not likely!), you'll have to parallel install python 2.6 or 2.7. 

 $ sudo bash
 # apt-get install python python-setuptools groff tidy
 # apt-get install gcc python-dev libxml2-dev libxslt-dev libjpeg-dev libpng-dev libfreetype6-dev
 # apt-get install python-cssutils python-docutils python-lxml

Epubmaker

 # easy_install epubmaker
 # exit
 $ cd ~/your/work/directory
 $ epubmaker --help
 $ epubmaker http://www.gutenberg.org/masters/rst/181/181.rst

Kindlegen

(Optional: Used only to make Kindle files) 

 $ cd /tmp
 $ wget http://s3.amazonaws.com/kindlegen/kindlegen_linux_2.6_i386_v1.1.tar.gz
 $ tar -xzf kindlegen_linux_2.6_i386_v1.1.tar.gz
 $ cp kindlegen ~/.local/bin/or/anywhere/else

If wget command fails, kindlegen is available from http://www.amazon.com/gp/feature.html?docId=1000765211

link to RST Index Page

Retrieved from "https://www.pgdp.net/w/index.php?title=RST:_Installation_Guide&oldid=133976"