Metadata-Version: 2.1
Name: doCal
Version: 0.3.1
Summary: Inject Python calculations into Word and LaTeX documents with ease!
Home-page: https://github.com/K1DV5/doCal
Author: K1DV5
Author-email: kidusadugna@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown

# doCal

[![CircleCI](https://circleci.com/gh/K1DV5/doCal.svg?style=svg)](https://circleci.com/gh/K1DV5/doCal)

doCal is a tool that can be used to send calculations that are written in
python to Word or LaTeX documents. It evaluates equations in a separate python
script from the document and replaces hashtags in the document that indicate
where the calculations should be with the results of the evaluation. It comes
with a powerful python expression to LaTeX converter built-in, so it converts
the calculations and their results to their appropriate LaTeX forms before
sending them, which makes it ideal to make academic and scientific reports.

## Installation

### Requirements

**Quick note**: in this document, shell means `cmd` (command prompt) or
`powershell` for Windows users and `sh` or `bash` for Linux and MacOS users.

A basic understanding of Python in general is necessary to have a smooth
experience here.  If you want to work with a little more advanvced stuff, like
arrays and matrices, more knowledge about python is necessary.

It must be obvious by now but you should have Python installed on your system.
You can check that by opening your shell (see above) and typing the command
`python` and hitting Enter. If it writes the version number and other info
about your python installation, you already have it installed. If the version
number starts with 2, you should probably install python 3 (the latest). If you
have python 3 or above, you\'re good to go. If either you don\'t have Python 3
or you don\'t have Python at all, you should go to [Python\'s
homepage](https://www.python.org) and install it, making sure to check the box
\"add python to path\" during installation.

If you want to work with word documents, you should have
[Pandoc](https://pandoc.org) installed on your system (and in your path).
Because docal internally only works with tex files and when a word file is
given, it internally converts it to tex, modifies it and converts it back to
word, using pandoc.

### Install

To install this package, (after making sure that you have a working internet
connection) type the following command and hit Enter.

```shell
pip install docal
```
Or if you have the source
```shell
pip install .
```

## Usage

### Typical workflow

* The user writes the static parts of the document as usual (Word or Latex) but
  leaving sort of unique hashtags (\#tagname) for the calculation parts (double
  hash signs for Wrod).
* The calculations are written on a separate text file with any text editor
  (Notepad included) and saved next to the document file. For the syntax of the
  calculation file, see below. But it\'s just a python script with comments.
* The tool is invoked with the following command:
  ```shell  docal
  [calculation-file] [input-file] [output-file]
  ```
  so for example,
  ```shell
  docal calcs.py document.tex document-out.tex
  ```
  will be valid.  
* Then voila! what is needed is done. The output file can be used normally.

### Syntax

The syntax is simple. Just write the equations one line at a time. What you
write in the syntax is a valid python file, (it is just a script with a lot of
assignments and comments).  The following should be a good starting point.

```python
## foo.py
## necessary for scientific functions
from math import *

#foo

# The first side of the first triangle is
x_1 = 5 #m
# and the second,
y_1 = 6 #m
# Therefore the length of the hypotenuse will be,
z_1 = sqrt(x_1**2 + y_1**2) #m

#bar

# Now the second triangle has sides that have lengths of
x_2 = 3
y_2 = 4
# and therefore has a hypotenuse of
z_2 = sqrt(x_2**2 + y_2**2) #m,13

# Then, we can say that the hypotenuse of the first triangle which is #z_1 long
# is longer than that of the second which is #z_2 long.
```

Now, looking at the above example line by line,

* The first part (starting with double hash signs) serves as a real comment
  that does not do anything in python or in docal.
* The second is a python import statement, to make things such as sqrt, sin, pi
  available.
* The line that only contains a hashtag is treated as a message that what
  follows, until the next tag or the end should be sent to the document and at
  this particular place. That\'s why tags are necessary in the document. It
  looks for those tags in the document and replaces them with the modified
  versions of the calculations and paragraphs below it.
* The lines starting with single hash characters are taken as parts of running
  text (paragraphs).
* The lines with equal signs are treated as calculations. when they end with
  comments, the part after the hash character is treated as options for that
  calculation. (in the first three cases, we want to display the unit m
  displayed besides the variables that we assign to. And in the last equation,
  the additional 13 is taken as thouth the user wants only the first and the
  last steps displayed.)
* The last two comments (treated as paragraphs), have tags in them, which are
  interpreted as variable references and thus are substituted by formatted
  values of those variables.

The output of the above example, inserted into a plain word file, containing
only two tags, \#\#foo and \#\#bar will look like the following figure.

![Word document output](common/images/word-out.jpg?raw=true "Word document output")

## Known Issues

* You cannot use python statements that need indenting. This is because docal
  reads the script line by line and uses exec to make the necessary
  assignments, and since you can't continue an already indented code with exec,
  that will result in an error. If you have an idea to overcome this problem,
  feel free to contact me.

## TODO

### Long term

* Add unit awareness. Currently the units don't take part in the number
  manipulations. They just appear besides the values when a variable is
  referenced. This means the numbers will be the same with or without the
  units.


