Metadata-Version: 2.1
Name: Feedmark
Version: 0.14
Summary: Feedmark: a curation-oriented subset of Markdown, and tools for processing it
Author-email: Chris Pressey <packages@catseye.tc>
License: Copyright (c)2019-2022 Chris Pressey, Cat's Eye Technologies
        
        Permission is hereby granted, free of charge, to any person obtaining a
        copy of this software and associated documentation files (the "Software"),
        to deal in the Software without restriction, including without limitation
        the rights to use, copy, modify, merge, publish, distribute, sublicense,
        and/or sell copies of the Software, and to permit persons to whom the
        Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
Project-URL: website, https://catseye.tc/node/Feedmark
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Requires-Python: >=2.7,>=3.5
Description-Content-Type: text/markdown
License-File: LICENSE

Feedmark
========

*Version 0.14.  Subject to change in backwards-incompatible ways without notice.*

**Feedmark** is a format for embedding structured data in Markdown files
in a way which is both human-readable and machine-extractable.
The structured data is intended to be "curational" in nature.
Articles in [Chrysoberyl][], [Some Games of Note][], and other collections
of Cat's Eye Technologies' are written in Feedmark.

Informally, the format says that every `h3`-level heading in the
Markdown file gives the title of an entity, and may be followed
immediately by the entity's "plaque", which is a bullet list
where every item is in the form "field-name: field-value".

Why Feedmark?
-------------

In the same way that a Markdown file is still a readable text file,
which is nice, a Feedmark file is still a readable Markdown file,
which is still a readable text file, which is nice.

While some structured data formats like YAML are fairly easy to
read, many web-based files viewers (such as GitHub's) will
automatically format Markdown as HTML, making it that much nicer.

Example Feedmark documents can be found in the `eg/` directory,
and in the projects mentioned above.

Implementation
--------------

This repository contains a Python program, `feedmark`, which is a
reference implementation of a processor for the Feedmark format.

To use it, you can clone this repository and run it as `bin/feedmark`
from the directory of your clone, or you can put the `bin` directory
on your executable search path, and run it as `feedmark` anywhere.

Or you can install it using `pip`:

    pip install Feedmark==0.14

(Depending on your needs, you may wish to establish a virtual environment
first.  How to do this is outside the scope of this document.)

`feedmark` is currently able to do the following things:

### Parse and check Feedmark documents

Loading documents will always check that they are minimally well-formed.

    feedmark eg/*.md

You can also check documents against a Feedmark schema, which is
simply another Feedmark document, one in which each entry describes
a property that entries should have.

    feedmark eg/*Sightings*.md --check-against=eg/schema/Llama\ sighting.md

### Convert Feedmark documents to various formats

The original use case of this tool was to generate an Atom (née RSS)
feed of entries in a document:

    feedmark "eg/Recent Llama Sightings.md" --output-atom=feed.xml
    python3 -m http.server 7000 &
    python3 -m webbrowser http://localhost:7000/feed.xml

It can now also output entries as JSON, indexed by entry, or by
property, or by publication date:

    feedmark --output-json eg/*.md
    feedmark --by-property eg/*.md
    feedmark --by-publication-date eg/*.md

Output entries as Markdown, or HTML (using the `toc` extension,
which generates link anchors on headings compatible with the ones
generated by GitHub).

    feedmark --output-markdown eg/*.md
    feedmark --output-html eg/*.md

### Rewrite documents in-place

They will be parsed as Feedmark, and then output as Markdown, to the
same files that were read in as input.  (Note!  This is destructive;
it is recommended that the original files be under version control such
as `git`, which will easily allow the changes to be reverted if necessary.)

    feedmark --rewrite-markdown eg/*.md

### Interlink documents

Markdown supports "reference-style" links, which are not inline
with the text.

`feedmark` can rewrite reference-style links that match the name of
an entry in a previously-created "refdex", so that they
can be kept current and point to the canonical document in which the
entry exists, since it may exist in multiple, or be moved over time.

    feedmark eg/*.md --output-refdex >refdex.json
    feedmark --input-refdex=refdex.json --rewrite-markdown eg/*.md

See also
--------

Feedmark is a subset of Markdown, which is something it has in common
with [Falderal][], however it has decidedly different goals.

See [TODO.md](TODO.md) for planned features and [HISTORY.md](HISTORY.md)
for a record of features added in past versions.

[Falderal]: https://catseye.tc/node/Falderal
[Chrysoberyl]: https://git.catseye.tc/Chrysoberyl/
[Some Games of Note]: https://github.com/cpressey/Some-Games-of-Note#readme
