A Sublime Text 2/3 package for PreTeXt files.
- Total 87
- Win 41
- OS X 34
- Linux 12
|May 26||May 25||May 24||May 23||May 22||May 21||May 20||May 19||May 18||May 17||May 16||May 15||May 14||May 13||May 12||May 11||May 10||May 9||May 8||May 7||May 6||May 5||May 4||May 3||May 2||May 1||Apr 30||Apr 29||Apr 28||Apr 27||Apr 26||Apr 25||Apr 24||Apr 23||Apr 22||Apr 21||Apr 20||Apr 19||Apr 18||Apr 17||Apr 16||Apr 15||Apr 14||Apr 13||Apr 12||Apr 11|
PreTeXtual: a Sublime Text package for PreTeXt
PreTeXtual is a Sublime Text 3 package designed to assist authors using PreTeXt (formerly known as MathBook XML). It is very experimental and may behave unexpectedly.
The package is inspired by the excellent LaTeXTools package, which I have enjoyed using for many years. I have borrowed very liberally from the LaTeXTools codebase in order to implement the features I thought would be most useful to MBX authors. Please let me know of any bugs you find or any features you would like to include.
As of version 0.5.0, Sublime Text 2 is no longer supported.
- Additional setup to use the automatic build systems
- Read before continuing
- Install other required software
- Choose a Vagrant box
- Install PreTeXt with one easy step
- Populate your environment
- Compiling to HTML or PDF
- Building images
- Known issues
Note: We assume you are familiar with running Sublime Text commands via the Command Palette. To bring up the palette, hit Ctrl+p (Cmd+p on OS X). Then start typing the name of the command you want to filter the list of results.
It is recommended to install PreTeXtual via Package Control. If you have not installed Package Control yet, you should do that first (and restart Sublime Text afterward).
After Package Control is installed, use the
Install Package command (in the
Command Palette) to search for the PreTeXtual package, and select it from the
Quick Panel to install. This method of installation allows Package Control to
automatically update your installation and show you appropriate release notes.
You may also install PreTeXtual via
git. Change directories into your
Packages folder. To find the
Packages folder, select Browse Packages from
the Preferences menu (from the Sublime Text 3 menu on OS X). Make sure you are
Packages folder and not
git clone https://github.com/daverosoff/PreTeXtual.git
and restart Sublime Text (probably not necessary).
Additional setup to use the automatic build systems
PreTeXtual now comes with build systems that can process your PreTeXt source into HTML or LaTeX and build your latex-image images into all image formats. The result is output that is ready to preview in a browser (HTML) or compile to PDF (LaTeX). All of this can be done from the command palette, if you carefully follow the directions below.
Read before continuing
The build systems are intended primarily for Windows users, since PreTeXt is much more difficult and tedious to install on Windows. As of this release, it has only been successfully used on Windows 10. Windows 7 users are welcome to try to follow the directions, but Windows 7 seems to have some difficulty installing current versions of Vagrant, see below. Future support for Windows 7 is devoutly to be wished.
If your Windows 7 is 32-bits, it is unlikely that you will be able to use the build system. Please open an issue if you need 32-bit support. If there is sufficient demand, it is possible to create compatible Vagrant boxes. (However you will still need to use Vagrant, which may not always play nice with Windows 7, as described above)
Users of other operating systems will not find the build systems in this release useful without manual editing of some of the package resources. You are welcome to open an issue with questions about how to accomplish this. A future release will support use of the build systems without Vagrant, which is preferable for any Mac OS or Linux users who might want to use the build systems for convenience.
Install other required software
At present, the build systems require the use of two other applications, Virtualbox and Vagrant. Install these on your computer. Agree to the default whenever you are prompted for a decision. Not choosing default values will break the PreTeXtual build systems.
- In Sublime Text, use Package Control to install the SideBarEnhancements plugin
- Download Virtualbox
- Download Vagrant
Choose a Vagrant box
After downloading and installing from the above links, open a Sublime Text window and run the command (from the Command Palette) “Initialize PreTeXt Vagrant”. This will take some time, depending on your selections. You will see a menu with several choices. Most people will want either “PreTeXt” or “PreTeXt-lite”. If you need Sage or Asymptote, choose “PreTeXt” (note that these image types are not supported in this release but support is coming very soon). If you need a full LaTeX installation but not Sage or Asymptote, choose “PreTeXt-lite”. If you only need to process HTML, you can try “PreTeXt- barebones”. The last option, “PreTeXt-no-images”, is only for testing.
The full “PreTeXt” option will take between 45 and 60 minutes to download and install. The others will take less time, but even the barebones option might take 10 to 15 minutes. You should see new windows opening to advise you of progress and reassure you that something is happening. When no more of these windows are visible, go on to the next step.
Install PreTeXt with one easy step
Note: This step will merge with the previous one in a future release.
From the Command Palette, run the command “Clone repository”. You will see a message at the bottom of the screen prompting you for a URL. Enter the text
and hit Enter. Another new window will pop up during the installation, which should only take a few seconds.
Populate your environment
The previous sections created a new folder
C:\PreTeXt on your machine. This
is where all your writing projects will live. You have a few ways to get them
- Move existing projects to the
C:\PreTeXtfolder. This is probably be st to do using the Windows file browser.
- Clone existing git repositories using the “Clone repository” command.
- Create an empty folder for a new project. Put it under
C:\PreTeXtand call it whatever you want (no spaces!)
Whatever way you choose, verify the following for each project you add.
- Project folder has subfolder called
srcfolder contains all PreTeXt source files for the project
Compiling to HTML or PDF
To get ready for the next step, open a command shell and run
Now the fun starts. In an existing writing project, open the root PreTeXt file
(the one with the
<mathbook> element). Use the Command Palette
(Ctrl+Shift+P) to run the command “Set current file as PreTeXt
root”. Then, bring up the build menu by pressing Ctrl+Shift+B.
Select “Process PreTeXt to HTML” from the menu. If you are watching the
sidebar, you will see an
output folder appear next to your
src folder. If
you expand it in the sidebar you can watch the HTML files appear as they are
generated. When the build is finished, Sublime Text should alert you to this
fact with a dialog box.
output\html folder and right-click one of the HTML files. Select
“Open in browser”. Marvel at the relative simplicity of this process.
To compile to LaTeX, you can select “Process PreTeXt to LaTeX” from the menu. To convert to PDF, I recommend you use the excellent LaTeXtools plugin, to which PreTeXtual owes a great deal. A future version (coming very soon) will support compilation from within Sublime Text without the use of LaTeXtools.
Note: this part of the build system may still be a bit buggy. In particular it
will probably fail if you chose
Building images should be as simple as processing to HTML or LaTeX. Use the Ctrl+Shift+B menu to select “Build images” (this will take a while if you have a large project). Then refresh your HTML output in the browser to check that the images appear.
This concludes the tour of the build system. Run
vagrant suspend in a command
shell before shutting down your system (Windows will complain that something is
stopping you from shutting down otherwise).
PreTeXtual is inspired by LaTeXTools, and like that package uses a Ctrl+l prefix for many commands. The Expand Selection to Line command is bound to Ctrl+l by default. PreTeXtual rebinds that command to Ctrl+l, Ctrl+l. Note that this is a keyboard shortcut consisting of two separate keystroke combinations. Most PreTeXtual shortcuts are like this.
You can activate the package features by enabling the PreTeXt syntax. The
syntax definition looks for
.ptx or the legacy
.mbx file extension. If
your MathBook XML files end with
.xml (or something else), you have several
Use the Preferences menu or the Command Palette to run the command
Set PreTeXt File Extensions, and use the input panel to add
.xmlor other extensions of your choice to the comma-separated list. Sublime will look for a project settings file first, then update user preferences if it doesn't find one. If you have multiple PreTeXt projects, or if you edit XML other than PreTeXt, it is best to start using Sublime Text projects so that you can have project-specific settings.
Enable the syntax manually using the command palette. To enable it manually, open a PreTeXt file and press Ctrl+Shift+P (Cmd+Shift+P on OS X) and type
Set Syntax: PreTeXtfrom the list of options.
You should see the text
PreTeXt in the lower right corner if you have
the status bar visible (command palette: Toggle Status Bar). Please excuse
the image which still shows the former name
Here is a (non-exhaustive) list of features.
New in 0.6.0: an extensive interface with Vagrant virtual machine management software is included, to enable Sublime Text 3 to behave more like an API for PreTeXt. See the PreTeXt Author's Guide for more information.
If you have some subdivisions (with
xml:id) in your PreTeXt file, hit Ctrl+R (Cmd+R on OS X) to run the Goto Symbol command. You should see a panel showing all your available sections. Select one to jump to it in the active view. This tool does not index subdivisions without an
Open your entire source folder as a project and use Goto Symbol in Project (Ctrl+Shift+R/Cmd+Shift+R) to see all the
xml:idfor all the MathBook XML files in the project (must use
.ptxextension for indexing to succeed).
If you have been using
xml:idto label your stuff, try typing
<xref ref="(the beginning of a cross-reference). Sublime Text should show you a panel containing all xml:id values along with the elements they go with. Choose one to insert it at the caret and close the
xreftag. Alternatively, type
refand hit Tab to activate the
xrefsnippet. Then hit Ctrl+L, X or Ctrl+L, Ctrl+Space to bring up the completions menu. There are several variants of the
If you set a PreTeXt root file, then ref completion as described above will recursively search for
xml:idthrough all your
xi:includesstarting with the indicated root file. Run the command “Set PreTeXt Root File” from the Preferences menu or the Command Palette. Be sure to use an absolute path name for the value of the setting, as well as forward slashes (yes, Windows too).
Tabto activate the subdivision snippets. A blank
titleelement is provided and the cursor positioned within it. As you type, the
xml:idfield for the subdivision is filled with similar text mirroring the title you are entering.
- There are quite a few edge cases and bugs in the build system left to fix in the next rc version.
refsnippet does not bring up the quick panel. Should it?
- Some of the snippets could be improved.
- Symbol finding could be improved.