├── zettels ├── __init__.py ├── resources │ └── zettels-grep-patterns ├── examples │ ├── Zettelkasten │ │ ├── onlies │ │ │ ├── yaml-test.md │ │ │ └── markdown-only.md │ │ ├── subdir │ │ │ ├── file4.md │ │ │ └── file5.md │ │ ├── file1.md │ │ ├── file2.md │ │ └── file3.md │ ├── zettels.cfg.yaml │ └── index.yaml ├── zettels_setup.py ├── zettelkasten.py ├── zettels.py └── zettelparser.py ├── MANIFEST.in ├── Makefile ├── CHANGELOG.md ├── .gitignore ├── README.md ├── setup.py ├── OLD-README.md └── LICENSE /zettels/__init__.py: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /zettels/resources/zettels-grep-patterns: -------------------------------------------------------------------------------- 1 | \-\-\-$ 2 | \.\.\.$ 3 | \[.*?\]\(.*?\) 4 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | # Include the license file 2 | include LICENSE 3 | include README.md 4 | include CHANGELOG.md 5 | recursive-include zettels/examples * 6 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/onlies/yaml-test.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Pure Yaml' 3 | author: 4 | - name: John Doe 5 | affiliation: University of Somewhere 6 | tags: [example, pureyaml] 7 | ... 8 | 9 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/subdir/file4.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'File 4' 3 | author: 4 | - name: John Doe 5 | affiliation: University of Somewhere 6 | tags: [example, fourth] 7 | followups: ['../file1.md'] 8 | ... 9 | 10 | This is points to [File 1 in the root directory](../file1.md) 11 | -------------------------------------------------------------------------------- /zettels/examples/zettels.cfg.yaml: -------------------------------------------------------------------------------- 1 | # This is a settings file for Zettels 2 | # see https://github.com/sthesing/Zettels 3 | rootdir: examples/Zettelkasten 4 | indexfile: examples/index.yaml 5 | outputformat: '{0[1]}' 6 | prettyformat: '{0[0]:<40}| {0[1]}' 7 | ignore: { 8 | #temporal files, hidden files, hidden directories 9 | '*~', 10 | '.*', 11 | '.*/', 12 | } 13 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/subdir/file5.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'File 5' 3 | author: Stefan Thesing 4 | tags: [] 5 | followups: [] 6 | --- 7 | 8 | # Let's see 9 | 10 | What happens if the metadata block doesn't end with three dots, but three 11 | dashes? And does it also work if the rest of the document contains "..."? 12 | And "---", too? 13 | And as a single line? 14 | ... 15 | And "---", too? 16 | --- 17 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/onlies/markdown-only.md: -------------------------------------------------------------------------------- 1 | This example file comes without a 2 | [yaml-metadata-block](http://pandoc.org/README.html#yaml_metadata_block) as 3 | suggested by pandoc. I contains, however not only the external link above, 4 | but also a relative link to [another file](../file2.md). The rest is not important. 5 | You can stop reading now. Seriously, nothing interesting beyond this point. I 6 | don't even know why I'm writing this. I could even break up in the middle of 7 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | build: clean 2 | # Source distribution 3 | python3 setup.py sdist 4 | # Wheel for python3 5 | python3 setup.py bdist_wheel 6 | 7 | clean: 8 | # Clean up files of previous builds 9 | rm -rf dist 10 | rm -rf build 11 | rm -rf zettels.egg-info 12 | 13 | install: 14 | # install locally in developer mode. Probably requires root privileges 15 | python3 -m pip install -e . 16 | 17 | test-release: 18 | # Upload to testpypi 19 | twine upload -r pypitest dist/* 20 | 21 | release: 22 | # Upload to pypi 23 | twine upload dist/* 24 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/file1.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'File 1' 3 | author: 4 | - name: John Doe 5 | affiliation: University of Somewhere 6 | tags: [example, first, test] 7 | followups: [file2.md, file3.md] 8 | ... 9 | 10 | My kinda people, my kinda place. There's something special about this place. 11 | Got no reason to stray too far, 'cause it's all right here in my own backyard! 12 | This is a Burger King town, it's made just for me! This is a Burger King town, 13 | we know how burgers should be! Right up the road, left at the sign. My way, 14 | your way, one at a time, hot off the fire with anything on it! And don't it 15 | feel good when it's just how you want it? This is a Burger King town, it's made 16 | just for me! This is a Burger King town, we know how burgers should be! 17 | 18 | The year is 1987 and NASA [launches](file2.md) the last of America's deep space 19 | probes. In a freak mishap, Ranger 3 and its pilot Captain William 'Buck' Rogers 20 | are blown out of their trajectory into an orbit which freezes his life support 21 | system and returns Buck Rogers to Earth five hundred years later. 22 | 23 | Steve Austin: Astronaut. A man barely alive. Gentlemen... we can rebuild him. 24 | We have the technology. We have the [capability](file3.md) to make the world's first bionic 25 | man. Steve Austin will be that man. Better than he was before. Better. 26 | Stronger. Faster. 27 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/file2.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'File 2' 3 | author: 4 | - name: John Doe 5 | affiliation: University of Somewhere 6 | tags: [example, second] 7 | followups: [] 8 | ... 9 | 10 | Here's [one more hyperlink](http://example.com). Let's see. 11 | 12 | Marshall, Will, and Holly on a routine expedition, met the greatest earthquake 13 | ever known. High on the rapids, it struck their tiny raft! And plunged them 14 | down a thousand feet below... to the Land of the Lost! Lost! Lost! Lost! Lost! 15 | 16 | Here's the story of a lovely lady, who was bringing up three very lovely girls. 17 | All of them had [hair](file3.md) of gold, like their mother, the youngest one 18 | in curls. Here's the store, of a man named Brady, who was busy with three boys 19 | of his own. They were four men, living all together, yet they were all alone. 20 | 'Til the one day when the lady met this fellow. And they knew it was much more 21 | than a hunch, that this group would somehow form a family. That's the way we 22 | all became the Brady Bunch, the Brady Bunch. That's the way we all became the 23 | Brady Bunch. The Brady Bunch! 24 | 25 | You unlock this door with the key of imagination. Beyond it is another 26 | dimension: a dimension of sound, a dimension of sight, a dimension of mind. 27 | You're moving into a land of both shadow and substance, of things and ideas; 28 | you've just crossed over into the Twilight Zone. 29 | 30 | 31 | -------------------------------------------------------------------------------- /zettels/examples/index.yaml: -------------------------------------------------------------------------------- 1 | files: 2 | file1.md: 3 | author: 4 | - {affiliation: University of Somewhere, name: John Doe} 5 | followups: [file2.md, file3.md] 6 | tags: [example, first, test] 7 | targets: [file2.md, file3.md] 8 | title: File 1 9 | file2.md: 10 | author: 11 | - {affiliation: University of Somewhere, name: John Doe} 12 | followups: [] 13 | tags: [example, second] 14 | targets: ['http://example.com', file3.md] 15 | title: File 2 16 | file3.md: 17 | author: 18 | - {affiliation: University of Somewhere, name: John Doe} 19 | followups: [] 20 | tags: [example, third] 21 | targets: [file1.md] 22 | title: File 3 23 | onlies/markdown-only.md: 24 | followups: [] 25 | tags: [] 26 | targets: ['http://pandoc.org/README.html#yaml_metadata_block', ../file2.md] 27 | title: untitled 28 | onlies/yaml-test.md: 29 | author: 30 | - {affiliation: University of Somewhere, name: John Doe} 31 | followups: [] 32 | tags: [example, pureyaml] 33 | targets: [] 34 | title: Pure Yaml 35 | subdir/file4.md: 36 | author: 37 | - {affiliation: University of Somewhere, name: John Doe} 38 | followups: [../file1.md] 39 | tags: [example, fourth] 40 | targets: [../file1.md] 41 | title: File 4 42 | subdir/file5.md: 43 | author: Stefan Thesing 44 | followups: [] 45 | tags: [] 46 | targets: [] 47 | title: File 5 48 | timestamp: 1497281891.8940217 49 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Change Log 2 | All notable changes to this project will be documented in this file. 3 | 4 | The format is based on [Keep a Changelog](http://keepachangelog.com/) 5 | and this project adheres to [Semantic Versioning](http://semver.org/). 6 | 7 | ## [Unreleased] 8 | ### Added 9 | - Migration info 10 | ### Changed 11 | ### Deprecated 12 | ### Removed 13 | ### Fixed 14 | ### Security 15 | 16 | ## [0.7.0] Reimplementation announcement 17 | 18 | And some old bugfixes 19 | 20 | ### Added 21 | ### Changed 22 | ### Deprecated 23 | ### Removed 24 | ### Fixed 25 | ### Security 26 | 27 | 28 | ## [0.6.0] 29 | ### Added 30 | ### Changed 31 | - Adjusted ignore settings in default settings file to ignore hidden 32 | directories, too. 33 | - Properly handling pandoc's specs for YAML metadata, now. Metadata block now 34 | may also end with '---'. 35 | - Reimplemented function to find updated files. Should be much faster now, 36 | when dealing with a large number of Zettels. Depending on UNIX tool `find` 37 | now, tested against GNU find. 38 | ### Deprecated 39 | ### Removed 40 | ### Fixed 41 | - With every run of zettels, the index was built from scratch. Now it only 42 | updates it if files in the Zettelkasten directory have changed. 43 | ### Security 44 | 45 | ## [0.5.0] - 2017-06-09 46 | ### Added 47 | - This change log 48 | ### Changed 49 | - dropped the `query` (or `q`) subcommand. So what used to be `zettels q` is 50 | now just `zettels`. 51 | - renamed the `-t` (or `--targets`) flag to `-l` (or `--links`) 52 | - First column of the default `pretty` output format is now 40 spaces wide 53 | ### Fixed 54 | - Issue with external links inside the markdown files (#9) 55 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Temporal files 2 | *~ 3 | 4 | # Byte-compiled / optimized / DLL files 5 | __pycache__/ 6 | *.py[cod] 7 | *$py.class 8 | 9 | # C extensions 10 | *.so 11 | 12 | # Distribution / packaging 13 | .Python 14 | env/ 15 | build/ 16 | develop-eggs/ 17 | dist/ 18 | downloads/ 19 | eggs/ 20 | .eggs/ 21 | lib/ 22 | lib64/ 23 | parts/ 24 | sdist/ 25 | var/ 26 | wheels/ 27 | *.egg-info/ 28 | .installed.cfg 29 | *.egg 30 | 31 | # PyInstaller 32 | # Usually these files are written by a python script from a template 33 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 34 | *.manifest 35 | *.spec 36 | 37 | # Installer logs 38 | pip-log.txt 39 | pip-delete-this-directory.txt 40 | 41 | # Unit test / coverage reports 42 | htmlcov/ 43 | .tox/ 44 | .coverage 45 | .coverage.* 46 | .cache 47 | nosetests.xml 48 | coverage.xml 49 | *.cover 50 | .hypothesis/ 51 | 52 | # Translations 53 | *.mo 54 | *.pot 55 | 56 | # Django stuff: 57 | *.log 58 | local_settings.py 59 | 60 | # Flask stuff: 61 | instance/ 62 | .webassets-cache 63 | 64 | # Scrapy stuff: 65 | .scrapy 66 | 67 | # Sphinx documentation 68 | docs/_build/ 69 | 70 | # PyBuilder 71 | target/ 72 | 73 | # Jupyter Notebook 74 | .ipynb_checkpoints 75 | 76 | # pyenv 77 | .python-version 78 | 79 | # celery beat schedule file 80 | celerybeat-schedule 81 | 82 | # SageMath parsed files 83 | *.sage.py 84 | 85 | # dotenv 86 | .env 87 | 88 | # virtualenv 89 | .venv 90 | venv/ 91 | ENV/ 92 | 93 | # Spyder project settings 94 | .spyderproject 95 | .spyproject 96 | 97 | # Rope project settings 98 | .ropeproject 99 | 100 | # mkdocs documentation 101 | /site 102 | 103 | # mypy 104 | .mypy_cache/ 105 | -------------------------------------------------------------------------------- /zettels/examples/Zettelkasten/file3.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'File 3' 3 | author: 4 | - name: John Doe 5 | affiliation: University of Somewhere 6 | tags: [example, third] 7 | followups: [] 8 | ... 9 | 10 | Spiderman, Spiderman, does whatever a spider can. Spins a web, any size, 11 | catches thieves just like flies, look out! Here comes the Spiderman. Is he 12 | strong? Listen bud, he's got radioactive blood. Can he swing from a thread? 13 | Take a look overhead. Hey there, there goes the Spiderman. In the chill of 14 | night at the scene of a crime, like a streak of light he arrives just in time! 15 | Spiderman, Spiderman, friendly neighborhood Spiderman. Wealth and fame, He's 16 | ignored. Action is his reward. To him, life is a great big bang up. Whenever 17 | there's a hang up, you'll find the Spiderman! 18 | 19 | Come and knock on our door. We've been waiting for you. Where the kisses are 20 | hers and hers and his, three's company, too! Come and dance on our floor. Take 21 | a step that is [new](file1.md). We've a lovable space that needs your face, 22 | three's company, too! You'll see that life is a ball again and laughter is 23 | callin' for you. Down at our rendezvous, three's company, too! 24 | 25 | Well we're movin' on up, to the east side. To a deluxe apartment in the sky. 26 | Movin' on up, To the east side. We finally got a piece of the pie. Fish don't 27 | fry in the kitchen, beans don't burn on the grill. Took a whole lotta tryin' 28 | just to get up that hill. Now we're up in the big leagues, gettin' our turn at 29 | bat. As long as we live, it's you and me baby, There ain't nothin' wrong with 30 | that. Well we're movin' on up, to the east side. To a deluxe apartment in the 31 | sky. Movin' on up, to the east side. We finally got a piece of the pie. 32 | 33 | 34 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Zettels 2 | Zettels is a command line tool implementing Niklas Luhmann's system of a 3 | "Zettelkasten". 4 | 5 | # Anouncement: Reimplementation 6 | 7 | This implementation of Zettels is no longer actively developed. Instead, I 8 | chose to reimplement Zettels from scratch in Rust. 9 | 10 | While doing so, I added a lot of features and separated the command line 11 | interface from the backend, which is now a library called `libzettels`, 12 | sporting an API that can be used to easily build other user interfaces. 13 | 14 | # Check the reimplementation out: 15 | 16 | ## 1. Zettels - Command line tool 17 | 18 | - [Repo](https://gitlab.com/sthesing/zettels) 19 | - [crates.io](https://crates.io/crates/zettels) 20 | 21 | ## 2. Libzettels - Backend 22 | 23 | - [Repo](https://gitlab.com/sthesing/libzettels) 24 | - [crates.io](https://crates.io/crates/libzettels) 25 | 26 | # Questions and answers 27 | 28 | ## Are users of the python implementation constrained to existing version? 29 | 30 | Essentially yes. I might fix a few critical bugs, but I strongly suggest 31 | migrating your Zettelkasten to the new Rust port. 32 | 33 | ## How can I migrate my existing Zettelkasten to the new implementation? 34 | 35 | If you want to switch to the new implementation, the following steps are 36 | necessary (the actual commands and configuration path might differ, 37 | depending on your os): 38 | 39 | 1. Uninstall the python version, e.g. `pip uninstall zettels` 40 | 2. Locate and delete the configuration of the python version, e.g. delete the 41 | directory `~/.config/zettels`. 42 | 3. Prepare the YAML-headers of your Zettel files. 43 | In the new implementation, the `tags` field of the header has been renamed 44 | `keywords`. So you need to edit the metadata of each zettel accordingly. 45 | The easiest way to do this for all your Zettel files at once by using `sed`, 46 | which is common on UNIX-like operating systems. 47 | Inside your Zettelkasten directory, run: 48 | 49 | `sed -i -e 's/tags:/keywords:/g' *.md` 50 | 51 | That assumes that your zettel files have the `.md` extension. If not, 52 | modify accordingly. If you have organized your Zettelkasten in 53 | subdirectories, you might need to repeat the process in each subdirectory 54 | or modify the `*.md` part of the command so it fits your needs. 55 | 4. Install the 56 | [new implementation of Zettels](https://gitlab.com/sthesing/zettels#installation) 57 | 5. Run setup: `zettels setup` 58 | 59 | ## Where is the old README? 60 | 61 | - [OLD-README.md](OLD-README.md) 62 | -------------------------------------------------------------------------------- /zettels/zettels_setup.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env python3 2 | 3 | ##This file is part of Zettels. 4 | ## 5 | ##Zettels is free software: you can redistribute it and/or modify 6 | ##it under the terms of the GNU General Public License as published by 7 | ##the Free Software Foundation, either version 3 of the License, or 8 | ##(at your option) any later version. 9 | ## 10 | ##Zettels is distributed in the hope that it will be useful, 11 | ##but WITHOUT ANY WARRANTY; without even the implied warranty of 12 | ##MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 | ##GNU General Public License for more details. 14 | ## 15 | ##You should have received a copy of the GNU General Public License 16 | ##along with Zettels. If not, see http://www.gnu.org/licenses/. 17 | 18 | """ 19 | Setup tool for Zettels 20 | """ 21 | import os 22 | import sys 23 | import xdg.BaseDirectory 24 | 25 | def _generate_settings(): 26 | """ 27 | Interactively generate settings. 28 | """ 29 | # Get the standard directory for settings. Create it, if not present. 30 | settings_base_dir = xdg.BaseDirectory.save_config_path('Zettels') 31 | 32 | # Defaults 33 | rootdir = os.getcwd() 34 | indexfile = settings_base_dir + '/index.yaml' 35 | outputformat = '{0[1]}' 36 | prettyformat = '{0[0]:<40}| {0[1]}' 37 | ignore = ['*~', '.*', '.*/'] 38 | 39 | # Ask the user 40 | 41 | # Root dir 42 | print('Please specify the root directory of your Zettelkasten.') 43 | print('It will contain the Zettel files.') 44 | rootdir = input("Default is the current directory: '" 45 | + rootdir + "': ") or rootdir 46 | 47 | # Index file 48 | print('Please specify the file containing the index of your Zettelkasten.') 49 | indexfile = input("Default is: '" + indexfile + "': ") or indexfile 50 | 51 | print() 52 | print("These are your settings:") 53 | print("------------------------") 54 | print("Root directory:", rootdir) 55 | print("Index file:", indexfile) 56 | 57 | correct = input("Are these correct? y/n, Default is 'y': ") 58 | if correct == "n" or correct == "N": 59 | startover = input("Do you want so start over? y/n, Default is y: ") 60 | if startover == "n" or startover == "N": 61 | exit() 62 | else: 63 | print("Starting over...") 64 | print() 65 | generate_settings() 66 | else: 67 | f = open(os.path.join(settings_base_dir, 'zettels.cfg.yaml'), 'w') 68 | f.write("# This is a settings file for Zettels\n") 69 | f.write("# see https://github.com/sthesing/Zettels\n") 70 | f.write('rootdir: ' + rootdir + '\n') 71 | f.write('indexfile: ' + indexfile + '\n') 72 | f.write('outputformat: \'' + outputformat + '\'\n') 73 | f.write('prettyformat: \'' + prettyformat + '\'\n') 74 | f.write('ignore: {\n') 75 | f.write(' # temporal files, hidden files, hidden directories\n') 76 | for p in ignore: 77 | f.write(' \''+ p + '\',\n') 78 | f.write('}\n') 79 | f.close() 80 | 81 | print("Settings written to '" + os.path.join(settings_base_dir, 'zettels.cfg.yaml') + "'.") 82 | exit() 83 | 84 | def generate_settings(): 85 | try: 86 | _generate_settings() 87 | except KeyboardInterrupt: 88 | print() 89 | print("Aborted by user") 90 | 91 | if __name__ == "__main__": 92 | generate_settings() 93 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | """A setuptools based setup module. 2 | 3 | """ 4 | 5 | # Always prefer setuptools over distutils 6 | from setuptools import setup, find_packages 7 | # To use a consistent encoding 8 | from codecs import open 9 | from os import path 10 | 11 | version = '0.7.1' 12 | 13 | here = path.abspath(path.dirname(__file__)) 14 | 15 | # Get the long description from the README file 16 | try: 17 | import pypandoc 18 | long_description = pypandoc.convert('README.md', 'rst') 19 | except(IOError, ImportError): 20 | with open(path.join(here, 'README.md'), encoding='utf-8') as f: 21 | long_description = f.read() 22 | 23 | setup( 24 | name='zettels', 25 | version=version, 26 | description='A command line tool implementing Luhmann\'s system of a "Zettelkasten".', 27 | long_description=long_description, 28 | 29 | # The project's main homepage. 30 | url='https://github.com/sthesing/Zettels', 31 | 32 | # Author details 33 | author='Stefan Thesing', 34 | author_email='software@webdings.de', 35 | 36 | # Choose your license 37 | license='GPLv3+', 38 | 39 | # See https://pypi.python.org/pypi?%3Aaction=list_classifiers 40 | classifiers=[ 41 | # How mature is this project? Common values are 42 | # 3 - Alpha 43 | # 4 - Beta 44 | # 5 - Production/Stable 45 | 'Development Status :: 3 - Alpha', 46 | 47 | # Indicate who your project is intended for 48 | 'Intended Audience :: Science/Research', 49 | 'Intended Audience :: Education', 50 | 'Topic :: Text Processing :: Indexing', 51 | 'Topic :: Other/Nonlisted Topic', 52 | 53 | 54 | # Pick your license as you wish (should match "license" above) 55 | 'License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)', 56 | 57 | # Specify the Python versions you support here. In particular, ensure 58 | # that you indicate whether you support Python 2, Python 3 or both. 59 | 'Programming Language :: Python :: 3', 60 | 'Programming Language :: Python :: 3.3', 61 | 'Programming Language :: Python :: 3.4', 62 | 'Programming Language :: Python :: 3.5', 63 | ], 64 | 65 | # What does your project relate to? 66 | keywords='notetaking zettelkasten', 67 | 68 | # You can just specify the packages manually here if your project is 69 | # simple. Or you can use find_packages(). 70 | #packages=find_packages(exclude=['contrib', 'docs', 'tests']), 71 | packages = ['zettels'], 72 | 73 | include_package_data=True, 74 | 75 | # List run-time dependencies here. These will be installed by pip when 76 | # your project is installed. For an analysis of "install_requires" vs pip's 77 | # requirements files see: 78 | # https://packaging.python.org/en/latest/requirements.html 79 | install_requires=['PyYAML', 'pathspec>=0.5.0'], 80 | 81 | # List additional groups of dependencies here (e.g. development 82 | # dependencies). You can install these using the following syntax, 83 | # for example: 84 | # $ pip install -e .[dev,test] 85 | extras_require={ 86 | 'dev': ['check-manifest', 'pypandoc'], 87 | 'test': ['coverage'], 88 | }, 89 | 90 | # If there are data files included in your packages that need to be 91 | # installed, specify them here. If using Python 2.6 or less, then these 92 | # have to be included in MANIFEST.in as well. 93 | package_data={ 94 | 'zettels': ['resources/*'], 95 | }, 96 | 97 | # To provide executable scripts, use entry points in preference to the 98 | # "scripts" keyword. Entry points provide cross-platform support and allow 99 | # pip to create the appropriate form of executable for the target platform. 100 | entry_points={ 101 | 'console_scripts': [ 102 | 'zettels = zettels.zettels:main', 103 | ], 104 | }, 105 | ) 106 | -------------------------------------------------------------------------------- /OLD-README.md: -------------------------------------------------------------------------------- 1 | # Zettels 2 | Zettels is a command line tool implementing Niklas Luhmann's system of a 3 | "Zettelkasten". 4 | 5 | It's still in alpha stage and probably very buggy. 6 | 7 | ## What does Zettels do? 8 | 9 | Zettels is a command line tool to index markdown files (your 10 | zettels). It reads YAML-metadata blocks as defined by [pandoc](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block) and also 11 | parses the 12 | [markdown hyperlinks](https://daringfireball.net/projects/markdown/syntax#link) 13 | in each file. 14 | 15 | The resulting index contains the metadata and the targets of the hyperlinks. 16 | 17 | Have a look at the files in `examples/Zettelkasten` and `examples/index.yaml` 18 | to get a better idea. 19 | 20 | Zettels can also be used to query the index. The output can then be piped 21 | to other tools (like grep or as arguments for the text editor of your choice). 22 | 23 | It's intended to be used for a "Zettelkasten" like Niklas Luhmann used it. 24 | 25 | ## What the heck is a Zettelkasten? 26 | 27 | "Zettel" is German for "note" or "slip of paper". "Kasten" is German for "box". 28 | Think of old style library catalogues. 29 | 30 | Obviously, this piece of software is not a box of paper sheets. However, 31 | [Niklas Luhmann](https://en.wikipedia.org/wiki/Niklas_Luhmann) used such a 32 | box in a very specific way for his academic work. 33 | 34 | A wonderful introduction in Luhmann's system of a Zettelkasten are the slides 35 | of a talk by Daniel Lüdecke: [Introduction to Luhmann's Zettelkasten-Thinking](https://strengejacke.wordpress.com/2015/10/07/introduction-to-luhmanns-zettelkasten-thinking-and-its-technical-implementation/) 36 | 37 | In Luhmann's own words: [Communicating with Slip Boxes](http://luhmann.surge.sh/communicating-with-slip-boxes) (translation of 38 | "Kommunikation mit Zettelkästen"). 39 | 40 | If you speak German, there's more: 41 | 42 | - Luhmann, Niklas (1981): Kommunikation mit Zettelkästen. Ein Erfahrungsbericht. 43 | in: H. Baier / H.M. Kepplinger / K. Reumann (Eds.), Öffentliche Meinung und sozialer 44 | Wandel. Opladen: Westdeutscher Verlag. pp. 22-28 45 | - Daniel Lüdecke: [Luhmanns Arbeitsweise im elektronischen Zettelkasten](https://strengejacke.wordpress.com/2015/09/08/luhmanns-arbeitsweise-im-elektronischen-zettelkasten/) 46 | - Thomas Schlesinger: [Wissen konservieren und kuratieren mit dem Zettelkasten nach Niklas Luhmann](http://www.schlesisblog.de/2016/09/wissen-konservieren-und-kuratieren-mit.html) 47 | - Universität Bielefeld: Video - [Einblicke in das System der Zettel - Geheimnis um Niklas Luhmanns Zettelkasten](https://youtu.be/4veq2i3teVk) 48 | 49 | ## What, no GUI? 50 | 51 | True. A GUI for querying the index would be nice. However, as such, Zettels 52 | doesn't provide one. It is intended to be used in a toolchain of UNIX-tools. 53 | 54 | I myself edit my Zettelkasten in my favourite text editor and have created 55 | a little module that allows me to query its index from there. So, if you use 56 | Textadept or don't care which text editor you use, have a look at 57 | [ta-zettels](https://github.com/sthesing/ta-zettels). 58 | 59 | ### Alternatives 60 | 61 | If you're looking for a GUI, all-in-one approach to implementing Luhmann's idea 62 | into software, I can recommend Daniel Lüdecke's [Zettelkasten](http://zettelkasten.danielluedecke.de/) (sjPlot/Zettelkasten). 63 | 64 | ## Installation and setup 65 | 66 | 1. Install using pip (or pip3, depending on your OS): `pip install zettels` 67 | 2. Run `zettels --setup` – follow the interactive setup process 68 | 3. Run `zettels -su` once to initially build the index. 69 | 70 | ## Usage 71 | 72 | Run `zettels -h` for a complete list of options. Some 73 | examples: 74 | 75 | ### Build or update the index: 76 | ``` 77 | zettels -su 78 | ``` 79 | Shorthand for `--silentupdate` 80 | 81 | ### Querying the index 82 | Show a list of all zettels: 83 | ``` 84 | zettels 85 | ``` 86 | Show a list of all zettels, but update the index first: 87 | ``` 88 | zettels -u 89 | ``` 90 | Show info about a specific zettel, e.g. file1.md: 91 | ``` 92 | zettels file1.md 93 | ``` 94 | Show info about two zettels, e.g. file1.md and file2.md: 95 | ``` 96 | zettels file1.md file2.md 97 | ``` 98 | Show a list of followups of a specific zettel, e.g. file1.md: 99 | ``` 100 | zettels -f file1.md 101 | ``` 102 | Show a list of zettels a specific zettel links to, e.g. file1.md: 103 | ``` 104 | zettels -l file1.md 105 | ``` 106 | Show a list of zettels linking to a specific zettel, e.g. file1.md: 107 | ``` 108 | zettels -i file1.md 109 | ``` 110 | And finally, a bit of fun with pipes: 111 | Let's say you want to see which zettels apart from file1.md 112 | itself link to the followups of file1.md: 113 | ``` 114 | zettels -f file1.md | zettels -i | grep -v file1.md 115 | ``` 116 | 117 | ### Try it with example data 118 | Run e.g. 119 | ``` 120 | zettels -s examples/zettels.cfg.yaml examples/Zettelkasten/file1.md 121 | ``` 122 | 123 | ## Zettel format 124 | 125 | Zettels doesn't require your markdown files to have a metadata block. But to 126 | be really effective parts of your Zettelkasten, a YAML metadata block 127 | containing an entry for `title`, `tags` and `followups` is necessary. 128 | 129 | ```{.yaml} 130 | --- 131 | title: 'Example Zettel' 132 | tags: [example, question] 133 | followups: [file.md, subdir/anotherfile.md, ../yetanotherfile.md] 134 | ... 135 | ``` 136 | 137 | If no such metadata is present, Zettels will replace it with appropriate 138 | "empty" values in the index: 139 | 140 | - `title`: "untitled" 141 | - `tags`: "[]" 142 | - `followups`: "[]" 143 | 144 | Instead of finishing the metadata block with `...` you can also use `---`. 145 | ```{.yaml} 146 | --- 147 | title: 'Example Zettel' 148 | tags: [example, question] 149 | followups: [file.md, subdir/anotherfile.md, ../yetanotherfile.md] 150 | --- 151 | ``` 152 | 153 | In fact, a zettel file may contain several YAML-blocks. However, Zettels will 154 | only parse the first one. 155 | The metadata block may contain a variety of other entries (e.g. `author`, 156 | `date`) – maybe for other tools, like pandoc – but those other entries are 157 | ignored by Zettels and do not become part of Zettels' index. 158 | 159 | To manually link between zettels, use the "inline syntax" for markdown 160 | hyperlinks: 161 | ```[.markdown] 162 | [link text](url) 163 | ``` 164 | 165 | Links between zettel files should be relative links. The same is true for 166 | entries in `followups`. 167 | 168 | ## Output format 169 | 170 | The output can be tweaked to your needs. In the 171 | settings file (default: ~/.config/zettels.cfg.yaml), you'll find two settings: 172 | 173 | - `outputformat` - standard format 174 | - `prettyformat` - used when Zettels is called with the `--pretty` flag 175 | 176 | These output formats are given as 177 | [Python Format Strings](https://docs.python.org/3.6/library/string.html#format-string-syntax). 178 | Query output consists of two fields that these format strings can process: 179 | 180 | 1. title - accessible by `'{0[0]}'` 181 | 2. path (relative to the Zettelkasten directory) - accessible by `'{0[1]}'` 182 | 183 | By default the formats are: 184 | ``` 185 | outputformat: '{0[1]}' 186 | prettyformat: '{0[0]:<40}| {0[1]}' 187 | ``` 188 | 189 | Standard `outputformat` just outputs the path(s) of the query results, 190 | `prettyformat` is a pseudo-table with the title(s) of the query result in 191 | the first column (which is at least 40 characters wide), and the path(s) in 192 | the second column. 193 | 194 | The output format can also be tweaked on a per call basis with the `-o` flag, 195 | that takes a custom output format. 196 | 197 | See the 198 | [Python Format String Syntax](https://docs.python.org/3.6/library/string.html#format-string-syntax) 199 | for details. 200 | 201 | ## Requirements 202 | 203 | - Python 3.x 204 | - [grep](https://www.gnu.org/software/grep/) & [find](https://www.gnu.org/software/findutils)– Your Python runtime must be able to find and execute the UNIX tools `grep` and `find`. Zettels is tested against GNU grep and GNU find, but other implementations should be fine, too. 205 | - [PyYaml](http://pyyaml.org/) 206 | - [pathspec](https://pypi.python.org/pypi/pathspec)>=0.5.0 207 | - XDG and Python Bindings for XDG 208 | -------------------------------------------------------------------------------- /zettels/zettelkasten.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf8 -*- 2 | ## Copyright (c) 2017 Stefan Thesing 3 | ## 4 | ##This file is part of Zettels. 5 | ## 6 | ##Zettels is free software: you can redistribute it and/or modify 7 | ##it under the terms of the GNU General Public License as published by 8 | ##the Free Software Foundation, either version 3 of the License, or 9 | ##(at your option) any later version. 10 | ## 11 | ##Zettels is distributed in the hope that it will be useful, 12 | ##but WITHOUT ANY WARRANTY; without even the implied warranty of 13 | ##MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 | ##GNU General Public License for more details. 15 | ## 16 | ##You should have received a copy of the GNU General Public License 17 | ##along with Zettels. If not, see http://www.gnu.org/licenses/. 18 | 19 | import logging 20 | import os 21 | 22 | logger = logging.getLogger('Zettels.' + __name__) 23 | 24 | class Zettelkasten: 25 | 26 | ###################### 27 | # Constructor # 28 | ###################### 29 | def __init__(self, index, rootdir): 30 | """Inits Zettelkasten class 31 | 32 | :param index: an index of the Zettels generated by Zettelparser 33 | :param rootdir: path to the directory containing the Zettels 34 | """ 35 | self.index = index 36 | self.rootdir = rootdir 37 | 38 | ###################### 39 | # Operations # 40 | ###################### 41 | 42 | def get_list_of_zettels(self, as_output=False, outputformat='{0[0]:<50}| {0[1]}'): 43 | """ 44 | Get a list of all Zettels from the index. 45 | 46 | :return: A list of Zettels. If as_output is set to True, the list 47 | contains strings formated by outputformat. Otherwise, it contains 48 | tuples. One tuple for each Zettel in the index. 49 | Each tuple contains: 50 | - Title of the Zettel 51 | - Path of the Zettel relative to rootdir 52 | """ 53 | zettels = [] 54 | for zettel in self.index['files']: 55 | tup = (self.index['files'][zettel]['title'], zettel) 56 | 57 | if as_output: 58 | zettels.append(outputformat.format(tup)) 59 | else: 60 | zettels.append(tup) 61 | 62 | if as_output: 63 | zettels.sort(key=str.lower) 64 | 65 | return zettels 66 | 67 | def get_title_of(self, zettel): 68 | """ 69 | Get the Title of a Zettel from the index. 70 | 71 | :param zettel: path to a Zettel file 72 | :return: Title of the Zettel as a String 73 | """ 74 | 75 | # Make the path to the file relative to the root directory 76 | zettel = os.path.relpath(zettel, self.rootdir) 77 | return self.index['files'][zettel]['title'] 78 | 79 | def get_followups_of(self, zettel, as_output=False, outputformat='{0[0]:<40}| {0[1]}'): 80 | """ 81 | Get the Followups of a Zettel from the index. 82 | 83 | :param zettel: path to a Zettel file 84 | :param index: An existing index. 85 | :return: A list of tuples. Each tuple contains: 86 | - Title of the followup 87 | - Path of the followup relative to rootdir 88 | """ 89 | # First, absolute path of zettel 90 | # In fact, we need the real path (desolving symlinks) 91 | zettel = os.path.realpath(zettel) 92 | logger.debug("Real path to ZETTEL: " + str(zettel)) 93 | 94 | # Make the path to the file relative to the root directory 95 | # To do that, we need the real path, too 96 | logger.debug("Real path to root Dir: " + str(os.path.realpath(self.rootdir))) 97 | 98 | zettel = os.path.relpath(zettel, os.path.realpath(self.rootdir)) 99 | logger.debug("Relative path to ZETTEL: " + str(zettel)) 100 | zetdir = os.path.dirname(zettel) 101 | logger.debug("Dirname of ZETTEL: " + str(zetdir)) 102 | 103 | followups = [] 104 | for followup in self.index['files'][zettel]['followups']: 105 | followup = os.path.normpath(os.path.join(zetdir, followup)) 106 | tup = (self.index['files'][followup]['title'], followup) 107 | 108 | if as_output: 109 | followups.append(outputformat.format(tup)) 110 | else: 111 | followups.append(tup) 112 | 113 | if as_output: 114 | followups.sort(key=str.lower) 115 | 116 | return followups 117 | 118 | def get_targets_of(self, zettel, as_output=False, outputformat='{0[0]:<40}| {0[1]}'): 119 | """ 120 | Get the targets of a Zettel's hyperlinks from the index. 121 | 122 | :param zettel: path to a Zettel file 123 | :param index: An existing index. 124 | :return: A list of tuples. Each tuple contains: 125 | - Title of the target 126 | - Path of the target relative to rootdir 127 | """ 128 | # First, real path of zettel 129 | zettel = os.path.realpath(zettel) 130 | 131 | # Make the path to the file relative to the root directory 132 | zettel = os.path.relpath(zettel, os.path.realpath(self.rootdir)) 133 | zetdir = os.path.dirname(zettel) 134 | 135 | targets = [] 136 | for target in self.index['files'][zettel]['targets']: 137 | # is it an intenal link to another zettel? 138 | try: 139 | normtarget = os.path.normpath(os.path.join(zetdir, target)) 140 | tup = (self.index['files'][normtarget]['title'], normtarget) 141 | except KeyError: 142 | tup = ("External link", target) 143 | 144 | if as_output: 145 | targets.append(outputformat.format(tup)) 146 | else: 147 | targets.append(tup) 148 | 149 | if as_output: 150 | targets.sort(key=str.lower) 151 | 152 | return targets 153 | 154 | def get_incoming_of(self, zettel, as_output=False, outputformat='{0[0]:<40}| {0[1]}'): 155 | """ 156 | Get the Sources of incoming links to a Zettel from the index. 157 | 158 | :param zettel: path to a Zettel file 159 | :return: A list of tuples. Each tuple contains: 160 | - Title of the incoming link's source 161 | - Path of the source relative to rootdir 162 | """ 163 | # First, real path of zettel 164 | zettel = os.path.realpath(zettel) 165 | 166 | # Make the path to the file relative to the root directory 167 | zettel = os.path.relpath(zettel, os.path.realpath(self.rootdir)) 168 | zetdir = os.path.dirname(zettel) 169 | 170 | # Start with an empty list of sources 171 | sources = [] 172 | 173 | # Iterate over the whole index 174 | for f in self.index['files']: 175 | # For every file, read the targets of its links, as well as 176 | # its followups from index 177 | 178 | # empty lists 179 | targets = [] 180 | followups = [] 181 | 182 | # The dir part of f's path, relative to root dir 183 | fdir = os.path.dirname(f) 184 | 185 | try: 186 | # Get the targets from index and replace the empty list 187 | # We could do the following: 188 | # targets = self.index['files'][f]['targets'] 189 | # However, the links contained in targets are relative to the 190 | # file f. We have to make them relative to rootdir. 191 | # So we do this: 192 | for target in self.index['files'][f]['targets']: 193 | targets.append(os.path.normpath(os.path.join(fdir, target))) 194 | 195 | # Same for followups 196 | for followup in self.index['files'][f]['followups']: 197 | followups.append(os.path.normpath(os.path.join(fdir, followup))) 198 | except KeyError: 199 | # Throw an error if the index has no target property for 200 | # the file in question. In that case we continue with the 201 | # empty list, meaning we don't do anything 202 | logger.debug(f + "has no target property. That's a sign for \ 203 | a malformed index. Continuing program, but expect output to \ 204 | be wrong.") 205 | logger.debug(sys.exc_info()[1]) 206 | 207 | # Check if our zettel file is among the targets. If so, 208 | # write the current f to our list of sources 209 | if zettel in targets: 210 | tup = (self.index['files'][f]['title'], f) 211 | if as_output: 212 | sources.append(outputformat.format(tup)) 213 | else: 214 | sources.append(tup) 215 | if zettel in followups: 216 | tup = (self.index['files'][f]['title'], f) 217 | if as_output: 218 | sources.append(outputformat.format(tup)) 219 | else: 220 | sources.append(tup) 221 | 222 | # remove duplicates 223 | sources = list(set(sources)) 224 | sources.sort() 225 | 226 | return sources 227 | 228 | def get_tags_of(self, zettel, as_output=False, outputformat='{0[0]:<40}| {0[1]}'): 229 | """ 230 | Get the tags of a Zettel from the index. 231 | 232 | :param zettel: path to a Zettel file 233 | :param index: An existing index. 234 | :return: A list of tags 235 | """ 236 | # First, real path of zettel 237 | zettel = os.path.realpath(zettel) 238 | 239 | # Make the path to the file relative to the root directory 240 | zettel = os.path.relpath(zettel, os.path.realpath(self.rootdir)) 241 | zetdir = os.path.dirname(zettel) 242 | 243 | tags = [] 244 | for tag in self.index['files'][zettel]['tags']: 245 | tags.append(tag) 246 | 247 | return tags 248 | 249 | def get_zettels_tagged_with(self, tag): 250 | """This function returns a list of Zettels contained in the index that 251 | are tagged with the specified tag. The list actually 252 | contains tuples: Title of the file and the path to the file. 253 | 254 | :param tag: the tag searched for 255 | :return: A list of tuples. Each tuple contains: 256 | - Title of the Zettel 257 | - Path to the Zettel as given in the index 258 | """ 259 | # Start with an empy list 260 | taggedzettels = [] 261 | # search index 262 | for f in index['files']: 263 | if tag in index['files'][f]['tags']: 264 | taggedzettels.append((index['files'][f]['title'],f)) 265 | return taggedzettels 266 | -------------------------------------------------------------------------------- /zettels/zettels.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env python3 2 | 3 | # -*- coding: utf8 -*- 4 | ## Copyright (c) 2017 Stefan Thesing 5 | ## 6 | ##This file is part of Zettels. 7 | ## 8 | ##Zettels is free software: you can redistribute it and/or modify 9 | ##it under the terms of the GNU General Public License as published by 10 | ##the Free Software Foundation, either version 3 of the License, or 11 | ##(at your option) any later version. 12 | ## 13 | ##Zettels is distributed in the hope that it will be useful, 14 | ##but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | ##MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | ##GNU General Public License for more details. 17 | ## 18 | ##You should have received a copy of the GNU General Public License 19 | ##along with Zettels. If not, see http://www.gnu.org/licenses/. 20 | 21 | """ 22 | Zettels is a command line tool implementing Niklas Luhmann's system of a "Zettelkasten". 23 | """ 24 | 25 | __version__ = '0.6.0' 26 | __author__ = 'Stefan Thesing' 27 | 28 | # Libraries 29 | import argparse 30 | import collections.abc 31 | import logging 32 | import os 33 | import sys 34 | import xdg.BaseDirectory 35 | import yaml 36 | 37 | # local imports 38 | from zettels.zettelparser import Zettelparser 39 | from zettels.zettelkasten import Zettelkasten 40 | import zettels.zettels_setup as setup 41 | 42 | # Module variables 43 | settings_base_dir = xdg.BaseDirectory.save_config_path('Zettels') 44 | logger = logging.getLogger('Zettels') 45 | 46 | 47 | ################################# 48 | # Internal methods used by main # 49 | ################################# 50 | 51 | def _connect_dev_arguments(parser): 52 | # Command line arguments that are "Developer options" should be available 53 | # in subcommands, too. To make it available to both parser and 54 | # eventual subparsers, while avoiding redundant code, this function 55 | # connects them to the parser specified as this function's parameter. 56 | 57 | #group_dev = parser.add_argument_group('Developer options', 'These are \ 58 | # probably only useful for developers.') 59 | group_dev = parser.add_argument_group('Developer options') 60 | 61 | group_dev.add_argument('-s', '--settings', help='relative or absolute \ 62 | path to a settings file. Useful if you have several distinct \ 63 | collections of Zettels (e.g. one for testing the program and one \ 64 | you actually use.). Default is "' + settings_base_dir + '/zettels.cfg.yaml"', 65 | default= settings_base_dir + '/zettels.cfg.yaml') 66 | group_dev.add_argument('-v', '--verbose', help='Output verbose logging \ 67 | messages to stdout. VERY verbose messages.', 68 | action="store_true") 69 | 70 | def _setup_logging(verbose=False): 71 | logger = logging.getLogger('Zettels') 72 | 73 | if verbose: 74 | logger.setLevel(logging.DEBUG) 75 | handler = logging.StreamHandler(sys.stdout) 76 | else: 77 | logger.setLevel(logging.INFO) 78 | handler = logging.StreamHandler() 79 | 80 | 81 | handler.setFormatter(logging.Formatter( 82 | '%(asctime)s - ' 83 | + '%(name)s - ' 84 | + '%(levelname)s - ' 85 | + '%(message)s' 86 | )) 87 | 88 | logger.addHandler(handler) 89 | 90 | return logger 91 | 92 | def _read_settings(f): 93 | try: 94 | f = open(f, 'r') 95 | settings = yaml.safe_load(f.read()) 96 | f.close() 97 | # We should have received a Dictionary or other mapping type 98 | if isinstance(settings, collections.abc.Mapping): 99 | rootdir = settings['rootdir'] 100 | # check wether rootdir exists 101 | if os.path.exists(os.path.abspath(os.path.expanduser(rootdir))): 102 | rootdir = os.path.abspath(os.path.expanduser(rootdir)) 103 | else: 104 | # TODO Raise an appropriate error 105 | logger.error("Rootdir path: " + 106 | os.path.abspath(os.path.expanduser(rootdir)) + 107 | " doesn't exist. Exiting") 108 | exit() 109 | indexfile = settings['indexfile'] 110 | indexfile = os.path.abspath(os.path.expanduser(indexfile)) 111 | outputformat = settings['outputformat'] 112 | prettyformat = settings['prettyformat'] 113 | ignore_patterns = settings['ignore'] 114 | return rootdir, indexfile, outputformat, prettyformat, ignore_patterns 115 | else: 116 | print("There seems to be a problem with your settings \ 117 | file. Zettels expected to receive a dictionary or other \ 118 | mapping type. Received" , str(type(settings)), " instead.") 119 | exit() 120 | except FileNotFoundError: 121 | logger.error(sys.exc_info()[1]) 122 | #print(sys.exc_info()[2]) 123 | logger.error("Settings file not found. Please specify a correct one or run \ 124 | Zettels with the --setup parameter to generate one.") 125 | exit() 126 | except yaml.YAMLError: 127 | logger.error("There seems to be a problem with your settings file. Is it \ 128 | valid YAML?") 129 | logger.error(sys.exc_info()[1]) 130 | exit() 131 | except KeyError: 132 | logger.error("There seems to be a problem with your settings file. At least \ 133 | one required setting is missing:" , str(sys.exc_info()[1])) 134 | exit() 135 | 136 | def _query(args): 137 | logger.debug(args) 138 | 139 | # Next, let's read the settings file. _read_settings(settings) does the 140 | # error handling 141 | rootdir, indexfile, outputformat, prettyformat, ignore_patterns = _read_settings(args.settings) 142 | # If we're still running, we have valid settings. 143 | logger.debug("Root dir: " + rootdir) 144 | logger.debug("Index file: " + indexfile) 145 | 146 | logger.debug("Reading index...") 147 | try: 148 | index = Zettelparser.read_index(indexfile) 149 | except FileNotFoundError: 150 | logger.error(sys.exc_info()[1]) 151 | logger.error("If you run Zettels with these settings for the " 152 | + "first time, please run it once without any arguments, " 153 | + "first. Or set the --update flag.") 154 | logger.error("Otherwise, please check your settings or run " 155 | + "Zettels with the --setup parameter to generate new settings.") 156 | logger.error("Exiting") 157 | exit() 158 | logger.debug("Done") 159 | 160 | if args.update: 161 | index = Zettelparser.update_index(rootdir, index, ignore_patterns=ignore_patterns) 162 | logger.debug("Writing index to file " + indexfile) 163 | Zettelparser.write_index(index, indexfile) 164 | logger.debug("Done") 165 | 166 | # Initialize a Zettelkasten 167 | zk = Zettelkasten(index, rootdir) 168 | # Now, let's do what we're told: 169 | 170 | if not args.Zettel: 171 | # When no Zettel argument is given, this implies the pretty flag, 172 | # but only of -o is not used. 173 | args.pretty = True 174 | else: 175 | # If no output flag is set, all them get set. This also implies 176 | # the pretty flag 177 | if not args.followups and not args.links and not args.incoming: 178 | # If no output flag is set, all them get set. The pretty flag 179 | # as well. 180 | args.followups = True 181 | args.links = True 182 | args.incoming = True 183 | args.pretty = True 184 | 185 | # Did the user set the output flag? 186 | if args.output: 187 | outputformat = args.output 188 | #Has the pretty flag been set (explicitly or implicitly)? 189 | elif args.pretty: 190 | outputformat = prettyformat 191 | 192 | if not args.Zettel: 193 | for entry in zk.get_list_of_zettels(as_output=True, 194 | outputformat=outputformat): 195 | print(entry) 196 | else: 197 | # In case our zettel arguments came from a pipe via stdin, 198 | # it's not a list, but a io.TextIOWrapper. We'll want to know 199 | # it's length before iterating through it, so convert it into 200 | # a list. 201 | args.Zettel = list(args.Zettel) 202 | for zettel_arg in args.Zettel: 203 | # In case our zettel arguments came from a pipe via stdin, 204 | # they each end with a line break. We have to strip those away. 205 | zettel_arg = zettel_arg.rstrip() 206 | # If we're dealing with more than one zettel argument, let's 207 | # structure output a bit: 208 | if len(args.Zettel) > 1: print("[", zettel_arg, "]") 209 | 210 | if args.followups: 211 | if args.pretty: print("[", "- Followups:" , "]") 212 | for entry in zk.get_followups_of(zettel_arg, 213 | as_output=True, 214 | outputformat=outputformat): 215 | print(entry) 216 | 217 | if args.links: 218 | if args.pretty: print("[", "- Link targets:" , "]") 219 | for entry in zk.get_targets_of(zettel_arg, 220 | as_output=True, 221 | outputformat=outputformat): 222 | print(entry) 223 | 224 | if args.incoming: 225 | if args.pretty: print("[", "- Incoming links:" , "]") 226 | for entry in zk.get_incoming_of(zettel_arg, 227 | as_output=True, 228 | outputformat=outputformat): 229 | print(entry) 230 | 231 | def _parse(args): 232 | logger.debug(args) 233 | 234 | # Read the settings file. _read_settings(settings) does the 235 | # error handling 236 | rootdir, indexfile, _, _, ignore_patterns = _read_settings(args.settings) 237 | # If we're still running, we have valid settings. 238 | logger.debug("Root dir: " + rootdir) 239 | logger.debug("Index file: " + indexfile) 240 | index = Zettelparser.read_index(indexfile) 241 | 242 | index = Zettelparser.update_index(rootdir, index, ignore_patterns=ignore_patterns) 243 | logger.debug("Writing index to file " + indexfile) 244 | Zettelparser.write_index(index, indexfile) 245 | logger.debug("Done") 246 | 247 | ################################# 248 | # Main function # 249 | ################################# 250 | 251 | def main(): 252 | """ 253 | Zettels is a little tool to index markdown files. It reads yaml-metadata 254 | blocks as defined by pandoc and parses the hyperlinks in each file. 255 | The resulting index contains the metadata and the targets of the 256 | hyperlinks. 257 | It's intended to be used for a "Zettelkasten" like Niklas Luhmann used it. 258 | """ 259 | ################################################# 260 | # Define command line arguments # 261 | ################################################# 262 | 263 | # Standard settings dir: 264 | settings_base_dir = xdg.BaseDirectory.save_config_path('Zettels') 265 | 266 | # Define the parser 267 | parser = argparse.ArgumentParser(description= 268 | "Zettels is an implementation of Niklas Luhmann's system of a \ 269 | Zettelkasten.") 270 | parser.set_defaults(func=_query) 271 | 272 | # top-level parameters 273 | parser.add_argument('--setup', help='interactively generate a new \ 274 | settings file. If this argument is given, all others are ignored.', 275 | action="store_true") 276 | parser.add_argument('-su', '--silentupdate', action="store_true", 277 | help='Silently build or update the index and exit.') 278 | 279 | group_query = parser.add_argument_group('Query options') 280 | # One (optional) postional argument, which is a Zettel 281 | 282 | if sys.stdin.isatty(): 283 | # Interactive, don't wait for the user if he or she hasn't 284 | # given any arguments 285 | zettel_arg_default = None 286 | else: 287 | # Piped, let's see what sys.stdin gives us. 288 | zettel_arg_default = sys.stdin 289 | 290 | group_query.add_argument('Zettel', 291 | metavar='ZETTEL', 292 | nargs='*', 293 | default=zettel_arg_default, 294 | help='Optional: specify one or several Zettel \ 295 | files. If no Zettel \ 296 | file is given, zettels will list the titles and \ 297 | paths of all the Zettels in the Zettelkasten \ 298 | (implying the --pretty flag).') 299 | group_query.add_argument('-u', '--update', action="store_true", 300 | help='Update the index before the query.') 301 | 302 | # Output arguments 303 | group_output = parser.add_argument_group('Query output options', 'Flags to \ 304 | determine the output. They only take effect if at least one \ 305 | ZETTEL argument is given. If none of these flags is set, the \ 306 | program outputs an overview over the specified Zettel(s), \ 307 | equivalent to setting all of these flags. Furthermore, this \ 308 | overview implicitly sets the --pretty flag for output format.') 309 | group_output.add_argument('-f', '--followups', action="store_true", 310 | help='Output followups of the specified Zettel(s).') 311 | group_output.add_argument('-l', '--links', action="store_true", 312 | help='Show the targets of hyperlinks in the specified Zettel(s).') 313 | group_output.add_argument('-i', '--incoming', action="store_true", 314 | help='Show all Zettels that link to the specified Zettel(s).') 315 | 316 | # Output format 317 | # It actually should be a mutually exclusive group, but that currently 318 | # supports neither title nor description... 319 | #group_format = q_parser.add_mutually_exclusive_group() 320 | group_format = parser.add_argument_group('Output format options', 'Tweak \ 321 | output format. Output is formatted as a Python Format String, (see \ 322 | https://docs.python.org/3/library/string.html#format-string-syntax \ 323 | for details). The output of the query command gives two fields that \ 324 | can be accessed in this manner: title as "{0[0]}" and path as "{0[1]}". \ 325 | In the settings file, two output formats are specified: \ 326 | a standard format and a "pretty" format.') 327 | group_format.add_argument('-p', '--pretty', action="store_true", 328 | help='Switch output to the pretty format as defined in settings \ 329 | (Default: "{0[0]:<40}| {0[1]}"). So with default settings, this is \ 330 | equivalent to -o "{0[0]:<40}| {0[1]}".') 331 | group_format.add_argument('-o', '--output', metavar='OUTPUTFORMAT', 332 | help='Override output format settings with OUTPUTFORMAT (a Python \ 333 | Format String). If this option is used, the --pretty flag is \ 334 | ignored.') 335 | 336 | # Developer options 337 | #_connect_dev_arguments(q_parser) 338 | _connect_dev_arguments(parser) 339 | 340 | ################################################# 341 | # Parse and process command line arguments # 342 | ################################################# 343 | 344 | args = parser.parse_args() 345 | 346 | # First check the --setup argument, because it overrides everything else 347 | if args.setup: 348 | setup.generate_settings() 349 | 350 | # Next, see if we're supposed to parse only or query, too. 351 | if args.silentupdate: 352 | args.func = _parse # default is _query, set in the argparser options. 353 | 354 | # Perpare the logger 355 | logger = _setup_logging(args.verbose) 356 | 357 | # Call the respective function for each subcommand 358 | # That is _parse(args) for the main command and _query(args) for the query 359 | # subcommand 360 | args.func(args) 361 | 362 | if __name__ == "__main__": 363 | main() -------------------------------------------------------------------------------- /zettels/zettelparser.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf8 -*- 2 | ## Copyright (c) 2017 Stefan Thesing 3 | ## 4 | ##This file is part of Zettels. 5 | ## 6 | ##Zettels is free software: you can redistribute it and/or modify 7 | ##it under the terms of the GNU General Public License as published by 8 | ##the Free Software Foundation, either version 3 of the License, or 9 | ##(at your option) any later version. 10 | ## 11 | ##Zettels is distributed in the hope that it will be useful, 12 | ##but WITHOUT ANY WARRANTY; without even the implied warranty of 13 | ##MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 | ##GNU General Public License for more details. 15 | ## 16 | ##You should have received a copy of the GNU General Public License 17 | ##along with Zettels. If not, see http://www.gnu.org/licenses/. 18 | 19 | import linecache 20 | import logging 21 | import os 22 | import pathspec 23 | import pkg_resources 24 | import shlex 25 | import subprocess 26 | import sys 27 | import time 28 | import yaml 29 | 30 | logger = logging.getLogger('Zettels.' + __name__) 31 | 32 | class Zettelparser: 33 | """ 34 | Zettelparser contains some methods necessary to build and update the index. 35 | 36 | It uses grep for parsing the Zettels. So if grep is not present 37 | on your OS, it won't work. 38 | 39 | The central method is probably Zettelparser.update_index(), it calls 40 | most of the other methods, which can be viewed as sub-methods. 41 | 42 | The only other independent functions are Zettelparser.read_index() 43 | and Zettelparser.write_index() 44 | 45 | See the class Zettelkasten for functionality of working with the index. 46 | """ 47 | 48 | @staticmethod 49 | def _ignorify(patterns=['*~']): 50 | """ 51 | pathspec implements gitignore style pattern matching. However, 52 | it doesn't ignore patterns, it *matches* patterns. 53 | So every pattern needs to be reversed by adding a '!' (or removing) 54 | it. 55 | """ 56 | patterns = list(patterns) 57 | # First, add everything 58 | reversed_patterns = ['*'] 59 | 60 | # Then reverse every single pattern 61 | for p in patterns: 62 | # If the pattern starts with '!', remove the '!' 63 | if p.startswith('!'): 64 | reversed_patterns.append(p.replace('!', '', 1)) 65 | else: 66 | reversed_patterns.append('!' + p) 67 | 68 | return reversed_patterns 69 | 70 | @staticmethod 71 | def _list_files(dirname, ignore_patterns=None): 72 | # Reverse pattern 73 | ignore_patterns = Zettelparser._ignorify(ignore_patterns) 74 | 75 | spec = pathspec.PathSpec.from_lines('gitwildmatch', ignore_patterns) 76 | matches = spec.match_tree(dirname) 77 | files = [] 78 | for match in matches: 79 | files.append(os.path.join(dirname, match)) 80 | 81 | return files 82 | 83 | @staticmethod 84 | def _get_updated_files(dirname, index=None, ignore_patterns=None): 85 | # Take care of optional parameters 86 | index = index or dict(files=dict()) 87 | 88 | ## Maybe our index has no timestamp, yet. 89 | try: 90 | timestamp = '@' + str(int(index['timestamp'])) 91 | except KeyError: 92 | timestamp = '@0' 93 | ignore_patterns = ignore_patterns or [] 94 | 95 | # Prepare ignore_patterns, i.e. reverse them 96 | ignore_patterns = Zettelparser._ignorify(ignore_patterns) 97 | spec = pathspec.PathSpec.from_lines('gitwildmatch', ignore_patterns) 98 | 99 | 100 | cmd = ['find', dirname, '-type', 'f', '-newerct', timestamp] 101 | # TODO (MEMO): should we need to get rid of the ./ at the beginning: 102 | # we can pipe it through sed 's/\.\///' 103 | 104 | output = [] 105 | for line in subprocess.check_output(cmd).splitlines(): 106 | line = line.decode() 107 | if spec.match_file(line): 108 | output.append(line) 109 | 110 | return output 111 | 112 | @staticmethod 113 | def _grep_files(dirname, index=None, ignore_patterns=None): 114 | # Calls grep to get the yaml-Blocks and markdown-Links as specified 115 | # in the file "zettels-grep-patterns" 116 | files = Zettelparser._get_updated_files(dirname, index, ignore_patterns) 117 | 118 | # Call grep only if there are any updated files 119 | grepoutput = None 120 | if files: 121 | # Path of the patterns file is 122 | # [installation directory]/resources/zettels-grep-patterns 123 | #patterns_file = os.path.join(sys.path[0], 124 | # "resources", 125 | # "zettels-grep-patterns ") 126 | 127 | patterns_file = pkg_resources.resource_filename('zettels', 'resources/zettels-grep-patterns') 128 | 129 | # pass it to grep 130 | grepcmd = ['grep', '-n', '-E', '-o', '-f', patterns_file] 131 | try: 132 | grepoutput = subprocess.check_output(grepcmd + files) 133 | except subprocess.CalledProcessError as e: 134 | # This may be caused by an empty file 135 | if e.returncode == 1 and e.output.decode() == "": 136 | logger.debug("grep returned an error, probably caused by" 137 | +"an empty file:", e) 138 | logger.debug("Carrying on ignoring the file.") 139 | else: 140 | raise 141 | 142 | grepoutput = grepoutput or "" 143 | 144 | return files, grepoutput 145 | 146 | @staticmethod 147 | def _parse_metadata(rootdir, for_yaml, index): 148 | origcwd = os.getcwd() 149 | os.chdir(rootdir) 150 | logger.debug("Parsing metadata:") 151 | for f in for_yaml: 152 | # Make the path to the file relative to the root directory 153 | #f = os.path.relpath(f, rootdir) 154 | 155 | logger.debug("Current file:") 156 | logger.debug(f) 157 | #only if there is more than the backbone. 158 | if for_yaml[f]['start'] != '': 159 | logger.debug("start: " + for_yaml[f]['start']) 160 | logger.debug("stop: " + for_yaml[f]['stop']) 161 | y = '' 162 | for i in range( 163 | int(for_yaml[f]['start']), 164 | int(for_yaml[f]['stop']) 165 | ): 166 | y = y + linecache.getline(f, i) 167 | 168 | logger.debug("y: " + str(y)) 169 | 170 | metadata = yaml.safe_load(y) 171 | #write the metadata to the index. 172 | for item in metadata: 173 | index['files'][f][item] = metadata[item] 174 | 175 | linecache.clearcache() 176 | os.chdir(origcwd) 177 | logger.debug("Parsing metadata: Done.") 178 | return index 179 | 180 | @staticmethod 181 | def _prune_index(rootdir, index): 182 | logger.debug("Pruning index...") 183 | to_prune = [] 184 | try: 185 | files = index['files'] 186 | # Make a list of all files in the root directory 187 | cmd = ['find', rootdir, '-type', 'f'] 188 | found_files = subprocess.check_output(cmd).splitlines() 189 | 190 | for entry in files: 191 | to_be_compared = os.path.join(rootdir, entry).encode(encoding='UTF-8') 192 | logger.debug("Current entry:") 193 | logger.debug(to_be_compared) 194 | if not to_be_compared in found_files: 195 | logger.error("Current entry is not in found_files. Well be pruned.") 196 | # The file listed in the index doesn't exist anymore. 197 | # Let's remove the entry 198 | to_prune.append(entry) 199 | except TypeError as e: 200 | logger.error("Failed pruning the index. No valid index.", e) 201 | except KeyError as e: 202 | logger.error("Failed pruning the index. It doesn't contain a " 203 | + "field 'files'", e) 204 | 205 | for entry in to_prune: 206 | del index['files'][entry] 207 | 208 | logger.debug("After pruning: index looks like this:") 209 | logger.debug(index) 210 | 211 | logger.debug("Pruning index: Done") 212 | 213 | return index 214 | 215 | @staticmethod 216 | def update_index(rootdir, index=None, ignore_patterns=None): 217 | """ 218 | Update/build an index for the specified directory. 219 | 220 | If an index is already available, only files with modification dates 221 | newer then the timestampt of the index are parsed. 222 | 223 | If no index is specified, a new index will be built. 224 | 225 | The function uses grep to parse the YAML-Metadata and the Markdown 226 | links in the Zettel files. It won't work on a system without grep. 227 | 228 | :param rootdir: the directory containing the Zettel files. 229 | :param index: An existing index, if available. 230 | :param ignore_patterns: a list of gitignore-style patterns to be ignored by grep 231 | :return: The index in dictionary format. 232 | """ 233 | logger.debug("Updating index:") 234 | 235 | # Generate a empty index, if necessary 236 | # It's necessary if 237 | # a) index is None 238 | # b) index is not a valid dictionary 239 | # c) if the list of files in index is empty 240 | 241 | built_index_from_scratch = False 242 | zfi = [] # zfi: Zettels from index 243 | try: 244 | zfi = index['files'] 245 | except (KeyError, TypeError): 246 | # index is None or not a dictionary with an entry called files 247 | logger.debug("index is none or invalid. Building from scratch.") 248 | built_index_from_scratch = True 249 | index = dict(files=dict()) 250 | 251 | n = 0 252 | try: 253 | n = len(zfi) 254 | except TypeError: 255 | # index['files'] contained something without a length => invalid 256 | logger.debug("index is invalid. Building from scratch.") 257 | built_index_from_scratch = True 258 | index = dict(files=dict()) 259 | 260 | if n == 0: 261 | logger.debug("index had an empty list of files. Building from scratch.") 262 | built_index_from_scratch = True 263 | index = dict(files=dict()) 264 | 265 | logger.debug("Before calling grep, the index looked like this:") 266 | if built_index_from_scratch: 267 | logger.debug("--Oh, by the way, we built it from scratch.") 268 | logger.debug(index) 269 | 270 | 271 | # get the list of updated files and the grep output 272 | files, grepoutput = Zettelparser._grep_files(rootdir, index, ignore_patterns) 273 | logger.debug("Here's what find and grep returned:") 274 | logger.debug("files:") 275 | logger.debug(files) 276 | logger.debug("grepoutput:") 277 | logger.debug(grepoutput) 278 | 279 | # generate an empty entry for each updated file, if necessary 280 | for f in files: 281 | # Make the path to the file relative to the root directory 282 | f = os.path.relpath(f, rootdir) 283 | if not f in index['files']: 284 | index['files'][f] = dict(title="untitled", 285 | targets=[], 286 | tags=[], 287 | followups=[]) 288 | 289 | if built_index_from_scratch: 290 | logger.debug("The empty index looks like this:") 291 | else: 292 | logger.debug("index should be untouched by grep") 293 | logger.debug(index) 294 | 295 | if grepoutput: 296 | #A temporary dict for in which information is 297 | #stored that are needed to parse the metadata 298 | for_yaml = dict() 299 | for line in grepoutput.splitlines(): 300 | #because grepoutput is in bytestring format, 301 | #decode it before taking it apart. 302 | line = bytes.decode(line) 303 | logger.debug("current line of grep output: " + line) 304 | 305 | #In the first partition, we get the filepath 306 | #of the occurrence file 307 | f, _, rest = line.partition(':') 308 | logger.debug("the rest looks like this: " + rest) 309 | 310 | # Make the path to the file relative to the root directory 311 | f = os.path.relpath(f, rootdir) 312 | 313 | logger.debug("Current file: " + f) 314 | #In the second partition, we get the line 315 | #number and the pattern that is responsible 316 | #for this line 317 | ln, _, pat = rest.partition(':') 318 | 319 | # First occurence for that file? Create an empty 320 | # entry 321 | if not f in for_yaml: 322 | for_yaml[f] = dict(start='', stop='') 323 | 324 | if pat == "---": 325 | # get the line number currently stored for the 326 | # pattern 327 | current_ln = for_yaml[f]['start'] 328 | # current_ln might be an empty string 329 | if current_ln: 330 | # we want to store the smallest linenumber 331 | # where this pattern occurs 332 | if int(current_ln) > int(ln): 333 | logger.debug("Storing start: " + ln) 334 | for_yaml[f]['start'] = ln 335 | else: 336 | # we might have a YAML block that ends with 337 | # '---' instead of '...' 338 | current_ln = for_yaml[f]['stop'] 339 | # same game 340 | if current_ln: 341 | if int(current_ln) > int(ln): 342 | logger.debug("Storing stop: " + ln) 343 | for_yaml[f]['stop'] = ln 344 | else: 345 | logger.debug("Storing stop: " + ln) 346 | for_yaml[f]['stop'] = ln 347 | else: 348 | # Yay, our value is new and shiny! Let's store it! 349 | logger.debug("Storing start: " + ln) 350 | for_yaml[f]['start'] = ln 351 | elif pat == "...": 352 | # get the line number currently stored for the 353 | # pattern 354 | current_ln = for_yaml[f]['stop'] 355 | # current_ln might be an empty string 356 | if current_ln: 357 | # we want to store the smallest linenumber 358 | # where this pattern occurs 359 | # or the second smallest where '---' occurs, which 360 | # is handled above 361 | if int(current_ln) > int(ln): 362 | logger.debug("Storing stop: " + ln) 363 | for_yaml[f]['stop'] = ln 364 | else: 365 | # Yay, our value is new and shiny! Let's store it! 366 | logger.debug("Storing stop: " + ln) 367 | for_yaml[f]['stop'] = ln 368 | #Other patterns are hyperlinks. Write the targets 369 | #of those to the index 370 | else: 371 | logger.debug("MD inline link found: " + pat) 372 | # We still have the complete inline link, e.g. 373 | # [Pipes](https://en.wikipedia.org/Pipelines_(Unix)) 374 | # We only want the URL-part. The target. 375 | #only the target in parentheses 376 | pat = pat.split("]")[1] 377 | #strip away the front parenthesis 378 | pat = pat.strip("(") 379 | #and the end parenthesis 380 | target = pat.rsplit(")", 1)[0] 381 | 382 | if not target in index['files'][f]['targets']: 383 | index['files'][f]['targets'].append(target) 384 | 385 | logger.debug("Before parsing, for_yaml looks like this:") 386 | logger.debug(for_yaml) 387 | 388 | logger.debug("Parsing metadata...") 389 | # Parse the metadata contained in for_yaml and write it to index 390 | index = Zettelparser._parse_metadata(rootdir, for_yaml, index) 391 | logger.debug("Parsing metadata...") 392 | 393 | if not built_index_from_scratch: 394 | # prune the index 395 | index = Zettelparser._prune_index(rootdir, index) 396 | 397 | # write the timestamp and return the completed index 398 | index['timestamp'] = time.time() 399 | 400 | logger.debug("Updating index: Done.") 401 | return index 402 | 403 | @staticmethod 404 | def read_index(filename="index.yaml"): 405 | """ 406 | Read index from file 407 | 408 | :param filename: path to the index file (YAML) 409 | :return: The index in dictionary format. 410 | """ 411 | f = open(filename, 'rt') 412 | index = yaml.safe_load(f.read()) 413 | f.close() 414 | return index 415 | 416 | @staticmethod 417 | def write_index(index, filename="index.yaml"): 418 | """ 419 | Write index to file 420 | 421 | :param index: dictionary containing the index 422 | :param filename: path to the index file (YAML) to be written 423 | """ 424 | f = open(filename, 'wt') 425 | yaml.dump(index, f) 426 | f.close() 427 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | {one line to give the program's name and a brief idea of what it does.} 635 | Copyright (C) {year} {name of author} 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | {project} Copyright (C) {year} {fullname} 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | --------------------------------------------------------------------------------