PreTeXt-CLI has moved to https://pypi.org/project/pretext! To upgrade:
pip uninstall pretextbook
pip install --upgrade pretext
Original README follows...
A package for authoring and building PreTeXt documents.
Most documentation for PreTeXt authors and publishers is available at:
Authors and publishers may also find the examples catalog useful as well:
We have a few notes below (TODO: publish these in the Guide).
PreTeXt-CLI requires the Python version specified in pyproject.toml.
To check your version, type this into your terminal or command prompt:
python -V
If your version is 2.x, try this instead
(and if so, either replace all future references to python
in these instructions with python3).
python3 -V
If you don't have a compatible Python available, try one of these:
Once you've confirmed that you're using a valid version of Python, just
run (replacing python with python3 if necessary):
python -m pip install --user pretextbook
(It's also possible you may get an error like
error: invalid command 'bdist_wheel'
— good news, you can ignore it!)
After installation, try to run:
pretext --help
If that works, great! Otherwise, it likely means that Python packages
aren't available on your “PATH”. In that case, replace all pretext
commands with python -m pretext instead:
python -m pretext --help
Either way, you're now ready to use the CLI, the --help option will explain how to use all the different
subcommands like pretext new and pretext build.
We install as much as we can with the pip install command, but depending on your machine
you may require some extra software:
If you have an existing installation and you want to upgrade to a more recent version, you can run:
python -m pip install --upgrade pretextbook
Custom XSL is not encouraged for most authors, but (for example) developers working
bleeding-edge XSL from core PreTeXt may want to call XSL different from that
which is shipped with a fixed version of the CLI. This may be accomplished by
adding an <xsl/> element to your target with a relative (to project.ptx) or
absolute path to the desired XSL. (Note: this XSL must only import
other XSL files in the same directory or within subdirectories.)
For example:
<target name="html">
<format>html</format>
<source>source/main.ptx</source>
<publication>publication/publication.ptx</publication>
<output-dir>output/html</output-dir>
<xsl>../pretext/xsl/pretext-html.xsl</xsl>
</target>
If your custom XSL file needs to import the XSL
shipped with the CLI (e.g. pretext-common.xsl), then use a ./core/
prefix in your custom XSL's xsl:import@href as follows:
<xsl:import href="./core/pretext-common.xsl"/>
Similarly, entities.ent may be used:
<!DOCTYPE xsl:stylesheet [
<!ENTITY % entities SYSTEM "./core/entities.ent">
%entities;
]>
Note: previously this was achieved with a pretext-href attribute - this is now deprecated and will be removed in a future release.
Note. The remainder of this documentation is intended only for those interested in contributing to the developement of this project. Anyone who simply wishes to use the PreTeXt-CLI can stop reading here.
From the "Clone or Download" button on GitHub, copy the REPO_URL into the below
command to clone the project.
git clone [REPO_URL]
cd pretext-cli
Developers and contributors must install a
version of Python that matching the requirements in pyproject.toml.
The pyenv tool for Linux automates the process of running the correct
version of Python when working on this project (even if you have
other versions of Python installed on your system).
Run the following, replacing PYTHON_VERSION with your desired version.
pyenv install PYTHON_VERSION
Then follow these instructions to install poetry.
Then you should be able to install dependencies into a virtual environment with this command.
poetry install
Then to use the in-development package, you can either enter a poetry shell:
pretext --version # returns system version
poetry shell
pretext --version # returns version being developed
exit
pretext --version # returns system version
Or use the runner (as long as you remain within the package directory):
pretext --version # returns system version
poetry run pretext --version # returns version being developed
If you run echo 'alias pr="poetry run"' >> ~/.bashrc then restart your
shell, this becomes less of a mouthful:
pretext --version # returns system version
pr pretext --version # returns version being developed
In windows, you can either use the bash shell and follow the directions above,
or try pyenv-win. In
the latter case, make sure to follow all the installation instructions, including
the Finish the installation. Then proceed to follow the directions above to
install a version of python matching .pyproject.toml. Finally, you may then need
to manually add that version of python to your path.
To add dependencies for the package, run
poetry add DEPENDENCY-NAME
If someone else has added a dependency:
poetry install
Updates to certain files tracked to the repository will need to be rebuilt by each user when pulled from GitHub.
The file pretext/__init__.py tracks the upstream
commit of core PreTeXt XSL/Python code we're developing against
(from PreTeXtBook/pretext).
To fetch these updates from upstream, run:
poetry run python scripts/fetch_core.py
If you instead want to point to a local copy of PreTeXtBook/pretext,
try this instead to set up symlinks:
poetry run python scripts/symlink_core.py path/to/pretext
Updates to templates/ must be zipped and moved into
pretext/templates/resources. This is done automatically by
running:
poetry run python scripts/zip_templates.py
Sets are contained in tests/. To run all tests:
poetry run pytest
To run a specific test, say test_name inside test_file.py:
poetry run pytest -k name
Tests are automatically run by GitHub Actions when pushing to identify regressions.
To check if a successful build is possible:
poetry run python scripts/build_package.py
To publish a new alpha release, first add/commit any changes. Then the following handles bumping versions, publishing to PyPI, and associated Git management.
poetry run python scripts/release_alpha.py
Publishing a stable release is similar:
poetry run python scripts/release_stable.py # patch +0.+0.+1
poetry run python scripts/release_stable.py minor # +0.+1.0
poetry run python scripts/release_stable.py major # +1.0.0
The development of PreTeXt's core is led by Rob Beezer.
FAQs
A package to author, build, and deploy PreTeXt projects.
We found that pretextbook demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.