Update documentation.

[lkitching]

Issues #62, #83, 84 - Update the table2qb documentation to describe the structure of generated URIs as well as the relationship between the pipelines.

Move the usage documentation into its own page and update the employment example to follow a similar structure.

[Robsteranium]

This is excellent @lkitching. Explaining each pipeline in turn with examples and specifics on how the URIs are derived makes it much clearer.

I've taken the liberty of making some small tweaks - the patch should be self-explanatory.

I think there are some other avenues for extension:

• In terms of the big picture, I prepared a colour-coded spreadsheet for the regional-trade example which seems to have helped some people to get their heads around this. Perhaps we should include a visual diagram showing a few tables?
• The docs now explain referential integrity, which is great, but I wonder if we should provide a summary or checklist for ensuring URIs all match-up. Indeed it might make more sense to have executable validations in rdf-validator. Nevertheless it would be good to figure out some way to link any violations back to the cells that caused the problem (which could be in column-csv which we're not loading at data yet).
• We've started using a pattern of name-spacing codes which I think is proving quite effective (i.e. the column is configured with a value template like domain.com/def/concept/age/{notation} while the notations look like nisra/4 or nrs/3-or-4 allowing namespacing within a single codelist without needing multiple column definitions etc). Perhaps we should document that approach in an example? I'm not sure how best to present patterns (I find a lot of tutorials are named by the topic not the relevant features!).

Reading this I'm also beginning to wonder about making some changes to the code:

• Maybe we should rename input-csv to be more descriptive? Perhaps it should instead be components-csv and observations-csv (or cube-csv).
• Component range - this is a half-completed feature (see the sns-graft pipeline for a more complete version which assigns ranges to the components and classes to the codes). My original intention was to use these as a means of validation between components and values, i.e. testing the statement that dim:age [a class:Age]. I've since learned that the rdfs:range property works in reverse and instead serves to imply this statement. At this point I'm inclined to remove the rdfs:range and classize elements from table2qb and validate this elsewhere.
• We should validate that measure components have no qb:codeList properties
• We should validate that the name field in columns-csv contains no hyphens (if we don't already) or is otherwise suitable for inclusion in URI templates)
• "the compact form of qb:measureType is not accepted." IIRC there might be a way to do this (perhaps with {+varname})

[lkitching]

@Robsteranium - We already valdiate the name field doesn't contain hyphens. Ideally we could use the validation in csv2rdf to check it's a valid variable name within a URI template. I'm wondering if having our own URI template library might be useful. I've created an issue for validating generated cubes. Agree re re-naming input-csv, I've started referring to it as observations-csv in parts of the code but renaming the pipeline parameter also makes sense.

[Robsteranium]

The outstanding points have gone into #97, #98, #99 and #100.