Introduction to Proskomma

[mvahowe]

Running Proskomma

One easy way to explore Proskomma is using the new sandbox: https://github.com/Proskomma/diegesis-apollo-sandbox . The French translation in that sandbox is the one for which we've been generating test HTML (for PHP).

Or, if you'd rather write code, another option is the Hello Proskomma tutorial: https://doc.proskomma.bible/en/latest/getting_started/tutorials/hello.html

Terminology

• a document is something like the USFM for one book of the Bible
• a docSet is a collection of documents, so something like a translation (eg ULT)
• a sequence is one or more paragraphs of content of the same type, within a document
• a block is something like a paragraph within a sequence

I've written something like a lot because the definitions are less clear when working with syntax trees. But, when working with Scripture text, you can ignore the something likes.

Some queries

However you are running Proskomma, here are some relevant queries to try...

{ docSets( ids:"xyz-fra_lsg" ) { id document( bookCode: "PHP" ) { id sequences { id type } } } }

will give you basic information about every sequence in the document behind the test HTML. If you skim the sequences section you should be able to see that the types correpond to the different blocks of content rendered in the editor.

{ docSets(ids:"xyz-fra_lsg") { id document(bookCode: "PHP") { id sequences(types:"main") { blocksText } } } }

will give you the text for each block in the main sequence, as one string per block. In most use cases you want more detailed information, for example

{ docSets(ids:"xyz-fra_lsg") { id document(bookCode: "PHP") { id sequences(types:"main") { blocks(positions:0) { items { type subType payload } } } } } }

This gives you each Proskomma item for the first block. (I limited the request to one block because the output is quite long.) You can probably see from this why we're not using GraphQL JSON directly - it's not that convenient to work with! Items are either

• tokens (printable text)
• scopes (something that wraps around content)
• grafts (information about another sequence that could be inserted, such as a footnote or cross-reference)

If you scroll through the results for the last 2 queries, you may notice that there are headings etc. That's because they are grafted onto the block that follows them, which you can see using

{ docSets(ids:"xyz-fra_lsg") { id document(bookCode: "PHP") { id sequences(types:"main") { blocks(positions:0) { bg { type subType payload } } } } } }

(bg is short for 'block graft'.) According to the second graft, the id of the introduction sequence, in the sandbox, is ODE0YjE5MjEt. (The UIDs are created when a document is loaded from USFM or USX, and will be different every time. The sandbox uses 'frozen' content so, unusually, the UIDs don't change, but production code should never rely on this.) Once you have that sequence Id, you can get the content for that sequence, which has the same format as the main sequence and every other sequence:

{ docSets(ids:"xyz-fra_lsg") { id document(bookCode: "PHP") { id sequences(ids:"ODE0YjE5MjEt") { blocksText } } } }

If you query the block grafts of that sequence (bg as above) you'll see that there's a title sequence grafted to the first introduction sequence. (A title in Proskomma is something like 'the title page' and may have multiple paragraphs, although in many places it's used as another sort of heading.) Finally, the headers are provided, once per document, as key-value tuples:

{ docSets(ids:"xyz-fra_lsg") { id document(bookCode:"PHP") { headers {key value } } } }

Some notes on GraphQL syntax

• GraphQL looks a bit like JSON, but isn't JSON. It's more like import {x, y, z} from 'foo' in Javascript. One difference is that spaces, not commas, separate tokens.
• In the queries above I've added arguments to make the output relatively short. Those arguments go between parenthesis , ie (). If you remove the parentheses after docSet and replace document() with documents (no parentheses) you'll get a lot more data.
• Many Proskomma arguments expect a list of values but, if they are given one value, they silently turn that into a list. That's why ids and types are plural above. (Try putting types=["main" "introduction"] into one of the queries above.)
• The form of the JSON result follows the form of the query. This is a feature, and is part of what makes GraphQL so flexible. But it's also what makes the JSON a bit painful to work with. For example, for headers, it would be nice to have a simple object with the header name as the key and the header content as the value, but there's no way to ask for that in GraphQL, because every key must be specified in the GraphQL schema).

To do

• Try the queries above and check that the results make sense to you
• Try changing the queries, for example to see more or less data, or different docSets, documents or sequences
• Ask questions or make comments on this issue