tex2sws / README.txt

Full commit
Rob Beezer
Initiated: 2010/01/27
Updated: 2010/02/27

This is a system for authors to convert a LaTeX document to a
Sage worksheet, or a collection of linked Sage worksheets.
Licensed with the GPL, see COPYING.txt.

The principal purposes are to

1) Preserve the mathematical LaTeX formatting of the
   document in the worsheet.
2) Migrate raw Sage code from the LaTeX document to
   the Sage worksheet.
     (a) Code to execute and experiment in pursuit of
     understanding mathematics.
     (b) Code to illustrate the proper use of Sage and
     Python in pursuit of (a) independently.
3) Migrate Sage interactive demonstrations from a LaTeX
   document to a Sage worksheet.

Secondarily, the LaTeX source should create a reasonable PDF
facsimile of the resultant worksheet when processed by pdflatex,
and the XHTML produced by tex4ht might also be usable.



1.  A working installation of Sage.  This also needs to be in
    your path, or you might be able to edit the shebang in the
    script to point to it.  This can be avoided with experimental
    code to create worksheets using just Python (and not the
    sagenb library code).

2.  A working installation of tex4ht to prepare input to this
    converter.  This may be part of your TeX installation,
    or you might be able to install it as a package.  See project
    wiki page for confirmed uses or setups.  Otherwise see
    instructions below for details.  Using tex4ht presupposes
    a reasonably complete TeX installation (such as TeXLive
    for Unix/Linux).



1.  Author something in latex.  Assume in the following that
    this latex document is named  foo.tex. You'll need just a
    bit of material in the header (which should be in a .sty
    file eventually).  Start with template.tex and look
    at example.tex (now outdated, but usable) for minimal guidance.
    Note the "worksheet" boolean switch if you want Sage and PDF outputs.

2.  Run tex4ht on your document.  See below for more info on this program.
    Make sure the tex4ht configuration file is in the working directory
    or put a correct path in command below.  (The configuration file is
    part of this distribution).  Run:

        htlatex foo.tex "/path/to/tex4ht-sage.cfg" " -cunihtf -utf8"

    A succesful run of tex4ht via its htlatex script should at a
    minimum produce:
    and the converter expects these to both be present.

    If you have multiple sections or subsections in your
    document you will also get files such as:
    where the XXX counts up from 1.  The converter will
    behave differently in the presence of these files, fixing
    hyperlinks between sections.  The output will be a tar archive,
    which is not supported by the notebook, so see the project wiki
    page for hints on how to deal with this archive.
    (2010/02/24 Converting multiple sections to a tar archive is
    most likely broken right now due to changes intended fro single
    worksheet creation.  It will come back.)

3.  Set your working directory to be where the output of tex4ht
    landed.  Make certain foo.css and foo.html are present.  It is
    alright if various latex and tex4ht source and intermediate files
    are present, but do not mix the output of two projects in the
    same directory.  Make the script executable:

        $ chmod 770 /path/to/

    Run the script.  See below for arguments.  If your input files are
    in the current directory, and are not mixed with another project,
    then sensible results can be obtained with no arguments.

        $ /path/to/

    Note: if you have the script in the same directory as your
    project files, run it with  ./

    Script arguments:

    -h --help
        Help similar to this section, but shorter.
    -v --verbose
        Print a summary of the conversion environment.
    -i --input_directory
        Directory containing CSS and HTML files.
        If omitted: The current directory.
    -b --basename
        The leading portion of files produced by tex4ht,
        for a project begun with  foo.tex  the basename is just  foo.
        If omitted: Determined by a single CSS file in the input directory.
        When there is no, or more than one, CSS file it is an error.
    -o --outputfile
        The name of the sws file to contain the compressed worksheet.
        If omitted: An sws file in the input directory using the basename.



    Main Page:
    Latest version:

    Packages (like Debian) are frequently out-of-date.  The installation link above
    is comprehensive advice for *porting* to a system, but can be used for a custom install.
    Here are some notes, items not mentioned should be performed basically as written
    in the instructions:

        (c,d) Compile.  Zip file should have 32-bit binaries in tex4ht.dir/bin/unix/.
              64-bit will need compilation -- see guidance in additional file near this one.
        (f,g,h) Environment pointers.  (f) is necessary, (g) and (h) are not.
        (i,j,k) Bitmap generation:  Skip these, as ideally you won't build bitmaps.
        (l,m,n,o,p) Scripts: not needed.
        (q) Path: do adjust your path so the binaries are located/found.
        (r) Style Files: I mv/cp tex4ht.dir/texmf/tex/generic/tex4ht to my personal texmf tree
        (s) texhash: Do this to make (r) effective.
        (t) Java: not necessary for purposes here.
        ()  Symlink: The environment file can be found via a symlink in your top-level home:
            ~/tex4ht.env -> ~/tex4ht.dir/texmf/tex4ht/base/unix/tex4ht.env
        (u,v,w) Test: as you see fit.