Skip to content

Commit

Permalink
Update documentation #201 #429
Browse files Browse the repository at this point in the history
  • Loading branch information
luigi-asprino committed Nov 29, 2023
1 parent 462d8c8 commit acf9b03
Show file tree
Hide file tree
Showing 2 changed files with 334 additions and 8 deletions.
25 changes: 17 additions & 8 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Main features:
- Query files in plain SPARQL 1.1, via the `SERVICE <x-sparql-anything:>` (see [configuration](#Configuration)) and
build knowledge graphs with `CONSTRUCT` queries
- [Supported formats](#supported-formats): XML, JSON, CSV, HTML, Excel, Text, Binary, EXIF, File System, Zip/Tar,
Markdown, YAML, Bibtex, DOCx (see [pages dedicated to single formats](#supported-formats))
Markdown, YAML, Bibtex, DOCx, PPTX (see [pages dedicated to single formats](#supported-formats))
- Transforms [files, inline content, or the output of an external command](#general-purpose-options)
- Generates RDF, RDF-Star, and tabular data (thanks to SPARQL)
- Full-fledged [HTTP client](Configuration.md#http-options) to query Web APIs (headers, authentication, all methods
Expand Down Expand Up @@ -197,6 +197,7 @@ A detailed description of the interpretation can be found in the following pages
- [EXIF Metadata](formats/Metadata.md)
- [Bibtex](formats/Bibtex.md)
- [YAML](formats/YAML.md)
- [Slides](formats/Slides.md)

... and, of course, the triples generated from the these formats can be integrated with the content of
any [RDF Static file](formats/RDF_Files.md)
Expand Down Expand Up @@ -400,13 +401,13 @@ the [Apache Jena documentation](https://jena.apache.org/documentation/query/libr
| [fx:entity(?a ... ?n)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxentity) | Function | Any sequence of node | URI node | The function `fx:entity (?a ... ?n)` accepts a list of arguments and performs concatenation and automatic casting to string. Container membership properties (`rdf:_1`,`rdf:_2`,...) are cast to numbers and then to strings (`"1","2"`). |
| [fx:literal(?a, ?b)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxliteral) | Function | String, (URI or language code) | Literal node | The function `fx:literal( ?a , ?b )` builds a literal from the string representation of `?a`, using `?b` either as a typed literal (if a IRI is given) or a lang code (if a string of length of two is given). |
| [fx:bnode(?a)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxbnode) | Function | Any node | Blank node | The function `fx:bnode( ?a) ` builds a blank node enforcing the node value as local identifier. This is useful when multiple construct templates are populated with bnode generated on different query solutions but we want them to be joined in the output RDF graph. Apparently, the standard function `BNODE` does generate a new node for each query solution (see issue [#273](https://github.com/SPARQL-Anything/sparql.anything/issues/273) for an explanatory case). |
| [fx:LevenshteinDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxlevenshteindistance) | Function | String, String | Integer | The function `fx:LevenshteinDistance(?n1, ?n2) ` computes the Levenshtein Distance between ?n1 and ?n2 (see #182). |
| [fx:CosineDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxcosinedistance) | Function | String, String | Double | The function `fx:CosineDistance(?n1, ?n2) ` computes the Cosine Distance between ?n1 and ?n2 (see #182). |
| [fx:JaccardDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxjaccarddistance) | Function | String, String | Double | The function `fx:JaccardDistance(?n1, ?n2) ` computes the Jaccard Distance between ?n1 and ?n2 (see #182). |
| [fx:JaroWinklerDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxjarowinklerdistance) | Function | String, String | Double | The function `fx:JaroWinklerDistance(?n1, ?n2) ` computes the Jaro-Winkler Distance between ?n1 and ?n2 (see #182). |
| [fx:LevenshteinDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxlevenshteindistance) | Function | String, String | Integer | The function `fx:LevenshteinDistance(?n1, ?n2) ` computes the Levenshtein Distance between ?n1 and ?n2 (see #182). |
| [fx:CosineDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxcosinedistance) | Function | String, String | Double | The function `fx:CosineDistance(?n1, ?n2) ` computes the Cosine Distance between ?n1 and ?n2 (see #182). |
| [fx:JaccardDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxjaccarddistance) | Function | String, String | Double | The function `fx:JaccardDistance(?n1, ?n2) ` computes the Jaccard Distance between ?n1 and ?n2 (see #182). |
| [fx:JaroWinklerDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxjarowinklerdistance) | Function | String, String | Double | The function `fx:JaroWinklerDistance(?n1, ?n2) ` computes the Jaro-Winkler Distance between ?n1 and ?n2 (see #182). |
| [fx:LongestCommonSubsequenceDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxlongestcommonsubsequencedistance) | Function | Any pair of IRIs or Literals | Integer | The function `fx:LongestCommonSubsequenceDistance(?n1, ?n2) ` computes the Longest Common Subsequence Distance between ?n1 and ?n2 (see #182). |
| [fx:HammingDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxhammingdistance) | Function | String, String | Integer | The function `fx:HammingDistance(?n1, ?n2) ` computes the Hamming Distance between ?n1 and ?n2 (see #182). |
| [fx:QGramDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxqgramdistance) | Function | String, String | Double | The function `fx:QGramDistance(?n1, ?n2) ` computes the QGram Distance between ?n1 and ?n2 (see #394). |
| [fx:HammingDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxhammingdistance) | Function | String, String | Integer | The function `fx:HammingDistance(?n1, ?n2) ` computes the Hamming Distance between ?n1 and ?n2 (see #182). |
| [fx:QGramDistance(?n1, ?n2)](FUNCTIONS_AND_MAGIC_PROPERTIES.md#fxqgramdistance) | Function | String, String | Double | The function `fx:QGramDistance(?n1, ?n2) ` computes the QGram Distance between ?n1 and ?n2 (see #394). |


## Usage
Expand Down Expand Up @@ -496,12 +497,20 @@ usage: java -jar sparql.anything-null -q query [-f <output format>] [-v
in the input result set.
```

Logging can be configured adding the following option (SLF4J):
Logging can be configured adding the following option (SLF4J).

To enable the default logger for SPARQL anything and its dependencies:
```
-Dorg.slf4j.simpleLogger.defaultLogLevel=trace
```

To enable the default logger for SPARQL anything only:

```
-Dorg.slf4j.simpleLogger.log.io.github.sparqlanything=trace
```


### Fuseki

An executable JAR of a SPARQL-Anything-powered Fuseki endpoint can be obtained from
Expand Down
317 changes: 317 additions & 0 deletions docs/formats/Slides.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,317 @@
# Slides

A slide is a single page of a presentation. Collectively, a group of slides may be known as a slide deck.
We can interpret a slide deck as a sequence of slides where each slide is a sequence of blocks (e.g. title, text boxes etc.).
A slide deck can be represented as a list of typed containers (of type `Slide`).
Each slide contains other *typed blocks*, where the type denotes the kind of block (e.g. title, subtitle etc.).

## Extensions

SPARQL Anything selects this transformer for the following file extensions:

- pptx

## Media types

SPARQL Anything selects this transformer for the following media types:

- application/vnd.openxmlformats-officedocument.presentationml.presentation

## Default implementation

- [io.github.sparqlanything.slides.PptxTriplifier](../sparql-anything-slides/src/main/java/com/github/sparqlanything/slides/PptxTriplifier.java)

## Default Transformation


### Data

Located at https://sparql-anything.cc/examples/Presentation1.pptx

### Query

```
CONSTRUCT
{
?s ?p ?o .
}
WHERE
{ SERVICE <x-sparql-anything:location=https://sparql-anything.cc/examples/Presentation1.pptx>
{ GRAPH ?g
{ ?s ?p ?o }
}
}
```

### Facade-X RDF

```turtle
@prefix fx: <http://sparql.xyz/facade-x/ns/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix xyz: <http://sparql.xyz/facade-x/data/> .
[ rdf:type fx:root , xyz:Presentation ;
rdf:_1 [ rdf:type xyz:Slide ;
rdf:_1 [ rdf:type xyz:CENTERED_TITLE ;
rdf:_1 "This is a test presentation"
] ;
rdf:_2 [ rdf:type xyz:SUBTITLE ;
rdf:_1 "This is the subtitle"
]
] ;
rdf:_2 [ rdf:type xyz:Slide ;
rdf:_1 [ rdf:type xyz:TITLE ;
rdf:_1 "First slide"
] ;
rdf:_2 [ rdf:type xyz:CONTENT ;
rdf:_1 "Bullet 1\nBullet 2"
]
] ;
rdf:_3 [ rdf:type xyz:Slide ;
rdf:_1 [ rdf:type xyz:TITLE ;
rdf:_1 "Second slide"
] ;
rdf:_2 [ rdf:type xyz:CONTENT ;
rdf:_1 "Bullet 1\nBullet 2"
]
]
] .
```

<!--
## Options
### Summary
|Option name|Description|Valid Values| Default Value |
|-----------|-----------|------------|----------------|
|docs.table-headers|It tells the document triplifier to use the headers of the tables within the document file for minting the properties of the generated triples.|true/false| false |
|docs.merge-paragraphs|It tells the document triplifier to merge all the paragraphs of the document into a single slot (new line characters are preserved)|true/false| false |
### `docs.table-headers`
#### Description
It tells the document triplifier to use the headers of the tables within the document file for minting the properties of the generated triples.
#### Valid Values
true/false
#### Default Value
false
#### Examples
##### Input
### Data
Located at https://sparql-anything.cc/examples/Doc1.docx
##### Use Case 1: Construct the dataset by using the headers of the columns of the tables to mint the property URIs.
###### Query
```
CONSTRUCT
{
?s ?p ?o .
}
WHERE
{ SERVICE <x-sparql-anything:location=https://sparql-anything.cc/examples/Doc1.docx,docs.table-headers=true>
{ ?s ?p ?o }
}
```
###### Result
```turtle
@prefix fx: <http://sparql.xyz/facade-x/ns/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix xyz: <http://sparql.xyz/facade-x/data/> .
[ rdf:type xyz:Document , fx:root ;
rdf:_1 [ rdf:type xyz:Heading1 ;
rdf:_1 "Title 1"
] ;
rdf:_2 [ rdf:type xyz:Paragraph ;
rdf:_1 "Paragraph1"
] ;
rdf:_3 [ rdf:type xyz:Paragraph ;
rdf:_1 "Paragraph2"
] ;
rdf:_4 [ rdf:type xyz:Heading2 ;
rdf:_1 "Title 2"
] ;
rdf:_5 [ rdf:type xyz:Paragraph ;
rdf:_1 "Paragraph3"
] ;
rdf:_6 [ rdf:type xyz:Paragraph ;
rdf:_1 ""
] ;
rdf:_7 [ rdf:_1 [ xyz:A "A1" ;
xyz:B "B1" ;
xyz:C "C1"
] ;
rdf:_2 [ xyz:A "A2" ;
xyz:B "B2" ;
xyz:C "C2"
]
]
] .
```
### `docs.merge-paragraphs`
#### Description
It tells the document triplifier to merge all the paragraphs of the document into a single slot (new line characters are preserved)
#### Valid Values
true/false
#### Default Value
false
#### Examples
##### Input
### Data
Located at https://sparql-anything.cc/examples/Doc1.docx
##### Use Case 1: Use Case 1: Construct the graph by merging multiple consecutive paragraphs into single a single slot.
###### Query
```
CONSTRUCT
{
?s ?p ?o .
}
WHERE
{ SERVICE <x-sparql-anything:location=https://sparql-anything.cc/examples/Doc1.docx,docs.merge-paragraphs=true>
{ ?s ?p ?o }
}
```
###### Result
```turtle
@prefix fx: <http://sparql.xyz/facade-x/ns/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix xyz: <http://sparql.xyz/facade-x/data/> .
[ rdf:type xyz:Document , fx:root ;
rdf:_1 "Title 1\nParagraph1\nParagraph2\nTitle 2\nParagraph3\n\n" ;
rdf:_2 [ rdf:_1 [ rdf:_1 "A" ;
rdf:_2 "B" ;
rdf:_3 "C"
] ;
rdf:_2 [ rdf:_1 "A1" ;
rdf:_2 "B1" ;
rdf:_3 "C1"
] ;
rdf:_3 [ rdf:_1 "A2" ;
rdf:_2 "B2" ;
rdf:_3 "C2"
]
]
] .
```
-->

<!--
#
## Extensions
SPARQL Anything selects this transformer for the following file extensions:
-
## Media types
SPARQL Anything selects this transformer for the following media types:
-
## Default Transformation
### Data
```
```
Located at https://sparql-anything.cc/examples/example.tar
### Query
```
```
### Facade-X RDF
```turtle
```
## Options
### Summary
### ``
#### Description
#### Valid Values
#### Default Value
#### Examples
##### Input
### Data
```
```
Located at https://sparql-anything.cc/examples/example.tar
##### Use Case 1:
###### Query
```
```
###### Result
```turtle
```
-->

0 comments on commit acf9b03

Please sign in to comment.