Package: pretext
PreTeXt-CLIA package for authoring and buildingPreTeXtdocuments.GitHub:https://github.com/PreTeXtBook/pretext-cli/Documentation and examples for authors/publishersMost documentation for PreTeXt authors and publishers is available at:https://pretextbook.org/doc/guide/html/Authors and publishers may also find the examples catalog useful as well:https://pretextbook.org/examples.htmlWe have a few notes below (TODO: publish these in the Guide).InstallationInstalling PythonPreTeXt-CLI requires the Python version specified inpyproject.toml.To check your version, type this into your terminal or command prompt:python -VIf your version is 2.x, try this instead
(and if so, replace all future references topythonin these instructions withpython3).python3 -VIf you don't have a compatible Python available, try one of these:https://www.python.org/downloads/Windows warning: Be sure to select the option adding Python to your Path.https://github.com/pyenv/pyenv#installation(Mac/Linux)https://github.com/pyenv-win/pyenv-win#installation(Windows)Installing PreTeXt-CLIOnce you've confirmed that you're using a valid version of Python, just
run (replacingpythonwithpython3if necessary):python -m pip install --user pretext(It's possible you will get an error likeerror: invalid command 'bdist_wheel'— good news, you can ignore it!)After installation, try to run:pretext --helpIf that works, great! Otherwise, it likely means that Python packages
aren't available on your “PATH”. In that case, replace allpretextcommands withpython -m pretextinstead:python -m pretext --helpEither way, you're now ready to use the CLI, the--helpoption will explain how to use all the different
subcommands likepretext newandpretext build.External dependenciesWe install as much as we can with thepip installcommand, but depending on your machine
you may require some extra software:TeXLivepdftoppm/GhostscriptUpgrading PreTeXt-CLIIf you have an existing installation and you want to upgrade to a more recent version, you can run:python -m pip install --upgrade pretextCustom XSLCustom 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 (toproject.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'sxsl:import@hrefas follows:<xsl:import href="./core/pretext-common.xsl"/>Similarly,entities.entmay be used:<!DOCTYPE xsl:stylesheet [
    <!ENTITY % entities SYSTEM "./core/entities.ent">
    %entities;
]>Note: previously this was achieved with apretext-hrefattribute - this is now deprecated and will be removed in a future release.DevelopmentNote.The remainder of this documentation is intended only for those interested
in contributing to the development of this project. Anyone who simply wishes tousethe PreTeXt-CLI can stop reading here.From the "Clone or Download" button on GitHub, copy theREPO_URLinto the below
command to clone the project.gitclone[REPO_URL]cdpretext-cliUsing a valid Python installationDevelopers and contributors must install a
version of Python that matching the requirements inpyproject.toml.Using pyenv and poetry (Mac/Linux)Thepyenvtool 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).https://github.com/pyenv/pyenv#installationRun the following, replacingPYTHON_VERSIONwith your desired version.pyenv install PYTHON_VERSIONThen follow these instructions to installpoetry.https://python-poetry.org/docs/#installationNote 2022/06/21: you may ignore "This installer is deprecated". Seepython-poetry/poetry/issues/4128Then you should be able to install dependencies into a virtual environment
with this command.poetry installBefore you attempt to runpretextlocally, you must fetch a copy of the core pretext library
and zip up templates by runningpoetry run python scripts/fetch_core.py
poetry run python scripts/zip_templates.pyThen 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 versionOr use the runner (as long as you remain within the package directory):pretext --version             # returns system version
poetry run pretext --version  # returns version being developedIf you runecho 'alias pr="poetry run"' >> ~/.bashrcthen restart your
shell, this becomes less of a mouthful:pretext --version     # returns system version
pr pretext --version  # returns version being developed(On Windows, in PowerShell, you get get such an alias withFunction pr {poetry run @Args})Steps on WindowsIn windows, you can either use the bash shell and follow the directions above,
or trypyenv-win. In
the latter case, make sure to follow all the installation instructions, including
theFinish the installation. Then proceed to follow the directions above to
install a version of python matchingpyproject.toml. Finally, you may then need
to manually add that version of python to your path.Updating dependenciesTo add dependencies for the package, runpoetry add DEPENDENCY-NAMEIf someone else has added a dependency:poetry installSyncing untracked updatesUpdates to certain files tracked to the repository will
need to be rebuilt by each user when pulled from GitHub.The filepretext/__init__.pytracks the upstream
commit of core PreTeXt XSL/Python code we're developing against
(fromPreTeXtBook/pretext).
To fetch these updates from upstream, run:poetry run python scripts/fetch_core.pyIf you instead want to point to a local copy ofPreTeXtBook/pretext,
try this instead to set up symlinks:poetry run python scripts/symlink_core.py path/to/pretextUpdates totemplates/must be zipped and moved intopretext/templates/resources. This is done automatically by
running:poetry run python scripts/zip_templates.pyFormatting code before a commitAll.pyfiles are formatted with theblackpython formatter and checked byflake8.
Proper formatting is enforced by checks in the Continuous Integration framework.
Before you commit code, you should make sure it is formatted withblackand
passesflake8by running the following commands (on linux or mac)
from therootproject folder (most likelypretext-cli).poetry run black .
poetry run flake8TestingSets are contained intests/. To run all tests:poetry run pytestTo run a specific test, saytest_nameinsidetest_file.py:poetry run pytest -k nameTests are automatically run by GitHub Actions when pushing to identify
regressions.PackagingTo check if a successful build is possible:poetry run python scripts/build_package.pyTo 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.pyPublishing 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.0AboutPreTeXt-CLI TeamOscar Levinis co-creator and lead developer of PreTeXt-CLI.Steven Clontzis co-creator and a regular contributor of PreTeXt-CLI.Development of PreTeXt-CLI would not be possible without the frequentcontributionsof the
widerPreTeXt-Runestone Open Source Ecosystem.A note and special thanksApretextpackage unrelated to the PreTeXtBook.org project was released on PyPI
several years ago by Alex Willmer. We are grateful for his willingness to transfer
this namespace to us.As such, versions of this project before 1.0 are released on PyPI under the
namepretextbook, while versions 1.0 and later are released aspretext.About PreTeXtThe development ofPreTeXt's coreis led byRob Beezer.