<?teipublisher odd="docbook.odd" template="documentation.html" fill="1" depth="2"?><?xml-model href="https://cdn.docbook.org/schema/5.0/xsd/docbook.xsd" type="application/xml" schematypens="http://www.w3.org/2001/XMLSchema"?><article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" label="b">
    <info>
        <title>Gentle Introduction to TEI Publisher</title>
        <author>
            <orgname>TEI Publisher Community</orgname>
        </author>
        <keywordset role="genre">
            <keyword>Documentation</keyword>
        </keywordset>
        <abstract>
            <para>Start here. Introduces key concepts and provides a tutorial to help you getting started.</para>
        </abstract>
    </info>
    <section xml:id="introduction">
        <title>Introduction</title>

        <para>TEI Publisher provides a flexible and sustainable <emphasis>toolbox</emphasis>
            which enables scholars with limited technical skills to publish their material
            without forcing it into a one-size-fits-all framework. Our mantra is to stop
            reinventing the wheel with every new digital project and reuse what others have
            already built instead. And, most importantly, help to improve the shared base by
            adding what's missing into the communal pool.</para>
        <para>TEI Publisher provides a smooth and fast entry path for editors with little
            technical experience while remaining endlessly flexible and extensible for advanced
            users. </para>
        <para>Numerous projects realized with <link xlink:href="https://www.e-editiones.org/map/" xlink:show="new">TEI Publisher worldwide</link> prove that it is:</para>
        <orderedlist>
            <listitem>
                <para>a truly universal tool for any kind of digital publication, from scholarly
                    editions to journals, monographs, lexicons, and much more</para>
            </listitem>
            <listitem>
                <para>suitable even for very complex and multi-faceted material</para>
            </listitem>
            <listitem>
                <para>sustainable and future-proof</para>
            </listitem>
            <listitem>
                <para>capable of generating high quality, camera ready material for print
                    publishing</para>
            </listitem>
            <listitem>
                <para>suitable for any XML, not only TEI (this documentation is written in
                    DocBook!)</para>
            </listitem>
        </orderedlist>

            <section xml:id="intro-jinks">
                <title>Overview</title>
                <para> Starting with the version 10, based on Jinks application manager, the core
                    TEI Publisher idea of assembling an edition from the modular
                        <emphasis>"lego"</emphasis> blocks is taken to the next level. Despite the
                    changes to the interface and internal reorganization, advanced users will
                    nevertheless find most underlying concepts and components slightly changed but
                    still recognizable. </para>
                <para>Version 10 substantially extends the <emphasis>toolbox</emphasis> idea of
                    simple, recombinable blocks: the core of TEI Publisher itself is now decomposed
                    into a set of small, modular profiles, which can be combined and configured to
                    assemble concrete applications. Each profile provides end-to-end implementation
                    for a particular aspect of a digital edition, e.g. support for a certain input
                    format, integration of facsimile images, timelines or map display.</para>
            </section>
            <section>
                <title>Assembling an application</title>
                <para>An actual application is created by selecting desired features and customizing
                    their configuration. This is achieved through a central configuration file,
                    which can be easily edited through the user interface. Human-readable structure
                    of the configuration file coupled with syntax suggestions in this step greatly
                    simplify the development process.</para>
                <para>Profiles may cover individual functional <emphasis>features</emphasis>, like
                    the aforementioned timeline but others take care of the
                        <emphasis>presentational</emphasis> aspects, like typesetting and styling.
                    Such profiles are called <emphasis>themes</emphasis>.</para>
                <para>Profiles may also aggregate and customize each other, so a profile may depend
                    on one or more other profiles. At the top of such a hierarchy sits what we call
                    a <emphasis>blueprint</emphasis>, which is essentially a ready-made
                    configuration for a complete application. Usually it will be targeting a
                    specific use case, e.g. a correspondence edition or a dictionary. In the
                    simplest case, a blueprint may be just a configuration file, which tailors the
                    configuration of profiles it uses for the specific purpose of this particular
                    blueprint.</para>
            </section>

            <section>
                <title>Continuous development</title>
                <para>TEI Publisher comes with a central application manager, Jinks, which manages
                    all profiles and the applications generated from it.</para>
                <para>Creation of an application is no longer a one-time generative step, but it can
                    be approached iteratively: new features may be added or removed, configuration
                    for the existing ones modified. The same user interface which allowed us to
                    select, pre-configure and generate our application, can be used to reconfigure
                    and regenerate it at any later point. </para>

                <para>As new profiles are added to the public library - or new versions are released
                    for the existing ones - this application manager can take care of updating
                    profiles and their dependencies used in custom applications under its control.
                    Updates can largely be carried out automatically with the number of necessary
                    manual interventions reduced to a minimum and most updates applied with a single
                    click. Gone are the days when users had to read through update instructions to
                    manually migrate to a new version of TEI Publisher. </para>
            </section>

            <section>
                <title>Basic vocabulary</title>
                <para>To clarify how various parts fit together, let us summarize some key concepts,
                    which will be used in the rest of this documentation:</para>
                <variablelist>
                    <varlistentry>
                        <term>TEI Publisher</term>
                        <listitem>
                            <para>denotes the software framework as a whole, i.e. the entire
                                toolbox, comprising all profiles and libraries</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>Jinks</term>
                        <listitem>
                            <para>the central application manager, which generates applications and
                                manages updates</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>TEI Publisher Documentation and Demo</term>
                        <listitem>
                            <para>refers to the application containing this documentation and a
                                selection of demos. It mimics the old monolithic TEI Publisher
                                application, but is now generated from a blueprint.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>Profile</term>
                        <listitem>
                            <para>a modular building block for a TEI Publisher application. Profiles
                                can extend other profiles and may be combined to create
                                applications. We distinguish several kinds of profiles:</para>
                            <variablelist>
                                <varlistentry>
                                    <term>Base</term>
                                    <listitem>
                                        <para>a special profile, used by all TEI Publisher
                                            applications, providing the core server-side API and
                                            basic page layout without styling</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry>
                                    <term>Feature</term>
                                    <listitem>
                                        <para>a functional profile to be combined with base and
                                            potentially other profiles. It provides all necessary
                                            resources to fully implement a specific functional
                                            scope, e.g. docker configuration, register sidebar, or a
                                            timeline.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry>
                                    <term>Theme</term>
                                    <listitem>
                                        <para>provides a particular look and feel. It supplies all
                                            necessary CSS styles, fonts and graphic assets to
                                            achieve that.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry>
                                    <term>Blueprint</term>
                                    <listitem>
                                        <para>a complete template for an application targeted at a
                                            specific use case, e.g. a monograph, correspondence
                                            edition, dictionary etc.</para>
                                    </listitem>
                                </varlistentry>
                            </variablelist>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>TEI Processing Model</term>
                        <listitem>
                            <para>the very core of TEI Publisher. Part of the TEI Guidelines and the
                                TEI ODD specification format, it defines how documents are
                                transformed from the source XML into output formats (e.g. HTML,
                                ePub, print).</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>Webcomponents</term>
                        <listitem>
                            <para>library of interactive custom HTML elements. These main user
                                interface building blocks of TEI Publisher can be freely combined to
                                create robust HTML pages with TEI Publisher. Part of the HTML5
                                standard and natively supported by browsers.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>Jinks Templates</term>
                        <listitem>
                            <para>a templating language used by Jinks during application generation
                                as well as within profiles to fill placeholders with content.</para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </section>
        <section xml:id="e-editiones">
            <title>e-editiones.org</title>
            <para> Since its first incarnation in 2015, TEI Publisher has gained substantial
                following with numerous academic and commercial projects around the globe, which are
                relying on it for their editorial and publishing needs. Grass-roots user initiative
                led in 2020 to the foundation of an international non-profit association <link xlink:show="new" xlink:href="https://e-editiones.org">e-editiones.org</link>
                with the focus on further joint development of TEI Publisher, open standards and
                best practices for digital editions. </para>

            <para>TEI Publisher development is only possible thanks to generous contributions of
                developers, users and institutions willing to employ Open Source approaches so that
                the whole community can reuse and benefit from their work.</para>

            <para> A growing number of projects from small to large that have decided to publish
                their materials with TEI Publisher gives us all not only the opportunity but also
                the responsibility to make the project thrive for years to come and to make it truly
                sustainable option for XML publishing! Consider joining <link xlink:show="new" xlink:href="https://e-editiones.org">e-editiones.org</link> through your
                affiliated institution or individually to support our efforts. </para>

            <para>We invite the community to contribute to the project – by means of code, ideas,
                documentation, tutorials and funding. </para>
            <para> You don't have to be a developer to contribute, you can do so in a number of
                ways! </para>

            <orderedlist>
                <listitem>
                    <para>Check out the source code, modify it, document it, enhance it.</para>
                </listitem>
                <listitem>
                    <para>Create new or enhance existing example documents and ODDs so we present
                        showcases for various TEI applications.</para>
                </listitem>
                <listitem>
                    <para> Report your issues, feature requests or ideas for discussion via <link xlink:show="new" xlink:href="https://github.com/eeditiones/tei-publisher-app/issues">GitHub issue tracker</link>. </para>
                </listitem>
                <listitem>
                    <para> Discuss with us on <link xlink:show="new" xlink:href="https://join.slack.com/t/e-editiones/shared_invite/zt-e19jc03q-OFaVni~_lh6emSHen6pswg">e-editiones slack chat</link> or through the <link xlink:show="new" xlink:href="https://admin.hostpoint.ch/mailman/listinfo/community_e-editiones.org">mailing list</link> and <link xlink:show="new" xlink:href="https://twitter.com/EEditiones">@EEditiones twitter</link>.
                    </para>
                </listitem>
                <listitem>
                    <para> Contribute to translations via <link xlink:show="new" xlink:href="https://crwd.in/tei-publisher">Crowdin</link>. Please
                        contact us if your target language is not listed and you'd like to work on
                        it. </para>
                </listitem>
                <listitem>
                    <para> Port back your customizations (e.g. profiles or themes) to the TEI
                        Publisher code base so that others can use it too (or ask us to do it for
                        you)! </para>
                </listitem>
                <listitem>
                    <para> Help and mentor others – publish teaching materials, answer questions on
                        our Slack channel, mailing list and other forums. </para>
                </listitem>
                <listitem>
                    <para> Sponsor a concrete feature or fund a development grant. </para>
                </listitem>
            </orderedlist>
        </section>
    </section>
    <section xml:id="tp">
        <title>Guided Tour</title>
        <para>If you are browsing this documentation through the official website or you have
            installed TEI Publisher via the docker image, you will find four applications on the start
            page:</para>
        <note>
            <para>If you installed TEI Publisher without docker, you will only see two applications
                here. You can <link linkend="using-jinks">generate the others yourself</link>
                though.</para>
        </note>
        <figure>
            <title>Start page showing four installed applications</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="home-explore.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <variablelist>
            <varlistentry>
                <term>Documentation and Demo</term>
                <listitem>
                    <para>Provides the documentation you are reading and a few selected
                        examples</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><link xlink:href="/exist/apps/tp-serafin" xlink:show="new">Correspondence Edition</link></term>
                <listitem>
                    <para>A more complex example, showcasing a parallel view with transcription and
                        translation, entity register of people and places, correspondence navigation
                        and a timeline.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><link xlink:href="/exist/apps/tp-workbench" xlink:show="new">Workbench</link></term>
                <listitem>
                    <para>Tools to help with the edition workflow: a web-based annotation editor and
                        an online editor for working directly on a TEI text.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><link xlink:href="/exist/apps/jinks" xlink:show="new">Jinks</link></term>
                <listitem>
                    <para>TEI Publisher's application manager: all other apps were generated by
                        this.</para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>For a first overview we recommend to start with the <productname>TEI Publisher
                Documentation and Demo</productname> application. This includes the documentation,
            provides a few selected demos, and also allows you to upload your own documents to the
                <filename>demo</filename> collection as well as to play around with different ODDs
            or create your own.</para>
        
        <note>
            <para>The first three apps
                correspond to one of the pre-configured blueprints available in Jinks. See <link linkend="using-jinks">below</link> for more information
            on profiles and blueprints.</para>
        </note>
        <section xml:id="browsing">
            <title>Browsing Documents</title>
                <para>The start page of <productname>TEI Publisher Documentation and
                        Demo</productname> serves as an entry point to explore and
                    experiment.</para>
                <para>The left side panel presents search and filtering options. The central panel
                    lists the available collections or – if you browse into a collection – the
                    documents within. Another panel to the right shows the list of ODD files
                    provided by the app.</para>

                <figure>
                    <title>First options in the start page collection listing</title>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="start-page-collections.png" width="512px"/>
                        </imageobject>
                    </mediaobject>
                </figure>
                <para>The usual starting point is the <emphasis role="bold">Demo
                        Collection</emphasis> with which users can explore a range of <link linkend="selected-use-cases">selected use cases</link>, demonstrating
                    various genres, encoding styles and presentation layouts. Various customization
                    aspects are handled using different ODDs and view templates. We suggest to have
                    a look at each of them to see what TEI Publisher can achieve out of the
                    box.</para>
            <para>Every example – including the documentation – can also be downloaded in different
                media formats. Not all formats will be available for every sample. TEI Publisher
                supports ePub, Markdown and PDF. For the PDF there are three options: using Print
                CSS, FO or LaTeX as intermediate format. FO and LaTeX are disabled by default. For
                further information refer to the <link xlink:href="documentation.xml?id=output-media">reference guide</link>.</para>
            <figure>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="download-menu.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
        </section>
        <section xml:id="document-view">
            <title>The Document View</title>
            <para>The document view can vary, sometimes substantially, depending on the sample
                document you are looking at. This is a natural consequence of TEI's versatility and
                broad scope of its application. However, key elements of the user interface
                intentionally remain the same across examples and applications. This starts with the
                central toolbar, showing a series of buttons by default:</para>
            <figure>
                <title>Central toolbar in demo collection</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="content-toolbar.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <variablelist>
                <varlistentry>
                    <term>Select ODD</term>
                    <listitem>
                        <para>The <guilabel>Select ODD</guilabel> dropdown allows you to change the currently
                            used ODD. Note that most texts require a particular ODD. However, if you develop
                            your own ODD, this dropdown allows you to quickly switch e.g. between different
                            versions.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Page navigation</term>
                    <listitem>
                        <para>Those two buttons allow you to navigate to the next/previous page in a
                            longer text</para>
                        <note>
                            <para>Alternatively, you can use the left/right keys on your
                                keyboard!</para>
                        </note>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Content zoom</term>
                    <listitem>
                        <para>Controls the font size for the content of the document to improve
                            readability</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Recompile ODD</term>
                    <listitem>
                        <para>Only available when logged in; this button triggers regenerating the ODD used to display the current document and reloads the page</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>Some examples may contribute additional buttons (e.g. the Cortés letter).</para>
            <para>Depending on the text you may also see one or two sidebars to the left and right
                of the content area. These can be resized or minimized.</para>
            <para>TEI Publisher 10 tries to provide a consistent layout across all applications. See
                the section on <link xlink:href="documentation.xml?id=themes-and-styling">Layout, Themes and Styling</link> in the reference guide.</para>
        </section>
        <section xml:id="selected-use-cases">
            <title>Selected Use Cases</title>
            <para>Sample documents which are included in TEI Publisher's installation package do not
                represent the full scope of its applications. Selection is based on community-provided use cases:</para>
            <figure>
                <title>Browsing Demo collection</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="demo-collection-overview.png" width="512px"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Critik der reinen Vernunft</emphasis> from the <emphasis>Deutsches
                            Textarchiv</emphasis> corpus presents a philosophical tractate,
                        originally published in print, thus following 'traditional' book structure
                        with front pages, foreword and chapters. </para>
                </listitem>
                <listitem>
                    <para> Shakespeare's <emphasis>Romeo and Juliet</emphasis>, from
                            <emphasis>Bodleian First Folio</emphasis> project uses dedicated TEI
                        elements to encode structure of the play but it also showcases the parallel
                        transcription and facsimile alignment for its presentation which is
                        obviously of general application and could be used for any genre, not
                        limited to dramatic texts. </para>
                </listitem>
                <listitem>
                    <para>Correspondence corpora are common, yet very interesting, subjects for
                        digital editions. Despite basic similarities in structure, depending on the
                        period, scope and particular research perspective, intended presentation may
                        vary enormously. We are presenting samples of:</para>
                    <itemizedlist>
                        <listitem>
                            <para> A 16th century manuscript letter of <emphasis role="bold">Hernán
                                    Cortés</emphasis> showcasing parallel transcription/translation
                                and facsimile view and transcription enhanced with commentaries and
                                explicitly encoded transcriptional features.</para>
                        </listitem>
                        <listitem>
                            <para> A letter from <emphasis role="bold">Van Gogh</emphasis> to Paul
                                Gauguin written in 1888. This intentionally reproduces the flexible
                                column layout pioneered by the <link xlink:show="new" xlink:href="http://vangoghletters.org">Vincent Van Gogh
                                    Letters</link> online edition, which is a model example for
                                correspondence.</para>
                        </listitem>
                    </itemizedlist>
                </listitem>
                <listitem>
                    <para>For a taste of completely different encoding style we present several 19th
                        century lexicons and dictionaries:</para>
                    <itemizedlist>
                        <listitem>
                            <para> A manuscript collocative dictionary of Polish <emphasis role="bold">Bogactwa mowy polskiej</emphasis> featuring
                                interactive highlights for regions of interest of the facsimile when
                                hovering over dictionary headwords. Internal composition is based on
                                the <code>entryFree</code> element with a rich
                                microstructure.</para>
                        </listitem>
                        <listitem>
                            <para> An encyclopedia of philosophic terms by Friedrich Kirchner and
                                Carl Michaëlis, published in 1907: <emphasis>Wörterbuch der
                                    Philosophischen Grundbegriffe</emphasis>. This is based on the
                                Lex-0 customization of TEI and provides a sidebar to browse the
                                available lemmata.</para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </itemizedlist>

            <note>
                <title>Note</title>
                <para>You may notice that the list of included samples is more limited than in
                    version 9. Some examples have been moved into separate profiles (see the
                        <emphasis>Serafin</emphasis> blueprint for a correspondence edition), the
                    rest has been condensed and streamlined. The base ODD now covers many more TEI
                    features out of the box, so fewer samples are necessary.</para>
                <para>We'd like to stress that preparing showcases above has been only possible
                    thanks to numerous projects releasing their sources openly, in particular the
                        <link xlink:show="new" xlink:href="http://firstfolio.bodleian.ox.ac.uk">Bodleian First Folio</link>, <link xlink:show="new" xlink:href="http://www.deutschestextarchiv.de">Deutsches Textarchiv</link>,
                        <link xlink:show="new" xlink:href="http://vangoghletters.org">Vincent Van
                        Gogh Museum</link> and <link xlink:show="new" xlink:href="https://www.textcreationpartnership.org/tcp-eebo">
                        EEBO-TCP</link>. We'd also like to thank William Graves and Anna Skolimowska
                    for sharing their correspondence material. </para>
            </note>

            <para>All TEI Publisher's sample documents are XML files which are transformed into a
                HTML webpage for display in the browser. We have already mentioned in the very first section that the TEI Processing Model
                lies at the heart of the Publisher – the ODD file associated with a document defines
                the rules of transformation of the XML source file into HTML. An introduction to ODD
                and the processing model <link linkend="pm-tutorial">will be given below</link> in the corresponding chapter.
                
                A detailed discussion of
                the Processing Model can be found in the <link xlink:href="documentation.xml?id=pm-syntax">reference manual</link>.</para> 
            <para>For now it
                is sufficient to say this is where decisions if a TEI element should be rendered
                inline, with a tooltip, or as a marginal note, are made. Simplifying things a bit,
                the <emphasis>text</emphasis> of the document that you see rendered in your browser
                is an effect of applying the rules from ODD file to the source document. When
                opening a document of the Demo collection, it is possible to see in the URL the
                    <parameter>odd</parameter> parameter indicating which ODD file is being used to
                process the document, e.g. <link xlink:href="../demo/F-rom.xml?odd=shakespeare">demo/F-rom.xml?odd=shakespeare</link>.</para>
            <para>Most demos come with their own ODD. However, all of them – at least if they deal
                with TEI – extend the base ODD, <filename>teipublisher.odd</filename>.</para>
        </section>
        <section xml:id="upload">
            <title>Uploading documents</title>
            <para>You may already have some documents you might want
                published, whether they are in TEI, DocBook, JATS, MS Word DOCX or other XML format.
                The <productname>Documentation and Demo</productname> application allows you to
                upload documents into the <guilabel>Demo Collection</guilabel>. The first step is to
                upload them into the database, for which you need to be <emphasis role="bold">logged
                    in</emphasis>. The user and password are displayed in the information block on
                top of the right sidebar.</para>
            <note>
                <title>Important</title>
                <para>If you are reading this on the official TEI Publisher <link xlink:href="https://tei-publisher.org">website</link>, you won't
                    be able to log in or upload. Please <link xlink:href="installation.xml">install</link> your own instance
                    of TEI Publisher to experiment with it. The remaining sections of this quickstart guide assume you
                have TEI Publisher installed yourself.</para>
            </note>
            <figure>
                <title>The Upload Panel</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="upload.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>Upon successful login, uploading is just a question of dragging your documents
                onto the <guibutton>Upload</guibutton> area. They will become available in the
                document list immediately after upload is successfully completed. The upload panel
                will also display the upload results. In case of problems, very often resulting from
                not well-formed XML, you will see a warning message.</para>
            <para>Now you can view your documents! The transformation will use the rules of the base
                ODD. For most text-centric TEI, the default rendition should already produce a
                readable result, but you will likely find aspects to improve to match your
                expectations. Quite often the need for customization will be limited to just a
                handful of elements. Refer to the <link linkend="pm-tutorial">Changing the presentation via ODD</link> chapter to learn about the ODDs and the Processing
                Model.</para>
            <para>If you upload a Microsoft Word document, the upload will automatically trigger the
                conversion of Word to TEI, using a special ODD for the transformation. Please note
                that the focus of this conversion is to preserve textual content, structure and
                basic semantics of the text, not to provide authoritative mapping of complete set of
                MS Word features to TEI. Refer to <link xlink:show="new" xlink:href="documentation.xml?id=docx">DOCX handling</link> section for more
                information.</para>
        </section>

    </section>
    <section xml:id="using-jinks">
        <title>Hands-on with Jinks</title>
        <para>After playing around with the <productname>TEI Publisher Documentation and
                Demo</productname> application, let's try and generate our own custom edition. As
            explained above, TEI Publisher now has an application manager, called
                <productname>Jinks</productname>. This will be your main entry point for creating or
            updating a custom edition.</para>
        <para>You can access <productname>Jinks</productname> via
                <productname>eXist-db's</productname> Dashboard. If you have not installed
                <productname>Jinks</productname> yet, use the Package Manager in the Dashboard to do
            so.</para>
        
        <para>Opening Jinks for the first time, you will see a login page. The default user is <code>tei</code> 
            and the password is the one displayed on the <productname>Documentation and Demo</productname> application browsing page. If you managed to login you see the main administration page 
            with three columns.</para> 

        <figure>
            <title>Jinks Login</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="jinks-login.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <section xml:id="using-jinks-first-steps">
            <title>First Steps</title>
            <itemizedlist>
                <listitem>
                    <para>The sidebar to the left shows the list of installed applications which
                        were created with Jinks (if any). In the screenshot there are two applications: <code>tp10</code> and <code>barth</code>.
                    </para>
                </listitem>
                <listitem>
                    <para>The central column contains the main configuration form with several tabs.
                    </para>
                </listitem>
                <listitem>
                    <para>The right column presents the configuration, as is currently in effect for
                        the application. The configuration is in JSON format and will initially show
                        as an empty object (empty curly brackets). As you fill out the form, you will
                        see how the JSON configuration is populated with corresponding
                        entries.</para>
                </listitem>
            </itemizedlist>
            <para>To start, you must fill at least the top three input fields under the first tab,
                    <guilabel>Application Configuration</guilabel>. In the first box,
                <guilabel>Abbreviation</guilabel>, provide a short but unique name. In the screenshot the abbreviation is <guilabel>barth</guilabel>. It will serve as a collection name in the database, where the
                application is stored. </para>
            <note><para>
                <emphasis role="bold">NB:</emphasis>Abbreviation may not contain whitespace,
                brackets and special characters. It may only contain alphanumeric characters
                (letters and numbers) supplemented with dashes (-) and underscore (_). </para>
            </note>
            <figure>
                <title>Jinks Application Configuration</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-config.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            
            <para>After filling out the abbreviation field, suggestions for the following two text
                boxes are provided automatically. The <option>label</option> is the title of the
                application, and will be used to caption the app in the Dashboard and elsewhere. It
                will initially be the set the same as the abbreviation, but you may change it to be
                more descriptive - and you can freely use whitespace, brackets etc. The
                    <option>unique identifier</option> must be a URI, but it does not need to be a
                real URL, pointing to some existing website. Like a namespace in XML, it can be
                anything as long as it is syntactically valid and unique.</para>
            <para>Running the generator with just these settings, the result would be an application
                without any documents. To provide some data to test with, switch to the
                    <guilabel>Profiles</guilabel> tab, search for the <guilabel>Demo Data</guilabel>
                feature in the <guilabel>Data Packages</guilabel> subsection and enable that
                checkbox.</para>
            
            <figure>
                <title>Jinks Profiles - Demo Data</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-profile.png"/>
                    </imageobject>
                </mediaobject>
            </figure>            
            
            <para>You are now ready to run the generator for the first time: click on the
                    <guibutton>Apply</guibutton> button in the bottom toolbar of
                    <productname>Jinks</productname>. you will see a wait indicator appear next to the
                button. The process may take a while as it consists of multiple steps:</para>
            <procedure>
                <step>
                    <para>configurations of all selected profiles are merged</para>
                </step>
                <step>
                    <para>files supplied by each profile are copied into a temporary collection in
                        the database</para>
                </step>
                <step>
                    <para>the temporary collection is packaged and installed into eXist-db</para>
                </step>
            </procedure>
            <para>Once the application is installed, a dialog will open. If you are creating a new
                app, it will inform you that the package has been deployed, along with a link which
                you can click to open the newly created application.</para>
            <figure>
                <title>Jinks Dialog</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-dialog.png"/>
                    </imageobject>
                </mediaobject>
            </figure>  
            <para>If you followed this section to the letter, and added only the <guilabel>Demo
                    Data</guilabel> feature, the created application should present three sermons by
                theologian Karl Barth. Clicking on one of those will display the text of the
                sermon.</para>
            <para>In Jinks itself you can now see your new created application in the left column. </para>
            <figure>
                <title>Jinks Profiles Tab</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-barth.png"/>
                    </imageobject>
                </mediaobject>
            </figure>  
            

        </section>
        <section xml:id="jinks-adding-features">
            <title>Adding Features</title>
            <para>The sermons contain mentions of places and people. To make use of the information
                available about these in the dataset, we can enable the profile dedicated for this
                purpose.</para>
            <para>Switch back to <productname>Jinks</productname>, go to the
                    <guilabel>Profiles</guilabel> tab and find the <guilabel>Entity
                    Registers</guilabel> profile in the <guilabel>Features</guilabel> category.
                Enable it and click <guibutton>Apply</guibutton> again.</para>
            <figure>
                <title>Jinks Entity Registers Feature</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-entity-registers.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>The <guilabel>Command Output</guilabel> dialog will now present a list of updated files.
                Close it and return to the generated app. Looking at the
                menubar, you will notice that there are new menu items for
                    <guilabel>People</guilabel> and <guilabel>Places</guilabel>, leading to separate
                pages for browsing those entities.</para>
            <para>We might also like to show a list of places and people mentioned in the current
                document, when viewing one of the sermons. This sub-feature is not enabled by
                default, because editions may not necessarily want limit it to some pages, or not to use it at all.</para>
            <para>To enable it globally, go back to Jinks and look at the editor to the right, which
                shows you a JSON representation of the currently active configuration for the
                application. Right now it should look like this (though the order of properties may
                differ):</para>
            <programlisting language="json" xml:space="preserve">{
  "pkg": {
    "abbrev": "barth"
  },
  "label": "barth",
  "id": "https://e-editiones.org/apps/barth",
  "extends": [
    "base10",
    "demo-data",
    "registers",
    "theme-base10"
  ]
}</programlisting>
            <para>Configuration parameters for feature profiles must go under a property called
                    <code>features</code>, followed by the name of the profile. While we're at it,
                we could also disable the navigation buttons in the toolbar (the sermons use a
                single-page display). Change the configuration and add the <code>features</code> as
                below:</para>
            <programlisting language="json" xml:space="preserve">{
  "pkg": {
    "abbrev": "barth"
  },
  "label": "barth",
  "id": "https://e-editiones.org/apps/barth",
  "extends": [
    "base10",
    "demo-data",
    "registers",
    "theme-base10"
  ],
  "features": {
    "register": {
        "enabled": true
    },
    "toolbar": {
      "navigation": false
    }
  }
}</programlisting>
            <para>After applying the new configuration, you should find a register sidebar, listing
                people and places, to the right of each sermon's text.</para>
            <figure>
                <title>Document view with register sidebar</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-registers.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
        </section>
        <section xml:id="jinks-theme-customization">
            <title>Customizing the theme</title>
            <para>Some of the most frequently changed styling aspects can be configured via the
                    <filename>config.json</filename>, allowing users to change colors, fonts or
                logos without editing CSS. For example, most projects will want to use their own
                logo in the menu and the splash screen (which appears while a page loads), and
                perhaps pick a custom background for the header as well.</para>
            <para>To make these changes, we first have to upload the necessary images. The
                    <guilabel>Files</guilabel> tab in <productname>Jinks</productname> provides a
                simple file manager, which we can use to browse and upload files into the database.
                It will initially show the collection root of the currently selected application.
                Images used for the general page layout should go into
                    <filename>resources/images</filename>, so navigate to that collection, then
                either drag and drop the desired images from your system's file manager or click the
                    <guibutton>Upload</guibutton> button.</para>
            <note>
                <para>The <guilabel>Files</guilabel> tab will only become visible after you
                    generated the application!</para>
            </note>
            <figure>
                <title>Jinks: Managing Files</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-filemanager.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>Either use your own images or the ones from the following sample:<link xlink:href="images/karl-barth/logo-white.png" xlink:show="new">logo-white.png</link>, <link xlink:href="images/karl-barth/type.jpeg" xlink:show="new">type.jpeg</link> and <link xlink:href="images/karl-barth/Karl_Barth.jpg" xlink:show="new">Karl_Barth.jpg</link>. They are available from <link xlink:href="https://github.com/eeditiones/jinks/tree/main/profiles/docs/data/doc/images/karl-barth" xlink:show="new">GitHub Jinks repository</link> as well. It is possible to
                upload multiple resources into a database collection at once. </para>
            <figure>
                <title>Jinks: Upload files</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-upload.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            
            <para>With the images uploaded, we can add them to the configuration. All settings
                related to the look and feel of an application go into the <code>"theme"</code>
                property of the configuration file. For example, to change the logo, splash screen
                image and menubar background, we could change the configuration as follows:</para>
            <programlisting language="json" xml:space="preserve">{
  "pkg": {
    "abbrev": "barth"
  },
  "label": "barth",
  "id": "https://e-editiones.org/apps/barth",
  "extends": [
    "base10",
    "demo-data",
    "registers",
    "theme-base10"
  ],
  "features": {
    "register": {
        "enabled": true
    },
    "toolbar": {
      "navigation": false
    }
  }
  "theme": {
    "logo": {
      "image": "../images/logo-white.png"
    },
    "menubar": {
      "background-image": "../images/type.jpeg"
    },
    "splash": {
      "image": "../images/Karl_Barth.jpg"
    },
    "fonts": {
      "content": {
        "family": "var(--jinks-base-font-family)",
        "size": "1.125rem"
      }
    }
  }
}</programlisting>
            <para>Note that all image paths will be relative to the CSS stylesheet (which lives in
                    <filename>resources/css</filename>), so we have to go up one level (using
                    <filename>../</filename>) and then down to <filename>images</filename>.</para>
            <para>The final setting above also changes the font used for the content. By default
                this will be a serif font (<productname>JunicodeVF</productname>), which is good for
                many historic scripts, but for a 20th century text, we may prefer to use the same
                sans-serif font as for the rest of the page (<productname>Inter</productname>).
                However, instead of providing a font name directly, we reference the CSS variable
                    <code>--jinks-base-font-family</code>, which predefines the corresponding
                font.</para>
            <para>We may want to decrease the font size a bit as well, setting it to
                    <code>1.125rem</code>. Note that for font scaling to work properly, we should
                use relative sizes based on the browser's base size, therefore using
                    <code>rem</code> here, not sizes in points or pixels.</para>
            <figure>
                <title>App with theme changes applied</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="karl-barth-theme.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>Finally, we can change the color scheme used by switching to the
                    <guilabel>Theming</guilabel> tab and choosing one of the available schemes. Note
                that this will add a property <code>"palette"</code> to the configuration,
                referencing the selected color scheme's name. </para>
            <note>
                <para>TEI Publisher comes with a small number of predefined color schemes, but you
                    can add your own palette. Using a well-chosen, limited color palette is in
                    general considered good practice in web design, which is why we avoid using
                    hard-coded colors.</para>
            </note>
        </section>
        <section xml:id="odd-creation">
            <title>Creating an ODD</title>
            <para>And now: action! One important step is still missing for a custom edition:
                creating your own ODD for text transformations. Jinks provides a control for this on
                the <guilabel>Application Configuration</guilabel> tab. Since we're dealing with
                Karl Barth, let's add an ODD called <filename>barth.odd</filename>.</para>
            <figure>
                <title>Create your own ODD</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-create-odd.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            
            <para>After clicking <guibutton>Add</guibutton>, you will see two new configuration
                entries:</para>            
            <programlisting language="json" xml:space="preserve">"odds": [
    "barth.odd"
  ],
  "defaults": {
    "odd": "barth.odd"
  }</programlisting>
            <para>The first adds <filename>barth.odd</filename> to the list of available ODDs
                inherited from the base and other profiles. The second sets this ODD as the default
                to use.</para>
            <note>
                <para>The created ODD will be empty, but extends
                        <filename>teipublisher.odd</filename>. If you would like to register an ODD
                    you already have, use the file manager to copy it to
                        <filename>resources/odd</filename> first. Afterwards follow the same steps
                    as described here. Jinks will notice that the file already exists and will just
                    register it.</para>
            </note>
            <para>What is important to know now is that adding an ODD to the configuration
                    <emphasis>after</emphasis> the app was initially generated <emphasis>does not
                    automatically use this ODD</emphasis>. Very likely the text will still be
                rendered using the default <filename>teipublisher.odd</filename>, which is the
                fallback.</para>
            <para>To fix this we need to run an action one time: actions are shown in the bottom
                toolbar of <productname>Jinks</productname>. Each profile may contribute its own
                actions, but there are four default actions always available. One of them is called
                    <guilabel>Fix ODDs</guilabel>. Click on it to recompile all ODDs (which means to
                translate them into XQuery code) and wire them up correctly in the system. Once the
                process has completed, the new ODD will actually be used and you could start
                extending it.</para>
            <figure>
                <title>Jinks action toolbar</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-action-toolbar.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <note>
                <para>You only need the <guilabel>Fix ODDs</guilabel> action if you add or update an
                    ODD in an already existing application, i.e. an application already installed
                    into the database – or if there were <emphasis>upstream updates</emphasis> to
                    the profiles you use (see the section on applying updates below).</para>
                <para>The same goes for the <guilabel>Reindex Data</guilabel> action: you only need
                    to call it, if you changed the index configuration for an existing app.</para>
            </note>
        </section>
        <section xml:id="jinks-download-sync">
            <title>Downloading the application</title>
            <para>
                <productname>Jinks</productname> operates within the database, which means all files
                it generates and modifies exist inside the database only. To keep track of changes
                and to have a backup, you always want to download the generated files to the file
                system. There are two actions for this:</para>
            <variablelist>
                <varlistentry>
                    <term><guilabel>Download</guilabel></term>
                    <listitem>
                        <para>Packages the application into a single archive (a so called XAR),
                            which you can later re-install into eXist-db using the Package Manager
                            in the Dashboard. This is a quick choice for passing the application on
                            to other people to try out.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><guilabel>Sync</guilabel></term>
                    <listitem>
                        <para>Synchronizes the file hierarchy into a local disk directory. Note that
                                <emphasis>local</emphasis> means the machine where eXist-db is
                            running. If you are using docker, the directory will be
                                <emphasis>inside</emphasis> the docker image. If you connect to a
                            remote server, it will be a directory on the server. Sync therefore is
                            particularly convenient to use during the development, to create
                            snapshots to be committed to the source control repository, like
                            Git.</para>
                        <figure>
                            <title>Jinks Sync Action</title>
                            <mediaobject>
                                <imageobject>
                                    <imagedata fileref="jinks-sync.png"/>
                                </imageobject>
                            </mediaobject>
                        </figure>
                        
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>Both actions allow you to quickly retrieve a copy of your work. For more
                information regarding development workflows and later updates, please refer to the
                <link xlink:href="documentation.xml?id=development-workflow">reference guide</link>.</para>
        </section>
        <section xml:id="jinks-apply-updates">
            <title>Applying updates</title>
            <para>There are two main scenarios in which you will update the application via Jinks
                (by pressing the <guibutton>Apply</guibutton> button):</para>
            <orderedlist>
                <listitem>
                    <para>you modified the configuration: by changing settings, adding/removing
                        profiles, uploading new files etc. This is what we've done above.</para>
                </listitem>
                <listitem>
                    <para>a new version of TEI Publisher becomes available, which means you will
                        update the version of Jinks installed, and – as a consequence – some of the
                        profiles your app is using will have changed
                        <emphasis>upstream</emphasis>.</para>                    
                </listitem>
            </orderedlist>
            <para>
                <productname>Jinks</productname> continuously tracks the files in your application
                to make sure updates will run smoothly. In particular, it needs to prevent that
                    <emphasis>upstream updates</emphasis>, i.e. changes coming from a profile, will
                overwrite any change you have applied locally in your app.</para>
            <para>Whenever you press <guibutton>Apply</guibutton>, the <guilabel>Command
                    Output</guilabel> dialog will show you a list of files. To the left of each file
                you will see a label. In most cases this will just show <emphasis>update</emphasis> with a green
                background. However, next to some files, brown <emphasis>conflict</emphasis> label may appear.</para>
            <figure>
                <title>Command output dialog showing a conflict</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="jinks-conflict.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>A <emphasis>conflict</emphasis> means that <productname>Jinks</productname> detected changes you made
                to this file since it was last updated, and it refused to overwrite this file with
                the original version coming from one of the profiles. For example, if I would change
                    <filename>teipublisher.odd</filename> in my app (via the ODD editor), Jinks
                would detect this next time I press <guibutton>Apply</guibutton> and mark it as a
                conflict.</para>
            <para>It is up to you to decide how to handle the conflict. You can tell <productname>Jinks</productname> 
                to ignore the conflict and
                overwrite the file with the <emphasis>upstream</emphasis> version by clicking the <guilabel>Overwrite
                    with next update</guilabel> button to the right of the entry.</para>
            <note><para>Conflict over the <filename>teipublisher.odd</filename> would be an example of a change that likely should be reverted. 
            Custom ODD rules for your application should be given in your own ODD, which extends the <filename>teipublisher.odd</filename>, 
            instead of directly changing the base ODD.</para></note>
            <para>You may also decide that the change is intentional, meaning that the conflict is
                expected and will stay. In this case, you may want to <emphasis>whitelist</emphasis> the file. 
                Files referenced by the whitelist will not be touched by future updates. You can
                do so by adding it to the <emphasis>skip</emphasis> property in <filename>config.json</filename>, which expects an array of
                paths relative to your application root:</para>
            <programlisting language="json" xml:space="preserve">{
    …
    "skip": [
        "resources/odd/landing.odd",
        "resources/i18n/app/.+.json"
    ]
    …
}</programlisting>
            <para>The paths are interpreted as regular expressions, so in the example above, we're
                skipping <filename>landing.odd</filename> as well as all i18n files ending with
                    <filename>.json</filename>. </para>
            <para>With new <emphasis>upstream</emphasis> versions of TEI Publisher or one of the profiles, you may need a hybrid approach, 
            namely add some of the <emphasis>upstream</emphasis> changes, while retaining some of yours. In such case you need to manually edit the file in question.</para>
            <note>
                <para>To avoid unnecessary conflicts, it is important that customization changes go
                    into files you have added yourself. It is easily possible, because TEI Publisher
                    on many levels provides configuration options, which allow you to add custom CSS
                    stylesheets, JavasSript, or API endpoints to your application without changing
                    what is already there. Added, custom files will never trigger a conflict,
                    because they only exist within your application.</para>
            </note>
        </section>
        <section xml:id="jinks-operation-modes">
            <title>Operation modes</title>
            <para>Tightly connected to updates and conflict detection are the three different
                operation modes <productname>Jinks</productname> provides. You can switch between
                them through the select on the bottom of the <guilabel>Application
                    Configuration</guilabel> tab:<variablelist>
                    <varlistentry>
                        <term><guilabel>Quick update</guilabel></term>
                        <listitem>
                            <para>is the fastest mode and selected by default. It does not check
                                every file for changes, but looks at the last modification date to
                                see if there were changes to the <emphasis>upstream
                                    version</emphasis> coming from the profile.</para>
                            <para>Consequently it will not report conflicts if they can be safely
                                ignored (because there are no upstream changes to overwrite
                                them).</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><guilabel>All</guilabel></term>
                        <listitem>
                            <para>checks the content of each file and compares it to the version
                                last installed. This mode reliably detects and reports all potential
                                conflicts.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><guilabel>Factory reset</guilabel></term>
                        <listitem>
                            <para>is the most drastic and dangerous of the modes: it completely
                                deletes the installed application and recreates everything from the
                                configuration. <emphasis>Don't use it unless you have the current
                                    version safely backed up and really know what you are doing: you
                                    are certain you want to start from scratch, or you are a
                                    developer working on a profile for Jinks</emphasis>!</para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </para>
        </section>

    </section>
    <section xml:id="pm-tutorial">
        <title>Changing the presentation via ODD</title>
        <para>If you followed the steps so far and opened one of the sermons, you will notice that –
            while the default rendition of the text looks fine – some details are not quite right.
            For example, each sermon begins with the bible passage of the day and this should stand
            out a bit more.</para>
        <para>We therefore need to change the ODD, <filename>barth.odd</filename>, which we created
            in the <link linkend="odd-creation">previous chapter</link>. You have the choice between writing the ODD by hand (it is TEI
            after all) or using a form-based visual ODD editor. Both approaches can be combined and
            mixed. The visual editor saves the ODD in a non-destructive way, preserving any
            information not related to the processing models. It is therefore safe to switch between
            hand-editing the ODD and using the visual editor. Just make sure you reload the visual
            editor view after modifying the source XML and vice versa. That said, visual editor is
            specifically tailored to editing processing models so it will be likely the fastest and
            safest way to edit your ODD.</para>
        <note>
            <title>Important</title>
            <para>If you edit the ODD XML by hand, there are some caveats you need to be aware of:
                the visual editor will automatically check if there are existing <tag>elementSpec</tag>
                s for a new element in any of the ODDs your ODD inherits from. When editing by hand, you
                need to do this yourself. It's best to always have the base <link xlink:href="odd/teipublisher.odd" role="source">
                    <filename>teipublisher.odd</filename>
                </link> open on the side. It is located in the same collection as your odd, i.e.
                <filename>/db/apps/tei-publisher/odd</filename>. </para>
            <para>For example, to modify the element spec for <tag>dateline</tag>, check <filename>
                    teipublisher.odd</filename>, where you will find a definition already. Copy it over to
                your ODD and start modifying it. </para>
            <para>Pay attention to the <option>@mode</option> attribute on <tag>elementSpec</tag>.
                You must set this to <parameter>change</parameter> if you are overwriting an <tag>elementSpec</tag>
                which already exists in the inherited ODDs. If not, set it to
                <parameter>add</parameter>. </para>
        </note>
        <section xml:id="pi-first-steps">
            <title>First steps</title>
        <para>To open the visual editor, go to the Admin menu (which is only visible if you are
            logged in), and select <guimenuitem>Edit ODD: barth.odd</guimenuitem>. A new tab opens,
            showing an action panel to the left, and the title of your ODD to the right. Initially
            your ODD will appear empty.</para>
        <figure>
            <title>Empty ODD editor</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="odd-empty-editor.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <para>To be able to customize the display of your data it is crucial to understand its XML
            structure well. You can check the underlying XML using the corresponding links in the
                <guimenuitem>Download</guimenuitem> menu: you will see that the whole bible passage is
            marked up as an <tag>epigraph</tag> with a nested <tag>cit</tag>. The actual bible text
            is wrapped into a <tag>quote</tag> and the reference is encoded with a <tag>ref</tag>
            with <code>type="can"</code> and <code>subtype="bible"</code>:</para>
        <programlisting language="xml" xml:space="preserve">&lt;epigraph&gt;
    &lt;cit&gt;
        &lt;ref type="can" subtype="bible" target="Apk.1.8"&gt;Offenbarung 1,8&lt;/ref&gt;
        &lt;quote&gt;Ich bin das A und das O, der Anfang und das Ende, spricht Gott der Herr, der da ist und der da war und der da kommt, der Allmächtige.&lt;/quote&gt;
    &lt;/cit&gt;
&lt;/epigraph&gt;</programlisting>
        <para>First, we may want to add some space before and after the epigraph, indent the bible
            text a little and render it in italics.</para>
        <para> To create a processing model addressing this need we have to know three things: </para>
        <itemizedlist>
            <listitem>
                <para>
                    <emphasis role="bold">when</emphasis> should it be applied, </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis role="bold">what</emphasis> is supposed to happen </para>
            </listitem>
            <listitem>
                <para> and <emphasis role="bold">how</emphasis> should the text be formatted?
                </para>
            </listitem>
        </itemizedlist>
        <para>Our first processing model should be applied to the <tag>epigraph</tag>, it should
            format it as a block-level element, and we would like to add margins before and after.
            In the <guilabel>Add Element</guilabel> input box to the left, enter
                <code>epigraph</code> and press on the <guibutton>+</guibutton> button.</para>
        <para>A new tab will appear to the right, showing the existing definition for
                <tag>epigraph</tag>. Where does it come from? It is inherited from the base ODD,
                <filename>teipublisher.odd</filename>. It already contains generic rules for the
            most common TEI elements. All TEI-related ODDs in TEI Publisher extend this.</para>
        <para>The existing model already treats <tag>epigraph</tag> as a <code>block</code> as can
            be seen in the <guilabel>behaviour</guilabel> setting. So all we need to do is to change
            the rendition to add margins.</para>
        <para>Let's cover some key concepts of the TEI processing model first:
                <tag>elementSpec</tag> primarily documents the structure, content, and purpose of an
            element. It is a core element in any ODD but the schema-related functions are not
            relevant for the discussion here. What is important for us is this is where processing
            models are defined. The <parameter>@ident</parameter> attribute of the
                <tag>elementSpec</tag> identifies the name of the element to which the spec (and
            therefore processing model) applies. </para>
        <para>An <tag>elementSpec</tag> may contain one or more <tag>model</tag> elements to specify
            the intended processing of this element. Every model maps the element to a
                <option>behaviour</option>. A behaviour denotes an abstract transformation function
            to be applied. The TEI guidelines currently list two dozen behaviours, e.g. paragraph,
            heading, note, inline, block. The last two are the most frequently used. How exactly a
            behaviour translates into the target output media may differ depending on media features
            and design decisions. TEI Publisher tries to implement them as generically as
            possible.</para>
        </section>
        <section xml:id="pi-output-renditions">
            <title>Using output renditions</title>
            <para>The processing model uses <tag>outputRendition</tag> and CSS to define visual
                aspects. For output formats other than XML, the CSS is translated into the
                corresponding target language. It is thus best to limit the CSS to the most common
                typographical features, like bold, italic, color, underline etc. The general styling
                of the text should be done outside the ODD to maintain a clear separation of
                concerns.</para>
            <para>To add some top and bottom margin to the <tag>epigraph</tag>, click on the
                    <guibutton>+</guibutton> next to <guilabel>Renditions</guilabel>. This opens a
                new input into which we can enter CSS. For the margins and padding, we can simply
                add:</para>
            <synopsis language="css">margin: 1rem 0;
padding: 0 2rem;</synopsis>
            <figure>
                <title>elementSpec for epigraph with renditions</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="odd-epigraph.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>Once you're done with the change, click on the button with the disk symbol in the
                toolbar to the left to save and compile the ODD. A pop-up will appear, reporting the
                result of the compilation process:</para>
            <figure>
                <title>Pop-up displayed after saving ODD</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="odd-popup.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <note>
                <para>TEI Publisher compiles the ODD into executable XQuery code. For each output media format supported, one
                    XQuery module is created as reported in the screenshot.</para>
                <para>Eventually this process may fail, e.g. if you entered incorrect XPath
                    expressions somewhere. In this case the pop-up will report the failure for each
                    output format. It still saves the resulting XQuery code into a file with the
                    marker <code>.invalid</code> in its name, e.g.
                        <filename>barth-web.invalid.xql</filename>. If you cannot figure out your
                    mistake otherwise, it sometimes helps to open the invalid XQuery in eXide, enter
                    a space somewhere to trigger validation and look at the error message eXide
                    gives you, which is often quite helpful. Don't be afraid of the XQuery code: the
                    mapping between the ODD and the generated XQuery is actually quite
                    straightforward.</para>
                <para>This said, the visual ODD editor does also run syntax checks on all XPath statements and you should pay attention
                    to any red markers to avoid running into issues.</para>
            </note>
            <para>Switch back to the tab with the sermon text from which you opened the editor and
                refresh the browser window to see your changes applied. In case you do not see any
                change, make sure </para>
            <orderedlist>
                <listitem>
                    <para>you are using the correct ODD: the URL should contain a query parameter
                            <option>odd</option> pointing to the name of your ODD. If not, go back
                        to the <link linkend="odd-creation">Jinks section</link> and check if the
                            <code>defaults.odd</code> configuration property is correctly set to
                        your ODD.</para>
                </listitem>
                <listitem>
                    <para>if you made changes to <tag>outputRendition</tag>s only, you may need to clear your
                        browser's cached version. For most browsers, holding the
                            <emphasis>Shift</emphasis> key while clicking on the
                            <emphasis>Reload</emphasis> button does the job.</para>
                </listitem>
            </orderedlist>
            <para>Instead of using the visual ODD editor, we could also work directly on the XML of
                the ODD. You can see the XML by clicking on the <guibutton>&lt;&gt;</guibutton> toolbar
                button to the left. For reference, our <tag>elementSpec</tag> for
                    <tag>epigraph</tag> should currently look as follows:</para>
            <programlisting language="xml" xml:space="preserve">&lt;elementSpec ident="epigraph" mode="change"&gt;
    &lt;model behaviour="block"&gt;
        &lt;outputRendition xml:space="preserve"&gt;
        margin: 1rem 0;
        padding: 0 2rem;
        &lt;/outputRendition&gt;
    &lt;/model&gt;
&lt;/elementSpec&gt;</programlisting>
        </section>
        <section>
            <title>Conditions and multiple models</title>
            <para>Next, we'd like to format the bible quote and make the text italic. If you add an
                <tag>elementSpec</tag> for quote, you will see that it has two models by default. The first one
                has a condition, which is reflected in the description and the corresponding XPath
                printed in red below. Conditions allow you to distinguish uses of the same element
                in different contexts. In the given scenario, <tag>quote</tag> will be rendered
                inline if it has a <tag>p</tag>, <tag>cell</tag> or <tag>cit</tag> ancestor.
                Otherwise the second model outputs it as a block.</para>
            <para>The processing model uses a <option>predicate</option> to make such distinctions:
                a model rule will only be used if the XPath expression in its predicate matches the
                current node being processed. And if there's more than one <tag>model</tag> within
                an <tag>elementSpec</tag>, only the first model matching all conditions will be
                used. Any model after the matching one will be ignored.</para>
            <para>Since our <tag>quote</tag> is indeed located within a <tag>cit</tag> element, we
                have to modify the first model:</para>
            <figure>
                <title>elementSpec for <tag>quote</tag></title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="odd-quote.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>The sermons look better now, but we still have the bible reference inlined before
                the bible quote. We want to make this a block and center it:</para>
            <procedure>
                <step>
                    <para>add an <tag>elementSpec</tag> for ref with behaviour <code>block</code></para>
                </step>
                <step>
                    <para>it should be limited to canonical references, which we could express by
                        adding a predicate <code>@type="can"</code>. However, this would apply to
                        all bible references in the text. Therefore the predicate needs to be
                        further limited to canonical references within the
                        epigraph:</para>
                    <synopsis language="xquery">@type="can" and ancestor::epigraph</synopsis>
                </step>
                <step>
                    <para>add an <tag>outputRendition</tag> to center the text:</para>
                    <synopsis language="css">text-align: center;</synopsis>
                </step>
            </procedure>
            <para>Applying this change, the bible reference becomes centered above the bible
                passage. So far so good. Unfortunately it is no longer a link because we turned it
                into a block. To again make it a link, we need to introduce another key concept:
                    <emphasis>parameters</emphasis>.</para>
        </section>
        <section xml:id="pi-parameters">
            <title>Using parameters</title>
            <para>All behaviours accept one or more parameters which are defined in the TEI
                guidelines. Every behaviour has an implicit parameter called
                    <parameter>content</parameter>, and, as the name suggests, it specifies which
                part of the source document should be processed: by default it uses the nested
                content of the node. You may overwrite this default and assign it another value.
                Some behaviours take other specialized parameters. For example, the <parameter>
                    alternate</parameter> behaviour accepts two parameters:
                    <parameter>default</parameter> and <parameter>alternate</parameter>. An
                alternate switches between two alternative states. On the web this could take the
                form of a pop-up, in print it is usually implemented as a footnote.</para>
            <para>The link behaviour accepts two extra parameters:</para>
            <variablelist>
                <varlistentry>
                    <term><parameter>uri</parameter></term>
                    <listitem>
                        <para>the URI to link to</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>target</parameter></term>
                    <listitem>
                        <para>corresponds to the <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#target">HTML attribute</link> of the same name and determines how
                            the link would be opened in a web browser</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>We'll switch our model for <tag>ref</tag> to use <option>link</option> and set both parameters:</para>
            <procedure>
                <step>
                    <para>change the behaviour of our model to <option>link</option></para>
                </step>
                <step>
                    <para>in the <guilabel>Parameters</guilabel> section, add a parameter and set
                        its name to <code>uri</code></para>
                </step>
                <step>
                    <para>for the parameter value, let's create a proper URL pointing to an external
                        service to give readers the possibility to read the bible passage in
                        context:</para>
                    <synopsis language="xquery">'https://www.bibleserver.com/LUT/' || @target</synopsis>
                    <para>The <code>||</code> expression is a string concatenation operator in
                        XPath/XQuery: we append the content of the <option>@target</option>
                        attribute to the base URI pointing to the online Luther Bible.</para>
                </step>
                <step>
                    <para>add another parameter named target with value <code>'_blank'</code>. This will result
                    in the link being opened in a new browser tab (unless the user configured the browser to behave differently).</para>
                </step>
                <step>
                    <para>a link is an inline element. To still render it as a block and center it,
                        we can change the CSS in the
                        <tag>outputRendition</tag>:</para>
                    <programlisting language="css">display: block;
text-align: center;</programlisting>
                </step>
            </procedure>
            <figure>
                <title>Add a model for ref</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="odd-bible-ref.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            <para>Clicking on the bible reference will now open a new tab and load the external
                    <emphasis>bibleserver</emphasis> service, which nicely displays the bible
                passage in context.</para>
            <note>
                <para>Obviously the <emphasis>bibleserver</emphasis> provides a much more modern
                    version of Luther's bible than the one Karl Barth used back in 1915. The proper
                        <link xlink:href="https://kbga.karl-barth.ch/texts/27003">Karl Barth
                        Gesamtausgabe</link> integrates the correct version (published 1912) as XML,
                    but that version unfortunately is not freely available.</para>
            </note>
            <para>However, you may note that bible references elsewhere in the text are still wrong,
                i.e. leading nowhere. Fixing this should be easy, but we'll leave this as an
                exercise.</para>
            
        </section>
    </section>
    <section xml:id="next">
        <title>Further steps</title>
        <para>This brief introduction aims to give a very basic orientation in using Jinks and TEI
            Publisher. For more in depth discussion of various subjects you may want to check the
                <link xlink:href="documentation.xml">Reference Manual</link> and <link xlink:href="webcomponents.xml">Web Components</link>.</para>
        <para>e-editiones runs a series of monthly community meet-ups and also maintains a Slack
            community, which provide a space for discussion, coordination of efforts and community
            support. Check the <link xlink:href="https://www.e-editiones.org">website</link> to find
            meeting announcements and recordings of past presentations and workshops.</para>
    </section>
</article>