Improve glossary section and example with <glossseealso/> and <glosssee/>

[tomschr]

Situation

I came across example 13 in the Style Guide. However, I see some problems with this example and this section:

• The <glossary> root element lacks the DocBook namespace and its version.
• There is no example about <glosssee/> or <glossseealso/> (cross-reference elements).
• The second <glossentry> is unfortunate as it was introduced as "see also" but should better use <glosssee/>.
• There is no definition or explanation between the two cross-reference elements.
• Not all glossary entries have an xml:id attribute. This makes it impossible to link to it.

Benefits

I'd suggest to include and describe the elements <glossseealso/> and <glosssee/>. I see the following benefits, although they are kind of related to each other:

• Consistency
  A cross-reference to another entry makes it easier to follow for the reader.
• Layout
  Each of a "see" or a "seealso" cross-reference appears after the text, not inside.
• Readability
  For the user, the overall structure of a definition gets clearer. The definition gets shorter as the writer doesn't have to include "see/see also/refer to/..." texts. For the user, it's easier to read and easier to grasp. Additionally, the cross-references always at the same place and it's not hidden in the text.
• Translation
  The need to translate a sentence is reduced as the text is automatically created. We don't need to translate variations of "see/see also/refer to/look into bla..." which makes the translation memory more consistent.

Certainly not big, world shattering benefits. 😉 However, although it looks like a small contribution, it makes our documentation consistent and easier to read.

Proposed solution

Both elements, <glossseealso/> and <glosssee/>, direct the reader to another glossentry. However, there is a specific distinction:

• glosssee: A "see" cross-reference occurs in place of the definition.
  For example, when a reader reads an entry about "XML" it should better read the entry "eXtensible Markup Language".
  There can only be one glosssee element.
  The readers need to follow the cross-reference, otherwise it wouldn't make sense to them.

• glossseealso: A "seealso" cross-reference gives the reader additional information.
  For example, in an entry about "eXtensible Markup Language" there could we one or more related entries like "DocBook" "SVG", etc.
  There can be zero or more glossseealso elements.
  The reader is free to use the cross-references or not.

If this is accepted, I'd suggest the following tasks:

• Add the previous definition of the two cross-references.
• Improve the example (see below).
• Mention some formal requirements (probably in a list):
  • an xml:id attribute on the <glossentry>, not the <glossterm>.
  • the ID naming (starting with gt-TERM, right?)
  • Spelling of the glossary term (lower- or uppercase?)
  • If these cross-references are used, I recommend to use them as empty elements. This will create the respective glossary entry automatically. If you add text, it might be necessary to translate them.
• Mention if glossary entries are automatically sorted?
• Review GeekoDoc if everything is there (should be).

I'd suggest to improve the mentioned example 13 and add also cross-references to other entries to make the use clearer:

<glossary xmlns="http://docbook.org/ns/docbook" version="5.2">
    <title>Glossary</title>

    <glossentry xml:id="gt-docbook">
        <glossterm>DocBook</glossterm>
        <glossdef><para>...</para></glossdef>
    </glossentry>

    <glossentry xml:id="gt-svg">
        <glossterm>SVG</glossterm>
        <glossdef><para>...</para></glossdef>
    </glossentry>

    <glossentry xml:id="gt-extensible-markup-language">
        <glossterm>Extensible Markup Language</glossterm>
        <glossdef>
            <para> A markup language that defines a set of rules for encoding
                documents in a format that is both human-readable and
                machine-readable. </para>
            <glossseealso linkend="gt-docbook"/>
            <glossseealso linkend="gt-svg">SVG (Scalable Vector Graphics)</glossseealso>
        </glossdef>
    </glossentry>

    <glossentry xml:id="gt-xml">
        <glossterm>XML</glossterm>
        <glosssee linkend="gt-extensible-markup-language" />
    </glossentry>

</glossary>

Additional information

• #269
• <glossseealso/>
  "A glossseealso directs the reader to another glossentry for additional information."
• <glosssee/>
  "A glosssee directs the reader to another glossentry instead of this one."

[dariavladykina]

This is now reflected in PR #272 and #271

[tomschr]

@dariavladykina There is one task still open: "Mention some formal requirements (probably in a list):" (see the task list above).

Should we create another issue from this? Or do you prefer to leave it as is and refer in another PR?

[dariavladykina]

I don't think we need to go into details here. We provide an example below (info on ID and naming) + lowercase spelling in this section + reference to the DocBook guide where everyone interested can check out the syntax.