Support for Glossary

[ashfurrow]

Glossaries are a really cool feature, and I think this tool needs to support them. They're easy enough to use, just a plist that's a literal dictionary, but they have this "First Use" thing that gets tricky. Here's an amended example from one of Apple's books:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Terms</key>
    <dict>
        <key>while loop</key>
        <dict>
            <key>Definition</key>
            <string>A block of code that runs for as long as a given condition is true. When the condition changes to false, the loop stops running. 
</string>
            <key>FirstUse</key>
            <dict>
                <key>PageReference</key>
                <string>While%20Loops/Introduction</string>
                <key>Title</key>
                <string>While Loops</string>
            </dict>
        </dict>
    </dict>
</dict>
</plist>

I haven't figured out what the PageReference or Title are for yet. Help would be appreciated.

[ashfurrow]

Looks like "FirstUse" is used in the overview of the glossary:

Looks a bit funny without a FirstUse, but it might be acceptable. For anyone looking to use glossaries, putting a Glossary.plist file in your Resources directory is sufficient :+1:

[rhysforyou]

Plists aren't exactly the friendliest format to work with, did we want to support glossaries written in, for example, YAML?

[ashfurrow]

Great idea! It wouldn't be too hard to scan through the markdown and look for glossary:// links, to generate the FirstUse programmatically (once we figure out what the PageReference is, I think Title is used in the "Introduced In" column).

[rhysforyou]

Just eyeballing it, the page reference seems to be in the format of <chapter title>/<page title> where both are URL escaped. Does that mean that both chapter and page names have to be unique across the book?

[ashfurrow]

Looks that way, I've verified that works with Apple's books. I think that the chapter title / page title combo needs to be unique, which isn't too bad of a restriction.

[ashfurrow]

So do we think another glossary.plist is a good idea, or should we just include a glossary dictionary in the main book.yml file?

[rhysforyou]

It seems to make sense to me that it should be part of the core book.yml file