RFC: see-also consistency

[jamesb93]

As earmarked by @tedmoore in #73 (review) there is a slight inconsistency in how see-also is treated across the CCEs in the RST.

His proposal is to normalise it a bit so we would have something like:

:flucoma-seealso:
:max-seealso:
:sc-seealso:
:pd-seealso:

I also vote that while we are in this space, we just make the hyphens into underscores. The jinja templates can't parse them by default and they get changed in the transformer which is more obscure code to write. So I propose this:

:flucoma_seealso:
:max_seealso:
:sc_seealso:
:pd_seealso:

If there are no serious objections I'm happy to go and PR this in but I wanted to gather intel first from @tremblap, @weefuzzy and @tedmoore.

[weefuzzy]

tldr – yeah, make it consistent

We ended up with sc-related in the old YAML as these were ported straight from .schelp files (where the scdoc key is related), Meanwhile, in the Max ref world, the equivalent is an XML block called see-also, so we ended up with diverging terms that didn't matter so long as the SC related stuff never figured.

• We can deal fine with hyphen in jinja if we use get
• an alternative now that we have .. only_in:: is to use that, but it might be irritatingly verbose

:flucoma-seealso: <blah> 

.. only_in:: sc 
   :seealso: <more blah> 

.. only_in:: pd 
   :seealso: <more different blah> 

[weefuzzy]

• We can deal fine with hyphen in jinja if we use get

Although that's harder if client_data ends up forming the top level of the jinja Environment. Maybe that wasn't a good idea

[jamesb93]

I find it a little verbose if its okay to maintain the current system we have.

Is your preference for hyphenations or nay? I think using one delimiter everywhere is nicer to read.

[weefuzzy]

I think my discomfort is about hard-coding top level keys that mention specific CCEs, but maybe I should get over it.

One possibility (which would require slightly more elaborate python)

:seealso: 
   :flucoma: <fluid object name templates that will get transformed, and linked to> 
   :max: <other max>  
   :sc: <etc> 
   :pd: <etc> 

[weefuzzy]

That might even be enough to tip me into writing One Proper Thing to convert docutils field_lists into something nicer to deal with

[jamesb93]

That looks better but will probably time drain for me to figure out compared to you. On the flip side I didn't intend to put more work on your head...

[tedmoore]

I think my discomfort is about hard-coding top level keys that mention specific CCEs, but maybe I should get over it.

One possibility (which would require slightly more elaborate python)

:seealso: 
   :flucoma: <fluid object name templates that will get transformed, and linked to> 
   :max: <other max>  
   :sc: <etc> 
   :pd: <etc> 

This seems fine to me. However, I think I might prefer without the "sub" object keys like this. The reason being that in the future if someone that is not in on this conversation creates a new object or whatever and is making a help file, having to navigate multiple levels of keys and possibly be wading through the python to see how things are parsed, etc., that seems like a hassle. IMO the more one-to-one that the RST and the outputs can be the better.

For the same reason, removing the hyphens makes sense to me. That way eyeballing the RST and the outputs makes it clear and doesn't inspire some python diving when it isn't necessary.