TeXPolicy

TeXPolicy

This document provides rules and recomendations for the packaging of the components of TeX subsistem and for packaging of applications having build or installation requirements on TeX or any other components of TeX subsystem.

Terms and Definitions

 * TeX distribution — a package or a collection of packages that provides binary files compatible with Donald E. Knuth's original TeX and metafont programs. At the moment Sisyphus repository holds two TeX distributions —             and . TeX distributions conflict with each other and currently there is no way to install packages originating from different TeX distributions simultaneously.
 * TEXMF tree — subdirectory in a file system organized according to TeX Directory structure recommendetions. In the TeX packaging context significant system TEXMF trees are:
 * TEXMFMAIN —
 * TEXMFDIST —
 * TEXMFSYSCONFIG —
 * TEXMF module — any files that are meant to be used by a TeX-related programm (placed in one of the system     TEXMF trees and accessible by the means of  library). TEXMF module may be packaged as a separate    package independent of any particular TeX distribution such that this package may be used with any TeX destribution.
 * Package using TeX subsystem — any package having build or install dependencies on any TeX-related program.

Install dependencies
In a general case (when a package is not specific for any particular TeX distribution) dependencies on the necessary TeX-related program should not be listed explicitly in the package — they will be found automatically. Following this rule enable users to install your package with any TeX distribution. When a necessary dependence was not detected automatically you may list in a package spec file expicit depence on a particular binary file requied by your package. For example:

Requires: /usr/bin/latex Requires: /usr/bin/dvips

All cases when a necessary dependnce was not detected automatically should be reported as an error.

A package may be specific for some TeX distribution when it could not be used with the other distribution or doesn't make sense for it. In this case explicit dependence on the pakage names of the needed TeX distribution is acceptable. E.g..

In all other cases explicit dependence on package names of one of the TeX distributions is considered an error.

Build dependencies
Packages using applications from a TeX distribution for build should list build dependency on that TeX distribution which is supposed by the package maintainer to be used for build.

Package names providing basic TeX functionalities required by other packages at the build time are listed in a table below for both TeX distributions.

At the moment TeX distributions are not equally supported: tetex is obsolete and texlive is maintained. Hence package maintainers are encouraged to use texlive packages for build whenever possible.

TeX distributions are supposed to be equivalent in their basic functionality such that replacing packages of one TeX distribution in a build environment with the packages of the other TeX distibution should not affect successfullness and the result of the building process. If such an effect is detected it should be reported as a possible error.

It is forbidden to list packages from different TeX distributions in a build requirements simultaneously because it will lead to unability to form build environent for your package due to TeX distributions mutual conflict.

TeX input files
If your package contains files meant to be used by TeX and related programs (most commonly
 * .sty and *.tex files), they are subject to rules of the section 3 of this document.

TEXMF modules packaging
All files meant to be used by TeX and related programs should be installed in one of the systemTEXMF trees. These files should not be placed anywhere outside TEXMF trees with the only exeption of %docdir.

For example, if your package contais LaTeX style files (.sty, .cls) these files are treated as TEXMF module and are subject to the rules of this section. In many cases packaging such a contained TEXMF module as a separate subpackage is reasonable.

General rules
Packaging TEXMF modules as a separate subpackages is motivated by the two main ideas: provided by the TeX distribution, "shadow" them. This enables to use TEXMF module to supplement a TeX distribution with the missing packages or to provided newer version of the package than in a conservative and comparatively rarely updated TeX distributions. distribution.
 * Files of a separately packages TEXMF modules have priority over the similar files
 * Separately packaged TEXMF modules should be universal, i.e. ready to use with any TeX

A separate package with a TEXMF module makes sense only if the corresponding module is missing in a TeX distribution or separate package provides version newer in at least one of the TeX distributions.

Maintainer of the separately packaged TEXMF module should keep his version not lower than in at least one of the TeX disributions. Otherwise package should be deleted from the repository.

TEXMF trees may not contain architecturally-dependent files. (Sub)package containing only TEXMF module should have noarch build architecture.

BuildArch: noarch

Package naming scheme
TEXMF modules should be named according to the following scheme:

texmf- -

where — is one of TeX formats (in TDS, directories TEXMF/tex/ /), e.g. latex, plain, xetex, lambda etc; — package name (in TDS, directories TEXMF/tex/ / / or TEXMF/tex/ /{base,misc}/        .{sty,cls}).

If a package contains files for several different TeX formats or format-specific and format-uncpecific (generic) files simultaneously they may be placed in a single package with a name:

texmf-

Whether such a package should be splited into smaller subpackages for each TeX format is left for the maintainers decision.

Note: generic may be treated as a special case of TeX format, so that splitting package into texmf-{generic,latex...}- subpackages is acceptable.

TEXMF modules contaning files to be used by a particular TeX-related progra, (in TDS, directories TEXMF//), are named according to scheme:

texmf-

TEXMF module specific to particular TeX distribution (see above) are named according to the same rules with the texmf- prefix replaced with the corresponding TeX distribution prefix, for example:

tetex- -

Dependencies

 * Build dependencies

BuildRequires(pre): rpm-build-texmf

All TEXMF modules should have dependency on. Presence of this package in a build environment provides:


 * availability of the necessary RPM macroses
 * Some macroses require to be installed in hasher: before th package build procedure    starts, therefore dependency on it should be listed as BuildRequires(pre):.


 * package that has installed files in TEXMFMAIN tree will automaticaly get dependency on     directory (provided by the  package), which guarantees avalability of all necessary infrastructure   (TEXMF directories, filetriggers) by the moment of installation of your package.


 * Install dependencies

Rules of he section 2.1 of his documen are applied.

File placement

 * TeX input files

TEXMF modules place files meant to be used by a TeX-related program in the TEXMFMAIN: tree according to the   TDS rules.

Documentaton files are placed in a subdirectories of according t TDS — this enbales TeX-        specific documentation searching utilities (texdoc and teh like) to find these files.
 * Documentation

Documentation files may e placed in /usr/share/doc/%name-%version directory provided that all the necessary symlinks  to the actual documentation files are created under  hierarchy to make them accessible by texdoc.

Documentation files should have self-explaining names corresponding to the package they document (generic names like  manual, index etc. sould be avoided becausethis makes files useless for search with texdoc).


 * Configuration files

Configuration files are placed in TEXMFSYSCONFIG: tree. Paths for files placement by type:
 * updmap config files —
 * hyphenation-related config files — (language.def and language.dat fragments)
 * fmtutil config files — ,
 * other config files — according to TDS.


 * Directories ownership

TEXMF module package should not own directories owned exclusively by.

/etc/tex-fonts.d       tex-common /etc/texmf     tex-common /etc/texmf/fmt.d       tex-common /etc/texmf/language.d  tex-common /etc/texmf/updmap.d    tex-common /usr/share/texmf       tex-common /usr/share/texmf/doc   tex-common /var/cache/texmf       tex-common
 * 1) tex-common dirlist for /usr/lib/rpm/files.req

All the subdirectories of the listed directories, installed by the package, should be owned by the package.

TEXMF module registering during installation
After installation/deletion of a TEXMF module system should perform a few operations to (de)register files in a TEXMF tree (texhash,updmap,fmtutil). A necessity to run these programs is detected automatically at the moment of the package installation or deletion with the help of filetriggers.

Therefore %post and %postun scriptlets in a TEAMF module package '''should not contain explicit calls''' to texhash, updmap, fmtutil.

Samples

 * Macropackage (style, class) for LaTeX
 * Fonts to use with ТеХ/LaTeX

Package naming scheme:. See also FontsPolicy



General Rules
TeX distribution should provide:
 * and — inaries fully compatible with Donald E. Knuth's original TeX and    METAFONT prorams
 * — utility to update ls-R databases in TEXMF trees
 * means to automatically run updae process for available vector fonts database (updmap) at the moment of installing/  deleting files into  directory by other packages (impemented using rpm-filetrigger    mechanism).
 * means to automatically run updae process for available vector fonts database (updmap) at the moment of installing/  deleting files into  directory by other packages (impemented using rpm-filetrigger    mechanism).

Note: filetrigger running texhash at the moment of installing/deleting files in system TEXMF trees is procided by the tex-common package. Tex distribution packages should not explicitly call texhash in %post(un) scriptlets.

Package naming scheme
TeX distribution packages are named according to the fillowing scheme:

-

Build dependencies
TeX distributions hould have build dependency on.

File placement
Files meant to be used by TeX-related programs TeX distributions should place in a TEXMFDIST tree.
 * TeX input files

It is acceptable to place individual files into TEXMFMAIN tree when consistemcy of such files with the main distribution binaries is crucial (because such placement prevents "shadowing" of such files by teh files of other TeX distribution or other packages). Number of files placed in TEXMFMAIN tree by a TeX distribution should be minimised because they cause file-level conflicts between packages of different TeX distributions and other packages.


 * Documentation

TeX distributions place documentation files in TEXMFDIST/doc subtree. It s possible to place documentation in %docdir, in that case TEXMFDIST/doc should be a symblic link to %docdir.


 * Configuration files

TeX distributions place configuration files into TEXMFSYSCONFIG tree. Config files suplied by TeX distributions are subject to te rules of section 3.4 of this document.

Links

 * Debian Tex Sub-policy
 * TeX Directory structure (TDS)