Description (modules)

[sushoff]

I would like the "description.md" to be built automatically with sky culture makers then arranging the input fields in always the same way. For the standard structure, I think:

• [ ] Licence and Author name have to be put directly below the headline for immediate recognition (like in research papers); this would also give the description a more "professional" appearance
• [ ] Then "description of the culture" (where it is on Earth, what's special about it etc.)
• [ ] then, "description of the sky of this culture", e.g. list of constellations, notes on features like zodiac division etc. ...
• [ ] then, of course the formal things (as it is now): reference, classification, region

@gzotti @10110111

[gzotti]

The structure is given in SUG 9.1 and is IIRC mandatory for allowing successful translation.

Sorry, but I disagree about author placement on screen. For our software users (i.e. 100% - 50 SC researchers), the author names are very uninteresting, and placing them at the end is OK. Same goes for license. Who wants to start reading a text that tells you what you can do with it? It may be relevant for the SCM to require them from the start, so that authors are aware of this CC license necessity.

We can be a bit more clear what should go under "Description", indeed, but I assumed the existing examples can provide guidance. The authors are free to define subsections within this section, and it may not really be possible to catch all expected possibilities between interpreting paleolithic cave art and modern Kindergarten dabblings. Basically, I would expect geolocation, ethnical/population info, living or past culture, language, economy, etc., then an intro about the science or use of astronomy/skywatching of this culture. Constellation metainfo should also go there. SCM can help authors by defining a series of optional subsection headers, but basically everybody can later use a plaintext editor to make further extensions or subsections, or modify the sequence of sections.

The detailed constellation info (without introduction) must be listed in section Constellations.

There is no section Asterisms yet. Although the separation between constellations and asterisms as defined by use during the 20th century after IAU declared their 88 probably is only relevant in Modern_* SCs, we have found earlier that we can use Asterisms for specialized things like highlighting the lunar station asterisms. A dedicated but optional L2 section may be useful, with a similarly structured sequence of level 5 Markdown sections. @10110111 would S-M simply ignore such section, or are "rogue L2 sections" a problem (S-M, translations, ..?)

In the end, SCM should test for the existence of the required level2 sections (and sequence) and make sure there are also no rogue level2 entries if they are a problem.

[github-actions[bot]]

Thank you for suggesting documentation improvement.

[10110111]

would S-M simply ignore such section, or are "rogue L2 sections" a problem (S-M, translations, ..?)

S-M will not be too happy but will work, and stellarium-skycultures (its update_po.py script) will give an error, as will Stellarium's generate-pot.py.

But this looks fixable, and generally it seems that, since we have asterisms as entities very similar to constellations, they should also have the corresponding section in the description.

[10110111]

For our software users (i.e. 100% - 50 SC researchers), the author names are very uninteresting, and placing them at the end is OK. Same goes for license. Who wants to start reading a text that tells you what you can do with it?

Just wanted to write the same. The SC descriptions are not scientific papers, they are for giving some information on the topic first of all. Authors, classification, license etc. are the least interesting part of this.

[gzotti]

How do we solve this issue? It was a suggestion by @sushoff to rearrange sequence of sections which we dislike, but @10110111 we said we can add an optional "Asterisms" section to description.md which programs that are not interested could just ignore. This may probably be utilized in practice not before 26.1, though. So, do it now or postpone to 26.1?

[10110111]

This may probably be utilized in practice not before 26.1, though. So, do it now or postpone to 26.1?

No point in introducing so close to the release a feature that won't be used.