adding more glossary links in the glossary

adding more glossary links in the glossary

[Robert P. J. Day]

[-- Attachment #1: Type: text/plain, Size: 1082 bytes --]


  finally have time to jump back into docs now that everyone else has
done all the heavy lifting ... currently perusing glossary and noticed
the following right near the top. in glossary entry for AUTOREV, there
is the sentence:

"If you use the previous statement to retrieve the latest version of
software, you need to be sure PV contains ${SRCPV}."

  that last bit, the "${SRCPV}" part, is set up as a glossary link via
the .rst content:

  `${``\ :term:`SRCPV`\ ``}``

to get both a glossary link and the appropriate rendering. if that's
the way to do it, then it seems there's more in the glossary that
should be so rendered, as in just above that in AUTO_LIBNAME_PKGS, one
reads:

  "The default value is “${PACKAGES}”, ..."

which has the underlying .rst content as, well, exactly that so there
is no glossary link.

  is it safe to assume that, over time, things like that should
eventually be linkified, as in:

  `${``\ :term:`PACKAGES`\ ``}``

is there any reason you *wouldn't* want to use a glossary link if one
exists?

rday

Re: [docs] adding more glossary links in the glossary

[Quentin Schulz]

Hi Robert,

On October 29, 2020 9:13:31 AM GMT+01:00, "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
>
>  finally have time to jump back into docs now that everyone else has
>done all the heavy lifting ... currently perusing glossary and noticed
>the following right near the top. in glossary entry for AUTOREV, there
>is the sentence:
>
>"If you use the previous statement to retrieve the latest version of
>software, you need to be sure PV contains ${SRCPV}."
>
>  that last bit, the "${SRCPV}" part, is set up as a glossary link via
>the .rst content:
>
>  `${``\ :term:`SRCPV`\ ``}``
>
>to get both a glossary link and the appropriate rendering. if that's
>the way to do it, then it seems there's more in the glossary that
>should be so rendered, as in just above that in AUTO_LIBNAME_PKGS, one
>reads:
>
>  "The default value is “${PACKAGES}”, ..."
>
>which has the underlying .rst content as, well, exactly that so there
>is no glossary link.
>
>  is it safe to assume that, over time, things like that should
>eventually be linkified, as in:
>
>  `${``\ :term:`PACKAGES`\ ``}``
>
>is there any reason you *wouldn't* want to use a glossary link if one
>exists?
>

I seem to recall that only the first occurrence of a "term" in a page should be "linked" (with :term:``) as to not overload the page with links for every occurrence of every variable in the glossary. That was discussed on IRC or on the ML, probably in the mails summing up what was to be done with Sphinx migration.

In the end, while skimming through the docs for quick simple fixes, the rule is not rigorously applied (sometimes more than one occurrence is "linked" in the same page).

However, we at least want all variables to be highlighted with double tick on both sides of it, to show it's a variable.

Quentin

Re: [docs] adding more glossary links in the glossary

[Robert P. J. Day]

[-- Attachment #1: Type: text/plain, Size: 2326 bytes --]

On Thu, 29 Oct 2020, Quentin Schulz wrote:

> Hi Robert,
>
> On October 29, 2020 9:13:31 AM GMT+01:00, "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
> >
> >  finally have time to jump back into docs now that everyone else
> >has done all the heavy lifting ... currently perusing glossary and
> >noticed the following right near the top. in glossary entry for
> >AUTOREV, there is the sentence:
> >
> >"If you use the previous statement to retrieve the latest version of
> >software, you need to be sure PV contains ${SRCPV}."
> >
> >  that last bit, the "${SRCPV}" part, is set up as a glossary link via
> >the .rst content:
> >
> >  `${``\ :term:`SRCPV`\ ``}``
> >
> >to get both a glossary link and the appropriate rendering. if that's
> >the way to do it, then it seems there's more in the glossary that
> >should be so rendered, as in just above that in AUTO_LIBNAME_PKGS, one
> >reads:
> >
> >  "The default value is “${PACKAGES}”, ..."
> >
> >which has the underlying .rst content as, well, exactly that so there
> >is no glossary link.
> >
> >  is it safe to assume that, over time, things like that should
> >eventually be linkified, as in:
> >
> >  `${``\ :term:`PACKAGES`\ ``}``
> >
> >is there any reason you *wouldn't* want to use a glossary link if one
> >exists?
> >
>
> I seem to recall that only the first occurrence of a "term" in a
> page should be "linked" (with :term:``) as to not overload the page
> with links for every occurrence of every variable in the glossary.
> That was discussed on IRC or on the ML, probably in the mails
> summing up what was to be done with Sphinx migration.

  i can understand that in the sense of having a single link as a
"first term", but i can also see how that doesn't properly apply to a
glossary, as one normally does not read a glossary top down -- in
fact, it's far more likely that one showed up there following a link
to the specific term they were interested in. in that sense, a "page"
would be more aptly represented by a single glossary entry. if you
look at it that way, then the middle ground would be that the first
term in any single glossary entry would be a link, and not the rest of
them in that glossary entry.

  sorry if this was already hashed out before, just an observation.

rday

Re: [docs] adding more glossary links in the glossary

[Nicolas Dechesne]

On Thu, Oct 29, 2020 at 10:12 AM Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
> On Thu, 29 Oct 2020, Quentin Schulz wrote:
>
> > Hi Robert,
> >
> > On October 29, 2020 9:13:31 AM GMT+01:00, "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
> > >
> > >  finally have time to jump back into docs now that everyone else
> > >has done all the heavy lifting ... currently perusing glossary and
> > >noticed the following right near the top. in glossary entry for
> > >AUTOREV, there is the sentence:
> > >
> > >"If you use the previous statement to retrieve the latest version of
> > >software, you need to be sure PV contains ${SRCPV}."
> > >
> > >  that last bit, the "${SRCPV}" part, is set up as a glossary link via
> > >the .rst content:
> > >
> > >  `${``\ :term:`SRCPV`\ ``}``
> > >
> > >to get both a glossary link and the appropriate rendering. if that's
> > >the way to do it, then it seems there's more in the glossary that
> > >should be so rendered, as in just above that in AUTO_LIBNAME_PKGS, one
> > >reads:
> > >
> > >  "The default value is “${PACKAGES}”, ..."
> > >
> > >which has the underlying .rst content as, well, exactly that so there
> > >is no glossary link.
> > >
> > >  is it safe to assume that, over time, things like that should
> > >eventually be linkified, as in:
> > >
> > >  `${``\ :term:`PACKAGES`\ ``}``

This specific syntax bothers me a lot.. one reason we moved to Sphinx
was to have 'simple' documentation source and this specific syntax is
horrifying.. if it's a pattern we use a lot, perhaps we should create
a custom role for that, like :term2: for example, so that
:term2:`PACKAGES` would add the ${} and the fixed-font rendering.

> > >
> > >is there any reason you *wouldn't* want to use a glossary link if one
> > >exists?
> > >
> >
> > I seem to recall that only the first occurrence of a "term" in a
> > page should be "linked" (with :term:``) as to not overload the page
> > with links for every occurrence of every variable in the glossary.
> > That was discussed on IRC or on the ML, probably in the mails
> > summing up what was to be done with Sphinx migration.

I don't remember discussing that specific thing. What would be the
rationale for limiting the glossary link to 1 per page? performance? I
think the link to glossary terms are useful, and would be more
inclined to have as many as possible.

I even thought about an extension to add links everywhere it's possible..

>
>   i can understand that in the sense of having a single link as a
> "first term", but i can also see how that doesn't properly apply to a
> glossary, as one normally does not read a glossary top down -- in
> fact, it's far more likely that one showed up there following a link
> to the specific term they were interested in. in that sense, a "page"
> would be more aptly represented by a single glossary entry. if you
> look at it that way, then the middle ground would be that the first
> term in any single glossary entry would be a link, and not the rest of
> them in that glossary entry.
>
>   sorry if this was already hashed out before, just an observation.
>
> rday
>
> 
>

Re: [docs] adding more glossary links in the glossary

[Robert P. J. Day]

On Thu, 29 Oct 2020, Nicolas Dechesne wrote:

... snip ...

> This specific syntax bothers me a lot.. one reason we moved to
> Sphinx was to have 'simple' documentation source and this specific
> syntax is horrifying.. if it's a pattern we use a lot, perhaps we
> should create a custom role for that, like :term2: for example, so
> that :term2:`PACKAGES` would add the ${} and the fixed-font
> rendering.

... snip ...

  ah, irony ... while sphinx is so much easier to write, the one thing
i truly miss about docbook/XML is the semantic markup, which is
exactly what you're proposing. :-) again, i missed a lot of the recent
discussion on this list, being coincidentally buried in yocto project
work, but it seems that a simple solution would be to restore just a
wee bit of that semantic markup as above by defining, say "glossterm":

  :glossterm:`PACKAGES`

and let sphinx take it from there.

  that could be a massively stupid suggestion as i'm still perusing
the sphinx docs to truly understand how it works.

rday

Re: [docs] adding more glossary links in the glossary

[Quentin Schulz]

Hi Nicolas,

On October 29, 2020 10:18:58 AM GMT+01:00, Nicolas Dechesne <nicolas.dechesne@linaro.org> wrote:
>On Thu, Oct 29, 2020 at 10:12 AM Robert P. J. Day
><rpjday@crashcourse.ca> wrote:
>>
>> On Thu, 29 Oct 2020, Quentin Schulz wrote:
>>
>> > Hi Robert,
>> >
>> > On October 29, 2020 9:13:31 AM GMT+01:00, "Robert P. J. Day"
><rpjday@crashcourse.ca> wrote:
>> > >
>> > >  finally have time to jump back into docs now that everyone else
>> > >has done all the heavy lifting ... currently perusing glossary and
>> > >noticed the following right near the top. in glossary entry for
>> > >AUTOREV, there is the sentence:
>> > >
>> > >"If you use the previous statement to retrieve the latest version
>of
>> > >software, you need to be sure PV contains ${SRCPV}."
>> > >
>> > >  that last bit, the "${SRCPV}" part, is set up as a glossary link
>via
>> > >the .rst content:
>> > >
>> > >  `${``\ :term:`SRCPV`\ ``}``
>> > >
>> > >to get both a glossary link and the appropriate rendering. if
>that's
>> > >the way to do it, then it seems there's more in the glossary that
>> > >should be so rendered, as in just above that in AUTO_LIBNAME_PKGS,
>one
>> > >reads:
>> > >
>> > >  "The default value is “${PACKAGES}”, ..."
>> > >
>> > >which has the underlying .rst content as, well, exactly that so
>there
>> > >is no glossary link.
>> > >
>> > >  is it safe to assume that, over time, things like that should
>> > >eventually be linkified, as in:
>> > >
>> > >  `${``\ :term:`PACKAGES`\ ``}``
>
>This specific syntax bothers me a lot.. one reason we moved to Sphinx
>was to have 'simple' documentation source and this specific syntax is
>horrifying.. if it's a pattern we use a lot, perhaps we should create

I've seen it enough times to say it's not uncommon. The good news is that it's probably rather easy to grep the pattern.

>a custom role for that, like :term2: for example, so that
>:term2:`PACKAGES` would add the ${} and the fixed-font rendering.
>

Makes sense to me, :term_curly: maybe? Just something more explicit than "terms" :)

>> > >
>> > >is there any reason you *wouldn't* want to use a glossary link if
>one
>> > >exists?
>> > >
>> >
>> > I seem to recall that only the first occurrence of a "term" in a
>> > page should be "linked" (with :term:``) as to not overload the page
>> > with links for every occurrence of every variable in the glossary.
>> > That was discussed on IRC or on the ML, probably in the mails
>> > summing up what was to be done with Sphinx migration.
>
>I don't remember discussing that specific thing.

Looked for it in the mail archive, couldn't find any and I can't be bothered to look into months of IRC archives, so I probably "dreamed" it.

> What would be the
>rationale for limiting the glossary link to 1 per page? performance? I

It can be rather hard to read if all variables in a paragraph are underlined. That's personal taste though.

>think the link to glossary terms are useful, and would be more
>inclined to have as many as possible.
>

Works for me, what would be a case in which you wouldn't want links to be used?

>I even thought about an extension to add links everywhere it's
>possible..
>

I could see a plug-in looking for all glossary terms not linked in documents and display a warning for each of them. Inline substitution is too risky IMHO.

Quentin