| Name | docal JSON |
| Version |
3.0.5
JSON |
| download |
| home_page | None |
| Summary | Inject calculations into Word and LaTeX documents with ease! |
| upload_time | 2024-06-16 09:05:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
docal
math
latex
word
mathcad
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
docal
=====
[](https://pypi.python.org/pypi/docal)
Inject Python calculations into Word and LaTeX documents with ease!
- Free software: MIT license
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
A basic understanding of Python in general is necessary to have a smooth
experience here (although you will do fine even if you don\'t).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 from 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] -i [input-file] -o [output-file]
```
so for example,
```shell
docal calcs.py -i document.tex -o document-out.tex
```
- 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).
#### Comments that take whole lines
These comments are converted to paragraphs or equations, depending on
what comes immediately after the hash sign. If the hash sign is followed
by a single dollar sign (\$), the rest of that line is expected to be a
python equation, and will be converted to an inline LaTeX equation. If
what comes after the dollar sign is two dollar signs, the rest of that
line will be converted to a displayed (block) equation in the document.
Remember, these equations are still in comments, and thus do not do
anything except appear as equations. If the hash sign is followed by
just running text, it is converted to a paragraph text. In all cases,
when a hash character immediately followed by a variable name like \#x,
the value of that variable will be substituted at that place. When a
hash character immediately followed by an expression surrounded by
squirrely braces like \#{x + 2} is encountered, what is inside the
braces will be evaluated and substituted at that place.
#### Equations (python assignments)
These are the main focus points of this module. Obviously, they are
evaluated as normal in the script so that the value of the variable can
be reused as always, but when they appear in the document, they are
displayed as equation blocks that can have up to three steps (that show
the procedures). If it is a simple assignment, like `x = 10`, they
appear only having a single step, because there is no procedure to show.
If the assignment contains something to be evaluated but no variable
reference like `x = 10 + 5 / 2` or if it contains a single variable
reference like `x = x_prime` then the procedure will have only two
steps, first the equation and second the results. If the equation has
both things to be evaluated and variable references, like
`x = 5*x_prime + 10` then it will have three steps: the equation itself,
the equation with variable references substituted by their values, and
the result. These equations can be customized using comments at their
ends (see below).
##### Comments after equations (assignments)
These comments are taken to be customization options for the equations.
Multiple options can be separated by commas. The first option is units.
if you write something that looks like a unit (names or expressions of
names) like `N/m**2` they are correctly displayed as units next to the
result and whenever that variable is referenced, next to its value. The
next option is the display type of the steps. If the option is a single
dollar sign, the equation will be inline and if it has more than a
single step, the steps appear next to each other. If it is double dollar
signs, the equation(s) will be displayed as block (centered) equations.
Another option is step overrides. If it is a sequence of digits like
`12`, then only the steps corresponding to that number will be displayed
(for this case steps 1 and 2). The last option is matrix and array
cut-off size. Matrices are cut off and displayed with dots in them if
their sizes are grester than 10 by 10 and arrays are cut off if they
have more than 10 elements. To override this number, the option is the
letter m followed by a number like `m6`. If the option starts with a
hash sign like `#this is a note`, what follows will be a little note
that will be displayed next to the last step.
##### Comments that begin with double hash signs
If you begin a comment line witn double hash signs, like `## comment` it
is taken as a real comment. It will not do anything.
Example
-------
Let\'s say you have a word document `foo.docx` with contents like this.
And you write the calculations in the file `foo.py` next to `foo.docx`
```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, If we run the command
```shell
docal foo.py -o foo.docx
```
A third file, named `foo-out.docx` will appear. And it will look like
this.
Note
----
- Python's AST changes almost every release. And since this package depends on
that, supporting every new version of python will be like a moving target.
This project was developed against python 3.8 and since the syntax changes in
python 3.9 don't seem to affect this project, it should work with those
versions. But versions before 3.8 are not guaranteed to work for every use
case. I'm considering using a third party package that tries to solve this
specific problem, like [ast-compat](https://pypi.org/project/ast-compat/).
Raw data
{
"_id": null,
"home_page": null,
"name": "docal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "docal, math, latex, word, mathcad",
"author": null,
"author_email": "Kidus Adugna <kidusadugna@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/30/1f/359fed86813cb290dbcf542014f7271eff53105b212b7a026481840a974b/docal-3.0.5.tar.gz",
"platform": null,
"description": "docal\n=====\n\n[](https://pypi.python.org/pypi/docal)\n\nInject Python calculations into Word and LaTeX documents with ease!\n\n- Free software: MIT license\n\ndocal is a tool that can be used to send calculations that are written\nin python to Word or LaTeX documents. It evaluates equations in a\nseparate python script from the document and replaces hashtags in the\ndocument that indicate where the calculations should be with the results\nof the evaluation. It comes with a powerful python expression to LaTeX\nconverter built-in, so it converts the calculations and their results to\ntheir appropriate LaTeX forms before sending them, which makes it ideal\nto make academic and scientific reports.\n\nInstallation\n------------\n\n### Requirements\n\nA basic understanding of Python in general is necessary to have a smooth\nexperience here (although you will do fine even if you don\\'t).If you want to\nwork with a little more advanvced stuff, like arrays and matrices, more\nknowledge about python is necessary.\n\nIt must be obvious by now but you should have Python installed on your\nsystem. You can check that by opening your shell (see above) and typing\nthe command `python` and hitting Enter. If it writes the version number\nand other info about your python installation, you already have it\ninstalled. If the version number starts with 2, you should probably\ninstall python 3 (the latest). If you have python 3 or above, you\\'re\ngood to go. If either you don\\'t have Python 3 or you don\\'t have Python\nat all, you should go to [Python\\'s homepage](https://www.python.org)\nand install it, making sure to check the box \\\"add python to path\\\"\nduring installation.\n\nIf you want to work with word documents, you should have\n[Pandoc](https://pandoc.org) installed on your system (and in\nyour PATH). Because docal internally only works with tex files and when\na word file is given, it internally converts it to tex, modifies it and\nconverts it back to word, using pandoc.\n\n### Install\n\nTo install this package, (after making sure that you have a working\ninternet connection) type the following command and hit Enter.\n\n```shell\npip install docal\n```\n\nOr from the source:\n\n```shell\npip install .\n```\n\nUsage\n-----\n\n### Typical workflow\n\n- The user writes the static parts of the document as usual (Word or\n Latex) but leaving sort of unique hashtags (\\#tagname) for the\n calculation parts (double hash signs for Wrod).\n\n- The calculations are written on a separate text file with any text\n editor (Notepad included) and saved next to the document file. For\n the syntax of the calculation file, see below. But it\\'s just a\n python script with comments.\n\n- The tool is invoked with the following command:\n\n ```shell\n docal [calculation-file] -i [input-file] -o [output-file]\n ```\n\n so for example,\n\n ```shell\n docal calcs.py -i document.tex -o document-out.tex\n ```\n- Then voila! what is needed is done. The output file can be used\n normally.\n\n### Syntax\n\nThe syntax is simple. Just write the equations one line at a time. What\nyou write in the syntax is a valid Python file, (it is just a script\nwith a lot of assignments and comments).\n\n#### Comments that take whole lines\n\nThese comments are converted to paragraphs or equations, depending on\nwhat comes immediately after the hash sign. If the hash sign is followed\nby a single dollar sign (\\$), the rest of that line is expected to be a\npython equation, and will be converted to an inline LaTeX equation. If\nwhat comes after the dollar sign is two dollar signs, the rest of that\nline will be converted to a displayed (block) equation in the document.\nRemember, these equations are still in comments, and thus do not do\nanything except appear as equations. If the hash sign is followed by\njust running text, it is converted to a paragraph text. In all cases,\nwhen a hash character immediately followed by a variable name like \\#x,\nthe value of that variable will be substituted at that place. When a\nhash character immediately followed by an expression surrounded by\nsquirrely braces like \\#{x + 2} is encountered, what is inside the\nbraces will be evaluated and substituted at that place.\n\n#### Equations (python assignments)\n\nThese are the main focus points of this module. Obviously, they are\nevaluated as normal in the script so that the value of the variable can\nbe reused as always, but when they appear in the document, they are\ndisplayed as equation blocks that can have up to three steps (that show\nthe procedures). If it is a simple assignment, like `x = 10`, they\nappear only having a single step, because there is no procedure to show.\nIf the assignment contains something to be evaluated but no variable\nreference like `x = 10 + 5 / 2` or if it contains a single variable\nreference like `x = x_prime` then the procedure will have only two\nsteps, first the equation and second the results. If the equation has\nboth things to be evaluated and variable references, like\n`x = 5*x_prime + 10` then it will have three steps: the equation itself,\nthe equation with variable references substituted by their values, and\nthe result. These equations can be customized using comments at their\nends (see below).\n\n##### Comments after equations (assignments)\n\nThese comments are taken to be customization options for the equations.\nMultiple options can be separated by commas. The first option is units.\nif you write something that looks like a unit (names or expressions of\nnames) like `N/m**2` they are correctly displayed as units next to the\nresult and whenever that variable is referenced, next to its value. The\nnext option is the display type of the steps. If the option is a single\ndollar sign, the equation will be inline and if it has more than a\nsingle step, the steps appear next to each other. If it is double dollar\nsigns, the equation(s) will be displayed as block (centered) equations.\nAnother option is step overrides. If it is a sequence of digits like\n`12`, then only the steps corresponding to that number will be displayed\n(for this case steps 1 and 2). The last option is matrix and array\ncut-off size. Matrices are cut off and displayed with dots in them if\ntheir sizes are grester than 10 by 10 and arrays are cut off if they\nhave more than 10 elements. To override this number, the option is the\nletter m followed by a number like `m6`. If the option starts with a\nhash sign like `#this is a note`, what follows will be a little note\nthat will be displayed next to the last step.\n\n##### Comments that begin with double hash signs\n\nIf you begin a comment line witn double hash signs, like `## comment` it\nis taken as a real comment. It will not do anything.\n\nExample\n-------\n\nLet\\'s say you have a word document `foo.docx` with contents like this.\n\n\n\nAnd you write the calculations in the file `foo.py` next to `foo.docx`\n```python\n## foo.py\n## necessary for scientific functions:\nfrom math import *\n\n#foo\n\n# The first side of the first triangle is\nx_1 = 5 #m\n# and the second,\ny_1 = 6 #m\n# Therefore the length of the hypotenuse will be,\nz_1 = sqrt(x_1**2 + y_1**2) #m\n\n#bar\n\n# Now the second triangle has sides that have lengths of\nx_2 = 3\ny_2 = 4\n# and therefore has a hypotenuse of\nz_2 = sqrt(x_2**2 + y_2**2) #m,13\n\n# Then, we can say that the hypotenuse of the first triangle which is #z_1 long\n# is longer than that of the second which is #z_2 long.\n```\n\nNow, If we run the command \n\n```shell\ndocal foo.py -o foo.docx\n```\n\nA third file, named `foo-out.docx` will appear. And it will look like\nthis.\n\n\n\nNote\n----\n\n- Python's AST changes almost every release. And since this package depends on\n that, supporting every new version of python will be like a moving target.\n This project was developed against python 3.8 and since the syntax changes in\n python 3.9 don't seem to affect this project, it should work with those\n versions. But versions before 3.8 are not guaranteed to work for every use\n case. I'm considering using a third party package that tries to solve this\n specific problem, like [ast-compat](https://pypi.org/project/ast-compat/).\n",
"bugtrack_url": null,
"license": null,
"summary": "Inject calculations into Word and LaTeX documents with ease!",
"version": "3.0.5",
"project_urls": {
"Homepage": "https://github.com/K1DV5/docal",
"Issues": "https://github.com/K1DV5/docal/issues"
},
"split_keywords": [
"docal",
" math",
" latex",
" word",
" mathcad"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f88c4a6937830854164e2ed5f16f46027aebaec560afe472475a853183b6e6dc",
"md5": "01452f0656ce871ccf7dd69033de43eb",
"sha256": "1cdfb86c9cd643b208a6b29460f60ecdc4a0a2c770d2f187005b4fbebb21dc55"
},
"downloads": -1,
"filename": "docal-3.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01452f0656ce871ccf7dd69033de43eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 40497,
"upload_time": "2024-06-16T09:05:12",
"upload_time_iso_8601": "2024-06-16T09:05:12.556860Z",
"url": "https://files.pythonhosted.org/packages/f8/8c/4a6937830854164e2ed5f16f46027aebaec560afe472475a853183b6e6dc/docal-3.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "301f359fed86813cb290dbcf542014f7271eff53105b212b7a026481840a974b",
"md5": "65dc19c8c749b78731abc3a88164617f",
"sha256": "1ac4d785737a6f770fb4762cc7f1bbe77c8af55a14f48c414b8c2e6ad0fdb98c"
},
"downloads": -1,
"filename": "docal-3.0.5.tar.gz",
"has_sig": false,
"md5_digest": "65dc19c8c749b78731abc3a88164617f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 77412,
"upload_time": "2024-06-16T09:05:20",
"upload_time_iso_8601": "2024-06-16T09:05:20.006962Z",
"url": "https://files.pythonhosted.org/packages/30/1f/359fed86813cb290dbcf542014f7271eff53105b212b7a026481840a974b/docal-3.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-16 09:05:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "K1DV5",
"github_project": "docal",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "docal"
}
