clarin-eric / fcs-misc

Specification documents, examples and schema files

FCS Miscellaneous Resources

This repo contains AsciiDoc sources, images, examples and schema files for the CLARIN Federated Content Search (FCS) specification documents found at clarin.eu. Prior versions of the specification documents with examples and schema files are also backed up in the historical/ folder. Current builds of the AsciiDoc sources are available on this page.

Jump to: [Specification Documents] | [Tutorial Documents] | [Historical Resources] | [Webpage with Builds]

Specification Documents

• CLARIN Federated Content Search - FCS Core 2.0: fcs-core-2.0/index.adoc
• CLARIN Federated Content Search - FCS Core 1.0: fcs-core-1.0/index.adoc
• CLARIN Federated Content Search - FCS Data Views 1.0: fcs-dataviews-1.0/index.adoc
• WIP CLARIN Federated Content Search - FCS AAI 1.0: fcs-aai/index.adoc
• WIP Text+ LexFCS 1.0: lexfcs/index.adoc (Mirror of Text+ Gitlab Repo)

Folder Structure

All the specification documents are structured as follows in their sub folders:

• index.adoc -- AsciiDoc entrypoint document that bundles and includes single chapters into one
• attachments/ -- (optional) with schema files or similar
• examples/ -- (optional) examples (or fragments) that are included in the specification document
• images/ -- (optional) for images that will be in the specification
• themes/ -- links to the global themes/ folder with the clarin theme

AsciiDoc

• global themes/ folder for CLARIN

How to build

Please take a look at the Github Actions workflow definitions in .github/workflows. All the specification documents will be built automatically when their source files change. (NOTE: changes to theme files may require manually triggering the build.)

You can build the specifications documents yourself with:

# Set spec you want to build
# Based on folder names, choose one of: fcs-core-1.0, fcs-core-2.0, fcs-aai, fcs-dataviews-1.0
NAME=fcs-core-2.0

# Output will be placed in `docs/`

# Build HTML
asciidoctor -v -D docs -a data-uri --backend=html5 -o ${NAME}.html ${NAME}/index.adoc

# Build PDF
asciidoctor-pdf -v -D docs -o ${NAME}.pdf ${NAME}/index.adoc

# (optional) Copy attachments
cp -R ${NAME}/attachments docs/

# (optional) Copy examples (are already included into the documents)
cp -R ${NAME}/examples docs/

You can use the asciidoctor/docker-asciidoctor docker image for building the specifications if you don't want to install various dependencies. Note that the build artifacts belong to the root user.

docker run --rm -it -v $(pwd):/documents asciidoctor/docker-asciidoctor
# then run your build commands

Tutorial Documents

• CLARIN Federated Content Search - FCS Endpoint Developer's Tutorial: fcs-endpoint-dev-tutorial/index.adoc

  For build instructions, see section Specification Documents "How to build".

• CLARIN Federated Content Search - FCS Endpoint Development Slides: fcs-endpoint-dev-slides

  This is a RevealJS slide deck based on AsciiDoc and needs slightly different build steps. Those are currently only listed in the GitHub Actions Workflow. The following are a copy:

  # Output will be placed in `slides/`
  
  # Setup "dependencies"
  git clone -b 4.1.2 --depth 1 https://github.com/hakimel/reveal.js.git
  mkdir -p slides/reveal.js
  mv reveal.js/dist slides/reveal.js/
  mv reveal.js/plugin slides/reveal.js/
  rm -rf reveal.js/
  
  git clone -b 10.7.3 --depth 1 https://github.com/highlightjs/highlight.js.git
  mv highlight.js/src/styles/github.css slides/reveal.js/plugin/highlight/
  mv highlight.js/src/styles/idea.css slides/reveal.js/plugin/highlight/
  mv highlight.js/src/styles/magula.css slides/reveal.js/plugin/highlight/
  rm -rf highlight.js/
  
  # Build Slides
  asciidoctor-revealjs -v -D slides fcs-endpoint-dev-slides/index.adoc
  
  # Copy images/styles/...
  cp -R -v fcs-endpoint-dev-slides/images slides/
  cp -R -v fcs-endpoint-dev-slides/css slides/
  cp -R -v fcs-endpoint-dev-slides/js slides/
  
  # Display slides, visit "localhost:8000"
  cd slides/
  python3 -m http.server 8000
  # or simply open the "index.html"

Historical Resources

To be found under historical/:

• documents/ -- specification documents
• examples/ -- examples from specification
• schema/ -- xsd schema files
• software/
  • mpi-endpoint/ -- CQL Search servlet

Webpage with Builds

A static overview webpage with latest document builds is available at https://clarin-eric.github.io/fcs-misc/.

To update this page (only manually), go to Actions: publish to <gh-pages> and trigger a rebuild with the Run workflow button on the main branch.

fcs-misc's Issues

[AsciiDoc] [Spec] Make URLs to attachments absolute for PDF output

Links to attachments should be absolute (maybe even versioned, using git tags) so that different output formats contain valid links! If the URLs remain relative, examples and attachments referred to in the specification documents may not be available depending on where the document is being hosted.
E.g. https://office.clarin.eu/v/CE-2017-1046-FCS-Specification-v20230426.pdf ("DataView-Hits.xsd" in §2.2.3.2. Data View)