Opensource software source packages are usually distributed with documentation which is in some markup language
since it can then be easily converted to many other formats (html, pdf, man-pages etc).
The documentation is usually converted at the same time the software is built. Since Scratchbox aims to be a
complete development environment where any software can be built without needing to change anything in the original
distribution package we need various documentation tools to handle the converting of documentation. Another reason is
that installing target and architecture specific tools might not be the best way since they would have to be installed
separately for all targets and, for example, when using ARM target the tools are run using emulation or on an ARM
device and that might be very slow. Instead, we have the tools in Scratchbox and they are run on the host which is a
lot faster.
To checkout the GAR tree from CVS you need to have your static IP address added to the list of IP addresses from where ssh connections are allowed. When
that is done you can checkout the GAR tree with the following command:
Installing is rather easy using the prebuilt packages. If you want you can also build the tools yourself and
install those.
You most likely must be root to install the documentation tools because you need write permissions to /scratchbox/ directory.
You can install the tools from a prebuilt package as follows:
Tarball:
tar xvf scratchbox-doctools-<version>.tar.gz -C /
Debian package:
dpkg -i scratchbox-doctools_<version>_i386.deb
RPM package:
rpm -Uvh scratchbox-doctools-<version>.i386.rpm
If you want to use the CVS version of the documentation tools package:
Go to the documentation tools directory in the GAR tree
cd scratchbox/doc_tools/
Build and install the tools
make && make install
The documentation tools are installed into /scratchbox/doc_tools/ directory. It's added
to users' PATH inside scratchbox so one can run the tools by just typing their name. Users usually don't need to run
the tools explicitly since the build scripts of software packages do it automatically when needed.
The following is a list of the documentation tools currently in Scratchbox along with short descriptions.
groff
The groff (GNU Troff) software is a typesetting package which reads plain text mixed with formatting commands and
produces formatted output. Output can be produced in a number of formats including plain ASCII, HTML and
PostScript.
The package contains the traditional UN*X text formatting tools troff, nroff, tbl, eqn, and pic. These utilities,
together with the man package, are essential for displaying the online manual pages. A number of other utilities are
also included together with several fonts.
A command line utility that converts HTML documents into plain text. The program is able to preserve the original
positions of table fields, allows you to set the screen width (to a given number of output characters), and accepts
also syntactically incorrect input (attempting to interpret it "reasonably").
OpenJade is a suite of tools for validating, processing, and applying DSSSL (Document Style Semantics and
Specification Language) stylesheets to SGML and XML documents. DSSSL is an ISO standard for formatting SGML (and XML)
documents.
An outline font editor that lets you create your own postscript, truetype, opentype, cid-keyed, multi-master, cff,
svg and bitmap (bdf) fonts, or edit existing ones. Also lets you convert one format to another.
Scratchbox uses the GAR build system [1]. It's a mechanism for automating the compilation and
installation of third-party source code. It appears in the form of a tree of directories containing Makefiles and other
ancillary bookkeeping files (such as installation manifests and checksum lists).
Only Scratchbox developers are allowed to access the CVS repository. The following instructions apply for adding
new tools to a local GAR tree as well, just ignore the adding to CVS and copying files to Scratchbox webserver.
To download the current CVS version in one package go to http://viewcvs.scratchbox.org/cgi-bin/viewcvs.cgi/ and click on the 'Download tarball' link at the bottom of
the page. Extract the tarball to a appropriate directory.
To checkout the GAR tree from CVS you need to have your static IP address added to the list of IP addresses from where ssh connections are allowed. Once
that is done you can checkout the GAR tree with the following command:
Adding new documentation tools to Scratchbox is fairly straightforward:
Obtain source package for the software.
Create a directory for the new tool in scratchbox/doc_tools/ directory.
Copy the source package to scratchbox/doc_tools/<newtool>/files/ directory.
Create a new GAR makefile scratchbox/doc_tools/<newtool>/Makefile. The GAR
makefile must have some specific variables for making it work correctly. At least the following variables should be
there.
GARNAME defines the package's name.
GARVERSION defines the package's version.
CATEGORIES defines the package's category. In this case it is 'doc_tools'.
DISTFILES defines the source package that contains the source. This is usually
combination of GARNAME, GARVERSION and source package's extension (usually tar.gz or tar.bz2).
LIBDEPS tells which libraries this package depends. These packages are compiled
before compiling this package.
DEPENDS defines packages that must be compiled before this package can be compiled
properly. This might contain tools that are required during building process of this package.
DESCRIPTION contains description of this package.
CONFIGURE_ENV defines some Scratchbox specific variables. For example Scratchboxs
perl and python should be defined here if package uses them.
CONFIGURE_ARGS defines options that are passed to package's configure script. This
should contain at least the install prefix.
BUILD_ARGS defines arguments that are used to build this package. This should
contain at least Scratchbox specific LDFLAGS, CC and PERL or PYTHON paths if they are used.
INSTALL_ARGS contains arguments that are used when package is installed. Usually
they are the same as BUILD_ARGS.
CONFIGURE_SCRIPTS defines the configuration script. Usually the package's own
configure script.
BUILD_SCRIPT defines the build script. Usually the package's own makefile.
INSTALL_SCRIPT defines the install script. Usually the package's own makefile.
In addition to package specific options packages GAR makefile should include correct GAR category file. In
Scratchbox this is done by including '../category.mk' file after variable definitions. See the Makefiles in Scratchbox
GAR tree for examples.
Type make checksums in packages directory to generate checksum information for package.
Package is now ready to be compiled. Compiling and installing package can be done with make
install command.
If the package does not compile properly check that you have necessary library dependencies etc. in the Makefile.
You might also have to add some Scratchbox specific configuration and build options.
Once the package builds cleanly and you have verified that it works you can add it to Scratchbox CVS repository.
You must also copy the source package to /work/files/sbox-files/ directory on Scratchbox
webserver so that it will be availble for others. Make sure the file permissions allow a read access for others as
well!