SUG 9.2: inconsistencies with index.json common_name(s) field

[xLPMG]

I have been reading through the SUG to understand the structure of sky culture data, especially the common_name/common_names field. I have noticed some inconsistencies that I think should be addressed:

SUG 9.2.4: Constellation -> common_name

• missing field translators_comments (9.2.7 has it), generate-pot.py uses it
• index.json (ex. arabic_arabian_peninsula) uses references but this is neither documented nor read by Constellations.cpp
• Constellations.cpp and generate-pot.py use context but this is not documented

SUG 9.2.5: Asterisms -> common_name

• missing field translators_comments (9.2.7 has it), generate-pot.py uses it
• Bug: SUG mentions references in common_name, but Asterisms.cpp tries to read data["references"] instead of data["common_name"]["references"]
• unlike Constellations, Asterisms.cpp does not use context, but generate-pot.py does, but the field is not documented in the SUG

SUG 9.2.7: Sky Culture -> common_names (Names of Stars, Planets and Nonstellar Objects)

• SUG says translator_comments, index.jsons use translators_comments (with an extra "s")
• the function process_names in generate-pot.py uses context in common_names, but this is not documented in the SUG

These are just examples of what I have found so far. I will edit this issue if I find more.
I suppose a solution would be to introduce a single section in the SUG that defines the structure of common_name/common_names, including all the fields and thus serving as a "single source of truth" so its easier to update and maintain.

[gzotti]

Thanks, some of these pesky details are probably still not complete.

The translator(s)_comments are not used in the program, but should help adding additional context for translators working on Transifex without necessarily seeing the place in the program where it's used. But agreed, should be translators_comments everywhere, and is optional.

On "Context", I cannot even say, @10110111 , @alex-w do we need to fill context everywhere in index.json, or could generate-pot.py add context entries (just the SC name?)? (And how many do exist now and are used - does a change mean retransifexing what feels like ~8000 name entries yet once more?)

On references vs common_name/references: For Asterisms and star names, I have implemented a "reference exclusion" so that if you don't like the asterisms or also star names from ref."X", those entries which only have "X" in their reference list are not used. (e.g. this internal ~1970 NASA memorandum which brings star name duplicates with Roman numerals. IMO nobody outside NASA/JPL has ever used them, so I don't like to see them usually. Same goes for tertiary textbooks that just brought misprinted names.)

The structure of the "common_name" dict inside Constellation and Asterism should probably be identical, and an L2 section "Asterisms" added to description.md. The skyculture/common_names section is IMO different by design, buy yes, the role of "context" is not really documented and may still have inconsistencies.

[github-actions]

Thank you for suggesting documentation improvement.

[alex-w]

Context maybe really helpful for star names, because same English name may have different translation in some languages (we have a few bug reports for this case)