[sword-devel] Headings, Titles and Intros

Thu Dec 17 15:52:44 MST 2009

Dear Manfred,

On 12/17/2009 12:02 PM, Manfred Bergmann wrote:
> Is it necessary to use a VerseKey for positioning in order to retrieve the headings?
>   
VerseKey::Headings(true|false) is currently how to turn intro records on
and off for VerseKey navigated modules.  These include:
testament.book.chap.0 for chapter intro
testament.book.0 for book intro
testament.0 for testament intro
0 for module intro

By default intro's are turned off.

The method name is confusing because 'Headings' was chosen before we had
any semblance of OSIS subheadings in verses.  VerseKey::Headings is a
prime candidate for a name change when we normalize the API naming
conventions in 2.0.

> Which XML/OSIS tags are then used to create the headings in the module?
>   
DM and others who maintain osis2mod can answer better than me, but I
believe these intros are populated from an OSIS doc by osis2mod choosing
the interverse text in the correct position, e.g.

<verse osisID="John.1.51">
...
</verse>
John Chapter 2 intro material
<verse osisID="John.2.1">
...
</verse>

The API lets you set this material with code like:

VerseKey *vk = (VerseKey *)module.getKey();
vk->Headings(true);
(*vk) = "jn.2.0";
module.setEntry("Intro Text for John 2");
The wiki mentions the <title/> tag and that it has to be placed right
before the verse/chapter.

> Does this also work for testament and book?
>   
Text parsing should work for jn.0.0, but I think you have to use some
crazy text for text parsing of book and testament headings... 
Basically, the text you get out of VerseKey::getText() should work for
setting with VerseKey::setText(), but I would suggest just using the
setters:

VerseKey::setTestament(0);
VerseKey::setBook(0);

> What is the "Headings" global option doing?
>   
Something entirely different.  These are for sections headings in the
text, including 'pre-verse' section headings.  These can be turned on
and off.  Headings are the little blurbs before a section like:

The Baptism of Jesus

Some of these are 'pre-verse', which means they should be displayed
before your frontend's verse marker.  These can be pulled from
entryAttributes, and each SWORD frontend has chapter display logic
similar to:

        VerseKey *key = (VerseKey *)currentText.getKey();
        VerseKey saveKey = *key;

        if (key->getVerse() != 1) {
                key->setChapter(0);
        } else {
                key->setVerse(0);

        SWBuf text = "<html><body>";
        for (; ((key->Chapter() == chapter) && (key->Book() == book) &&
!currentText.Error()); currentText++) {

             if (key->getVerse() == 0) {
                 text += currentText.RenderText();    // intro material
                 text += "<br/><br/>";
                 continue;
             }

            // see if there are any pre-verse headings
            SWBuf preverseHeading =
currentText->getEntryAttributes()["Heading"]["Preverse"]["0"].c_str();
            if (preverseHeading.length()) {
                text += "<br/><br/><b>";
                text += currentText.RenderText(preverseHeading); // do
any tag conversions for our requested markup
                text += "</b><br/><br/>";
            }

            // render our verse number marker
            text += "<font color=\"#0000ff\"><small>" + key->getVerse()
+ "</small></font>";
        }
        text += "</body></html>";
        textDisplay->setText(text);
        textDisplay->scrollToAnchor("curVerse");
        currentText->SetKey(saveKey);

    }

Hope this is helpful.

Troy

>
>
> Manfred
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page
>   