Getting started

To use Scriba, a user has to:

  1. compile scriba or download the binaries
  2. edit the content descriptor XML file: "Scriba Contents File" (SCF)
  3. extend Scriba with a custom Plugin
  4. run Scriba

In the following sections, the four steps are explained.

Compile Scriba or download the binaries

To compile the project you can choose between two different versions:

  • light version: contains the source code of SCRIBA but no external libraries;
  • full version: light version plus all the libraries;

Import the project into your favorite RAD or compile it using the ANT file named 'build.xml' located in the project tree. If you want to use Scriba without compiling it, you can download the binary version.

Top

Edit the content descriptor XML file: "Scriba Contents File" (SCF)

Scriba assumes the existance of a "contents descriptor XML file" (named "Scriba Contents File", SCF), where every content is pointed by an URL. Let's see how the XML descriptor file is structured.

The file is made up of three sections (XML Schema is available here):

  • header
  • metadata
  • contents

Header

This is the header of the file. A simple XML declaration with the version of the Scriba descriptor file.


  <?xml version="1.0" encoding="UTF-8" ?>
  <book version="1.0">

			

Metadata

A 'metadata' section where you have to specify all the ebook metadata. Every 'metadataitem' identifies a single metadata. Every 'metadataitem' has two attributes which are the 'eletype' and 'elename'. The former is needed by the engine to distinguish the type of element, whereas the latter is used to set the name of the XML element.


    <metadata>
      <metaitem eletype="dc" elename="title">Form del %pretty_date%</metaitem>
      <metaitem eletype="dc" elename="creator" role="aut" >Ufficio Stampa e Internet - Servizio dell'Informatica</metaitem>
      <metaitem eletype="dc" elename="creator" role="edt" >Senato della Repubblica</metaitem>
      <metaitem eletype="dc" elename="language">it</metaitem>
      <metaitem eletype="dc" elename="identifier" id="senabookid">aula_commissioni_book1</metaitem>
      <metaitem eletype="dc" elename="subject">Documenti Aula e Commissioni</metaitem>
      <metaitem eletype="dc" elename="date">%date%</metaitem>
      <metaitem eletype="meta" elename="meta" name="copyright" content="Senato della Repubblica italiana" destination="opf"/>
      <metaitem eletype="meta" elename="meta" name="dtb:uid" content="aula_commissioni_book1" destination="ncx"/>
      <metaitem eletype="meta" elename="meta" name="dtb:depth" content="1" destination="ncx"/>
      <metaitem eletype="meta" elename="meta" name="dtb:totalPageCount" content="0" destination="ncx"/>
      <metaitem eletype="meta" elename="meta" name="dtb:maxPageNumber" content="0" destination="ncx"/>
    </metadata>
			

Contents

Following the metadata section, there is the 'contents' section where you have to specify the actual contents of your ebook. You define the container of the contents and identify which the TOC Id is.


    <contents tocId="toc">
 			

Now you can add the contents you want. It is very important to specify the 'packageId', 'packagePath' (it is the path in the TOC) and the 'packageFile' (it is the filename that will be stored in the ebook). The following content represents the toc file.


	<content packageId="toc" packagePath="/" packageFile="toc.ncx" contentMediaType="application/x-dtbncx+xml" />
 			

The most important attribute is surely the 'contentUrl' where you have to pin the content through a URL.


        <content packageId="copertina" packagePath="/" packageFile="copertina.html"
            contentUrl="file:///C:/Lavoro/...copertina.html"
            contentMediaType="application/xhtml+xml" cover="true" isInSpine="true" tocName="Copertina"
            plugin="it.senato.areatesti.ebook.ebookmaker.plugin.defaultplugin.CoverPlugin" />
        <content packageId="logo_senato_png" packagePath="/IMG"
            contentUrl="file:///C:/Lavoro/...logo_senato.png"
            packageFile="logo_senato.png" contentMediaType="image/png" />
        <content packageId="style" packagePath="/" packageFile="stile.css"
            contentUrl="file:///C:/Lavoro/...stile.css"
            contentMediaType="text/css" />
        <content packageId="reso_aula" packagePath="Aula/Ultimo Stenografico"
            packageFile="Resoconto stenografico della seduta.xhtml"
            contentUrl="http://www.senato.it/..."
            contentMediaType="application/xhtml+xml" isInSpine="true" tocName="Ultimo stenografico"
            plugin="it.senato.areatesti.ebook.ebookmaker.plugin.ResoStenoPlugin"/>
        <content packageId="scheda_ddl_S2537" packagePath="Ddl/Scheda" packageFile="Scheda del DDL n S2537.xhtml"
            contentUrl="http://www.senato.it/.../content.htm"
            contentMediaType="application/xhtml+xml" isInSpine="true" tocName="Scheda DDL S2537"
            plugin="it.senato.areatesti.ebook.ebookmaker.plugin.SchedaDdlPlugin"/>
        <content packageId="testo_ddl_S_2537" packagePath="Ddl/Testo" packageFile="Testo del DDL n S2537.xhtml"
            contentUrl="http://www.senato.it/..."
            contentMediaType="application/xhtml+xml" isInSpine="true" tocName="Testo DDL S2537"
            plugin="it.senato.areatesti.ebook.ebookmaker.plugin.TestoDdlPlugin"/>
        <content packageId="schedasenatore_321" packagePath="Senatori/Schede attivit‡"
            packageFile="schedasenatore_321.xhtml"
            contentUrl="http://www.senato.it/.../00321.htm"
            contentMediaType="application/xhtml+xml" isInSpine="true" tocName="Scheda Senatore 321"
            plugin="it.senato.areatesti.ebook.ebookmaker.plugin.SchedaSenPlugin" />
        <content packagePath="/Atti del Giorno"
            packageId="atti"
            contentUrl="http://www.senato.intranet/../content.html"
            plugin="it.senato.areatesti.ebook.ebookmaker.plugin.UltimiAttiStampatiPlugin" pdfToHtml="true" isNeededTidy="true"
            isNeededXsl="false"/>
    </contents>
			

You may or may not specify a 'plugin' attribute for the content.

Top

Extend Scriba with a custom Plugin

Scriba sources contain some sample plugins. One of that is to complete the ebooks Cover (example). You can call this plugin with the syntax previously seen:


    <content packageId="copertina" packagePath="/" packageFile="copertina.html"
        contentUrl="file:///C:/Lavoro/...copertina.html"
        contentMediaType="application/xhtml+xml" cover="true" isInSpine="true" tocName="Copertina"
        plugin="it.senato.areatesti.ebook.ebookmaker.plugin.defaultplugin.CoverPlugin" />
		

In the new version (0.52) other two plugins have just been added: PDFtoHtml (it converts a single PDF file in HTML) and Boilerpipe experimental plugin (it instructs Scriba to include a web site main contents).

Top

Run Scriba

This is a command line example:

java -jar ScribaEBookMaker -c "scf.xml" -t EPUB_STANDARD -o "this-is-your-ebook-output-file" -cr rgb

This line instructs Scriba to:

  • (-c) use the 'scf.xml' file where it can find the contents to retrieve
  • (-t) produce an output in ePub format
  • (-o) name of the output file
  • (-cr) use coloured (rgb) or grayed (gray) PDF converted images

For the help:

java -jar ScribaEBookMaker -h

 

You can download the new version (1.5) bin package. It is ready to run with an example of SCF file and a run.bat (for Windows platform).

See the video at the demo page!

(page content was updated on 08/07/2014)