{
    "info": {
        "author": "Alberto Pianon",
        "author_email": "pianon@array.eu",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 2.7"
        ],
        "description": "# include-pandoc\n\nA wrapper for pandoc that processes include lines (like `!include path/to/included/file`) in markdown files before passing them to pandoc for further processing. \n\nIt allows to assemble complex/modular texts with link texts referring to headers or link definitions contained in different files. \n\nIt supports unlimited nested includes, and handles also relative include paths.\n\nInclude-pandoc should work on any Linux version and distribution. It should work also on Windows and OSX but it is untested on such platforms yet.\n\n## 1. Installation\n\n`sudo pip install include-pandoc && sudo include-pandoc --update`\n\nor (as user)\n\n`pip install --user include-pandoc && include-pandoc --update`\n\n## 2. Usage\n\n```bash\ninclude-pandoc [PANDOC_OPTIONS] [FILES] | [--update]\n```\n\nJust call `include-pandoc` instead of `pandoc`, with the same syntax you would use with `pandoc`. Without putting any files, standard input will be processed.\n\nIf you update Pandoc on your system, before using `include-pandoc` again, you have to run `include-pandoc --update` (otherwise you will get an error); this will update the wrapper with possible new Pandoc options implemented by the new installed version. If you installed `pandoc-update` as root, you have to call `include-pandoc --update` as root (f.e. with sudo).\n\n## 3. Include Syntax\n\nIncludes must be on **separate lines**, with the **include statement at the very beginning of the line**, with **no quotes** and **no escaped characters**. Some examples:\n\n`!include relative_path/to/included/file.md`\n\n`!include /absolute_path/to/included/file.md`\n\n`!include path with spaces/to/included file.md`\n\nIf relative paths are used in includes, they are regarded as relative to the path of the file that contains the include line; also in nested/recursive includes, relative paths are regarded as relative to the path of the nested file that contains the include line, not to the main/parent file path.\n\nSo if `main.md` includes `parts/part1.md` and the latter in turn includes `parts/subparts/subpart1.md`:\n\n- the include line in `main.md` will be `!include parts/part1.md`\n- the include line in `part1.md` will be `!include subparts/subpart1.md`.\n\n## 4. Rationale\n\n### 4.1 The Problem\n\nExisting solutions to implement includes in Pandoc are generally incomplete.\n\nThere are **filters that handle only code block includes**, like [pandoc-include-code](https://github.com/owickstrom/pandoc-include-code), that work well but **only for a specific purpose** (i.e. including code within a markdown guide).\n\nThere are **filters** like [pandoc-include](https://pypi.org/project/pandoc-include/) that allow to **include any kind of file** at any point of the markdown 'parent' file; however, they are all **limited by the architecture of Pandoc**.\nAs explained in [Pandoc's guide](https://pandoc.org/filters.html):\n\n>\u00abA \u201cfilter\u201d is a program that modifies the AST, between the reader and the writer:\n`INPUT --reader--> AST --filter--> AST --writer--> OUTPUT`.\nFilters are \u201cpipes\u201d that read from standard input and write to standard output. They consume and produce a JSON representation of the pandoc AST\u00bb.\n\nThe problem is that links and link definitions are processed by Pandoc's reader, and filters come only after it, and they can process Pandoc's AST and not the 'original' text.\n\nAs a consequence, when using Pandoc's include filters, if for instance a link text (`[Super Goof]`) contained in an included file (`part1.md`):\n\n- references a header (`# Super Goof`) contained in another included file (`part2.md`), \n\nor \n\n- is defined (`[Super Goof]: #super_goof_id`) in another included file (`definitions.md`), \n\nsuch link will remain 'unresolved' (i.e, it will be rendered as `[Super Goof]`, without being changed to a link), because Pandoc processes links before the include filter merges all included files.\n\n**This limitation prevents you to assemble working modular text documents through include filters in Pandoc**. \n\nAlternative workarounds seem not viable, too.\n\n- Some propose to [concatenate files when calling pandoc](https://stackoverflow.com/a/5529508) (`pandoc 01.md 02.md 03.md`), but it is a solution that may get very complicated to manage compared to an include based solution, especially when coming to complex modular texts:\n    - you would need to split the main document into small pieces, and further split -- or re-merge -- such pieces every time you want to move or change something, while it is much simpler to work on a main document that includes snippets from other files.   \n- Some propose to [use m4 as a pre-processor](https://stackoverflow.com/a/36104553), but this would lead to a lot of complications, too, because of the way m4 processes quotes and macros:\n    - for instance, if your text contains words corresponding to m4 macros like `changequote` or `define()` or others, m4 processes them as macros, even if they are in the middle of a line (and in some cases, even if no parentheses follow the reserved word!); so you should avoid to use any m4 reserved words in your text, but this is not an acceptable limitation; \n    - moreover, you cannot use in your text, for any reason, the character sequences you set as begin-quote and end-quote delimiters for m4 - otherwise you may get m4 errors like `dangling quote error-->m4:stdin:2: ERROR: end of file in string`; so you should choose very long and unlikely sequences of characters as begin-quote and end-quote delimiters, that in turn may lead to very awkward include lines.\n\n### 4.2 The solution\n\nI created a wrapper for Pandoc in order to process includes before passing the text(s) to Pandoc. It handles all the available options from the Pandoc version installed in your system and passes them transparently to Pandoc, but, before that, it processes the includes contained in the given file(s) (or in standard input if no filename is given). The chosen include syntax should not interfere with the remainder of the markdown text (like it happens instead with the m4 syntax).\nIn this way, you can create very complex modular texts with working links, no matter where the link is defined or where the referenced header is.\n\n\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/alpianon/include-pandoc",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "include-pandoc",
        "package_url": "https://pypi.org/project/include-pandoc/",
        "platform": "",
        "project_url": "https://pypi.org/project/include-pandoc/",
        "project_urls": {
            "Homepage": "https://github.com/alpianon/include-pandoc"
        },
        "release_url": "https://pypi.org/project/include-pandoc/0.11/",
        "requires_dist": [
            "argparse"
        ],
        "requires_python": "",
        "summary": "A wrapper for pandoc to pre-process includes (even nested ones)",
        "version": "0.11"
    },
    "last_serial": 5397528,
    "releases": {
        "0.10": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c3e16b2c4fc2d069ac9091e236f143fd",
                    "sha256": "75af901a43679dac4da7c4f41a613b2380b32d7a8507a313fad8cf344b5230fe"
                },
                "downloads": -1,
                "filename": "include_pandoc-0.10-py2-none-any.whl",
                "has_sig": false,
                "md5_digest": "c3e16b2c4fc2d069ac9091e236f143fd",
                "packagetype": "bdist_wheel",
                "python_version": "py2",
                "requires_python": null,
                "size": 23837,
                "upload_time": "2019-06-10T14:34:00",
                "url": "https://files.pythonhosted.org/packages/a2/56/4bc91ac9b24b0db487b00cfe91ca458bd0b8a885f22859b980cb689fd3eb/include_pandoc-0.10-py2-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "9d42e1167be0d92df10a09dd0f9563d6",
                    "sha256": "70c6423e7503cf8df092e07018ef8ab44788ed2ea709a37e2010acafa0b72f96"
                },
                "downloads": -1,
                "filename": "include-pandoc-0.10.tar.gz",
                "has_sig": false,
                "md5_digest": "9d42e1167be0d92df10a09dd0f9563d6",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9364,
                "upload_time": "2019-06-10T14:34:03",
                "url": "https://files.pythonhosted.org/packages/7a/b9/168df5eeae4e55f996bbed36825769961b5d090e7163fe6c849f9266ebf6/include-pandoc-0.10.tar.gz"
            }
        ],
        "0.11": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "19c686f676a2d9dd9cb1596edbb91d31",
                    "sha256": "ec0f241854ef487f73e4324aa943d257b99fd7312dbc889fb0c9997512e02892"
                },
                "downloads": -1,
                "filename": "include_pandoc-0.11-py2-none-any.whl",
                "has_sig": false,
                "md5_digest": "19c686f676a2d9dd9cb1596edbb91d31",
                "packagetype": "bdist_wheel",
                "python_version": "py2",
                "requires_python": null,
                "size": 23852,
                "upload_time": "2019-06-13T20:07:34",
                "url": "https://files.pythonhosted.org/packages/bb/f9/becf7bfb25b4203f6b44cad002cf852ab8bcc3c9edbdece832284ba0db07/include_pandoc-0.11-py2-none-any.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "19c686f676a2d9dd9cb1596edbb91d31",
                "sha256": "ec0f241854ef487f73e4324aa943d257b99fd7312dbc889fb0c9997512e02892"
            },
            "downloads": -1,
            "filename": "include_pandoc-0.11-py2-none-any.whl",
            "has_sig": false,
            "md5_digest": "19c686f676a2d9dd9cb1596edbb91d31",
            "packagetype": "bdist_wheel",
            "python_version": "py2",
            "requires_python": null,
            "size": 23852,
            "upload_time": "2019-06-13T20:07:34",
            "url": "https://files.pythonhosted.org/packages/bb/f9/becf7bfb25b4203f6b44cad002cf852ab8bcc3c9edbdece832284ba0db07/include_pandoc-0.11-py2-none-any.whl"
        }
    ]
}