<?xml version='1.0' encoding='utf-8'?>
<pretext xml:lang="en-US" xmlns:xi="http://www.w3.org/2001/XInclude">
  <docinfo>
    <macros>\newcommand{\foo}{bar}</macros>
    <latex-image-preamble>\usepackage{tikz}</latex-image-preamble>
  </docinfo>
  <article xml:id="pretext-cli-documentation">
    <title>PreTeXt-CLI Documentation</title>
    <section xml:id="about">
      <title>About</title>
      <introduction>
        <p>PreTeXt-CLI is available on 
        <url href="https://pypi.org/project/pretextbook/">PyPI</url>. Source
        code is available on 
        <url href="https://github.com/PreTeXtBook/pretext-cli/">
        GitHub</url>.</p>
      </introduction>
      <subsection>
        <title>Lead Contributors</title>
        <ul>
          <li>
            <url href="https://clontz.org">Steven Clontz</url>
          </li>
          <li>
            <url href="https://math.oscarlevin.com/">Oscar Levin</url>
          </li>
        </ul>
      </subsection>
      <subsection>
        <title>About PreTeXt</title>
        <p>The development of 
        <url href="https://github.com/rbeezer/mathbook">PreTeXt's core</url> is
        led by 
        <url href="http://buzzard.ups.edu/">Rob Beezer</url>.</p>
      </subsection>
    </section>
    <section xml:id="installation">
      <title>Installation</title>
      <subsection>
        <title>Python</title>
        <p>PreTeXt-CLI requires Python version 
        <xi:include href="../pretext/static/MINIMUM_PYTHON_VERSION"
        parse="text" /> or better.</p>
        <p>To check your version, type this into your terminal or command
        prompt:</p>
        <cd>python -V</cd>
        <p>If your version is 2.x, try this instead (and if so, either replace
        all future references to `python` in these instructions with `python3`,
        or try 
        <url href="https://askubuntu.com/a/321000">this</url>).</p>
        <cd>python3 -V</cd>
        <p>If you don't have a compatible Python available, try one of
        these:</p>
        <ul>
          <li>
            <url>https://www.python.org/downloads/</url>
              <ul><li>Windows warning: Be sure to select the option adding Python to your Path.</li></ul>
          </li>
          <li>
          <url>https://github.com/pyenv/pyenv#installation</url> (Mac/Linux) or 
          <url>
          https://github.com/pyenv-win/pyenv-win#installation</url> (Windows)</li>
        </ul>
      </subsection>
      <subsection>
        <title>Other Dependencies</title>
        <p>Some features of PreTeXt rely on some non-Python applications. TODO:
        Document these.</p>
      </subsection>
      <subsection>
        <title>PreTeXt-CLI</title>
        <p>Once you've confirmed that you're using a valid version of Python,
        just run (replacing `python` with `python3` if necessary):</p>
        <cd>python -m pip install --user pretextbook</cd>
        <p>(It's possible you may get an error like 
        <c>error: invalid command 'bdist_wheel'</c>
        <mdash /> good news, you can ignore it!)</p>
        <p>After installation, if you didn't see an error like
        <q>WARNING:
        The script pretext is installed in
        '[file_path]' which is not on PATH.</q>, then try to run:</p>
        <cd>pretext --help</cd>
        <p>If that works, great! Otherwise, it likely means that Python packages aren't
        available on your <q>PATH</q>.</p>
        <ul>
            <li>
        <p>To fix this on Linux/Mac, run the following commands:</p>
        <cd>
<![CDATA[echo "export PATH=\"`python -m site --user-base`/bin:$PATH\"" >> ~/.bash_profile
echo "export PATH=\"`python -m site --user-base`/bin:$PATH\"" >> ~/.zprofile]]>
        </cd>
            </li>
            <li>
        <p>To fix this on Windows, open your Windows Control Panel, search for <q>environment</q>,
        and select <q>Edit environment variables for your account</q></p>
        <p>Then edit your PATH variable and add the following line (replacing <c>3x</c> with the
        version of Python you installed, e.g. <c>38</c> for version <c>3.8</c>):</p>
        <cd>%USERPROFILE%\AppData\Roaming\Python\Python3x\Scripts</cd>
            </li>
          </ul>
        <p>Then close and reopen your command line and try 
        <c>pretext --help</c>again.</p>
      </subsection>
        <subsection>
            <title>Upgrading</title>
            <p>
The most recent version of PreTeXt-CLI is
<xi:include href="../pretext/static/VERSION" parse="text" />.
Use <c>pretext --version</c> to see the version you're running.
            </p>
            <p>
To upgrade your version, run the following:
            </p>
        <cd>python -m pip install --user pretextbook --upgrade</cd>
        </subsection>
    </section>
    <section xml:id="usage">
      <title>Usage</title>
      <p>For your convenience, documentation on using all features of the command-line interface may
      be viewed below, or displayed on the command line by using the 
      <c>--help</c> option. Use 
      <c>pretext --help</c> to see what commands are available, and (for example)
      <c>pretext new --help</c> to learn how to use each command.</p>
      <cd><xi:include href="../pretext/static/help.txt"
                    parse="text" /></cd>
    </section>
  </article>
</pretext>
