jakobib / makespec

Makefile and templates to create specifications from Pandoc Markdown syntax

makespec simplifies creation and management of specifications and documentations. The program consists of a set of makefiles and templates to generate human-readable documents (HTML, PDF...) and formal schema files (OWL, Turtle, Relax-NG, BNF...) from a common source document written in Pandoc Markdown. Makespec also supports generating and updating GitHub pages to publish the specification at GitHub. Feel free to reuse, comment, fork, and modify makespec! The current version can be found at https://github.com/jakobib/makespec.

makespec's Issues

A link to an example result...

...would be nice in README.MD.

Hints on required packages

On a fresh Ubuntu, the following packages are required:

pandoc
texlive-xetex
texlive-fonts-recommended
texlive-fonts-extra (?)
latex-beamer (implies several other packages)
raptor-utils

Support RFC format

As used in https://github.com/gbv/beaconspec

Rewrite path-URIs at gh-pages

Specification of an ontology with path-URIs such as http://purl.org/ontology/foo/Bar for class "Bar" require a target URL http://your.github.org/foo/Bar. The makefile should therefore create small redirecting HTML pages, such as file Bar for each class and each property in an ontology.

Add KEYWORD variable

Comma separated list of keywords to be used as template variable and as document variable:

KEYWORD = foo, bar, doz

See issue #9 for similar variable ABSTRACT.

Automatically find templates files by name

makespec should first look in the templates directory before complaining.

How to add a custom css file

I tried the following Makefile

NAME = README
HTML_CSS = styles/doc.css

include makespec/Makefile

(The doc suggests HTML_TEMPLATE as variable name here, but I suppose that's a typo).

Anyway, I get invariably:

make: *** No rule to make target `styles/doc.css', needed by `README.html'.  Stop.

Workflow question

I'm on branch master and the file mwo.md was edited

git status

# On branch master
# Your branch is ahead of 'origin/master' by 10 commits.
#   (use "git push" to publish your local commits)
#
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   mwo.md

git add -u

# On branch master
# Your branch is ahead of 'origin/master' by 10 commits.
#   (use "git push" to publish your local commits)
#
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   mwo.md

git commit -m "testing makespec worflow"

[master 39655ec] testing makespec worflow
 1 file changed, 1 deletion(-)

git status

# On branch master
# Your branch is ahead of 'origin/master' by 11 commits.
#   (use "git push" to publish your local commits)
#
nothing to commit, working directory clean

make html

Creating movingwall.html...

git status

# On branch master
# Your branch is ahead of 'origin/master' by 11 commits.
#   (use "git push" to publish your local commits)
#
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   movingwall-tmp.md
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       movingwall.html

git add .
git status

# On branch master
# Your branch is ahead of 'origin/master' by 11 commits.
#   (use "git push" to publish your local commits)
#
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   movingwall-tmp.md
#       new file:   movingwall.html

git commit -m "testing makespec worflow"

[master d4c294a] testing makespec worflow
 2 files changed, 254 insertions(+), 2 deletions(-)
 create mode 100644 movingwall.html

git status

# On branch master
# Your branch is ahead of 'origin/master' by 12 commits.
#   (use "git push" to publish your local commits)
#
nothing to commit, working directory clean

make website

Creating movingwall.html...
rapper: Parsing URI file:///home/sbb-zdb/cklee/movingwall/movingwall-tmp.ttl with parser guess
rapper: Serializing with serializer turtle
rapper: Guessed parser name 'turtle'
rapper: Parsing returned 30 triples
rapper: Parsing URI file:///home/sbb-zdb/cklee/movingwall/movingwall-tmp.ttl with parser guess
rapper: Serializing with serializer rdfxml
rapper: Guessed parser name 'turtle'
rapper: Parsing returned 30 triples
new revision to be shown at https://github.com/cKlee/movingwall/
error: Your local changes to the following files would be overwritten by checkout:
        movingwall-tmp.ttl
Please, commit your changes or stash them before you can switch branches.
Aborting
fatal: A branch named 'gh-pages' already exists.
make: *** [website] Error 128

git status

# On branch master
# Your branch is ahead of 'origin/master' by 12 commits.
#   (use "git push" to publish your local commits)
#
# Changes not staged for commit:
#   (use "git add/rm <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       deleted:    movingwall-7d21d19.html
#       deleted:    movingwall-7d21d19.owl
#       deleted:    movingwall-7d21d19.ttl
#       modified:   movingwall-tmp.ttl
#       deleted:    movingwall.html
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       movingwall-39655ec.html
#       movingwall-39655ec.owl
#       movingwall-39655ec.ttl

git add -u
git status

# On branch master
# Your branch is ahead of 'origin/master' by 12 commits.
#   (use "git push" to publish your local commits)
#
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       deleted:    movingwall-7d21d19.html
#       deleted:    movingwall-7d21d19.owl
#       deleted:    movingwall-7d21d19.ttl
#       modified:   movingwall-tmp.ttl
#       deleted:    movingwall.html
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       movingwall-39655ec.html
#       movingwall-39655ec.owl
#       movingwall-39655ec.ttl

git commit -m "testing makespec worflow"

[master 11e6c7a] testing makespec worflow
 5 files changed, 649 deletions(-)
 delete mode 100644 movingwall-7d21d19.html
 delete mode 100644 movingwall-7d21d19.owl
 delete mode 100644 movingwall-7d21d19.ttl
 delete mode 100644 movingwall.html

make website

Creating movingwall.html...
rapper: Parsing URI file:///home/sbb-zdb/cklee/movingwall/movingwall-tmp.ttl with parser guess
rapper: Serializing with serializer turtle
rapper: Guessed parser name 'turtle'
rapper: Parsing returned 30 triples
rapper: Parsing URI file:///home/sbb-zdb/cklee/movingwall/movingwall-tmp.ttl with parser guess
rapper: Serializing with serializer rdfxml
rapper: Guessed parser name 'turtle'
rapper: Parsing returned 30 triples
new revision to be shown at https://github.com/cKlee/movingwall/
M       makespec
Switched to branch 'gh-pages'
[gh-pages 94e958d] revision 39655ec
 4 files changed, 286 insertions(+), 31 deletions(-)
 create mode 100644 movingwall-39655ec.html
Switched to branch 'master'
Your branch is ahead of 'origin/master' by 13 commits.
  (use "git push" to publish your local commits)

Now I can finally push. But this is obviously not the nicest workflow. What I'm doing wrong?

Add CSS variable

Seems there is a place in the default.html for a custom css file. But the variable CSS isn't used.

Additional output formats (epub, docbook, docx, pdf)

See https://github.com/OParl/specs/blob/master/scripts/create_documents.sh for an example script.

Include website theme as git submodule

One should be able to select a theme by justing pointing to a git repository, which should be included as git submodule instead of copying all files to the gh-pages branch.

Support multiple input files

e.g. chapter01.md, chapter02.md etc.

prettify HTML

Add auto-detected syntax highlighting etc.

This version, latest version

How to make links to 'this version' and 'latest version'?

Automatic init-gh-pages

make init-gh-pages should create and fill the gh-pages branch fully automatically.

Variable to toggle on/off toc

Add ABSTRACT and KEYWORD variables

An optional abstract and an optional list of keywords are needed for scientific papers (makedoc) but they could also be useful for some specifications. One could support the following configuration variables with ABSTRACT_FROM set to abstract.md by default:

KEYWORDS = foo, bar, doz
ABSTRACT = bla blub
ABSTRACT_FROM = filename

Should their plain text value be passed to the templates and/or should they be injected in the Markdown document? Which template variable names? For instance MAKEDOC_KEYWORDS or DOCUMENT_KEYWORDS, DOCUMENT_ABSTRACT, or MAKEDOC_ABSTRACT?

Fix extraction of RDF/Turtle

Right now any line with four spaces (outside of code sections) is interpreted as raw Turtle syntax. Makespec should better use pandoc export format to extract code snippets. One should also configure the formats and allow for multiple formats (e.g. RelaxNG, RDF/Turtle etc.) in one specification.

Support Content-Negotiation for serving ontologies

Github pages does not support content negotiation, so one should put a proxy between purl.org and github.io that delegates to turtle or owl files.

Set --toc-depth=2 in HTML

This requires Pandoc >= 1.10 (2013-01-19), which is not given as Ubuntu package by now.

don't switch to gh-pages branch if index is not clean

Allow more flexible configuration and usage of file variables

It would be nice to have the possibility defining custom file variables. E.g. for file inclusion like:
{FILE_1}
{FILE_2}
{FILE_X}

So that it is clear, that variables starting with "FILE_" always pointing to files, that should be included.

Adding a tag after make website will break

Maybe force existence of a tag?