Astronomy glossary

[cosinekitty]

Create a document that explains astronomy terminology. Alphabetically sorted glossary. Allow deep linking from other documents.

• Observers
  • Heliocentric
  • Geocentric
  • Topocentric
• Coordinate systems
  • Equatorial
  • Ecliptic
  • Horizontal
• Different time scales (UT, TT).
  • UTC/UT1
  • Terrestrial Time
• Barycenters: SSB, EMB.
• Apsides: pericenter and apocenter.
• Equinox has two meanings:
  • A location on the Earth's orbit.
  • A time at which the Earth reaches the equinox point.
• (Search through documentation for all astronomy jargon.)

[matheo]

This could be live documentation in the demo-app rendering the differences between these terms with live examples :)

[cosinekitty]

That is an interesting idea. I need to get back to working on this part, since it has been sitting here idle for such a long time. My first goal will be to get something people can refer to here in GitHub Markdown pages. Having some diagrams and live animations to embed will be helpful, but GitHub does not allow custom JavaScript to render inside Markdown pages, for security reasons. But we can link to demos hosted on other sites.

[matheo]

I just saw that https://github.com/SEscobedo/AstraSolaris uses Netlify, I will check if there's a sponsorship for Open Source or if the quota is not exceeded to use it for free :)

Edit: Yes they do have a plan: https://www.netlify.com/legal/open-source-policy

[matheo]

Hi Don, I need an idea of how do you process the docs (for all the languages at once? or javascript has a special generator?) so with that I can get an idea of the possibilities.

• Do you generate the README for Javascript? or is it manual?
• The tool you use can be used to generate a JSON file with all the docs data?
• Do you think we should automate the docs website or have some kind of custom code?

[cosinekitty]

This is a complicated process, unfortunately. The original source code that I work on is in the directory generate/template/. You can see all 4 language source files there. This is where I do the original programming work. Then I have a custom code generator (generate/generate.c) that transforms these files into usable code.

If you look in generate/template/astronomy.js, you will see there are 12 places where $ASTRO_... occurs. The code generator replaces each one of these with various computed tables of numbers. This way all 4 languages have identical computed data; if I make a change to the mathematical models, it propagates to all of the source code.

After generating the source code comes the most frustrating part as a maintainer. There are several different documentation generators that build Markdown from the generated source code. This part is in the bash script generate/makedoc, which is in turn called by the build+test script generate/run. I had to cobble together completely different custom steps to make all supported languages have a reasonably consistent GitHub Markdown output. I even created my own translators for C# (csdown) and Python (pydown), because I could not get existing third-party tools to do what I want. For C, I use doxygen to generate XML, and I wrote my own tool (hydrogen) to convert that XML into Markdown.

For JavaScript, makedoc first generates all the source code, then minifies it with the Google Closure Compiler, then runs jsdoc2md on the un-minified version of the generated code.

One of the things that concerns me is, when I try to use the same versions of jsdoc2md and Google Closure Compiler, but on a more recent version of Linux (such as Arch Linux), I can't get either of them to produce the same output as what I have now, which totally breaks my build process. It's especially weird because I can't tell why the output is different, even though I'm explicitly using the same version of both tools. It's another reason I'm not very fond of the JavaScript development world... I don't know how to get reproducible results when the entire ecosystem undergoes weekly churn. It's also why I'm committed to not having Astronomy Engine itself (the final code, not the build process) have any dependencies on third-party libraries.

So the point of all this is, I will probably have to create yet another custom tool to replace jsdoc2md, because I can't seem to predict or control its output. In fact, I should probably do this while converting from JavaScript to TypeScript, or it will no doubt break the build process.

Anyway, sorry for the rant, but it is important to understand why changing things in this project can be more work than one expects at first.

[cosinekitty]

For clarity, I don't know what I'm going to do about the Google Closure Compiler issue. I'm open to ideas for how I can minify my code for client-side users and get the exact same output regardless of the host operating system. That would be a huge help if you know how to make it generate the same thing in (for example) both Debian Stretch 9.4 and the latest versions of Arch Linux. My Travis CI build runs the same code generator and document generators, and verifies that what is checked into git is the same as what it generates, or it fails the build.

[matheo]

I'd like to build some demos around the Glossary, I've reorganized the sections in this way to start that module with some understanding of the concepts/terms mentioned in this Issue:

We could have some text definition and some kind of animation next to it to reflect the concept in action, WDYT? :)

[cosinekitty]

Yes, I like the idea of providing diagrams and even animations where possible. Hopefully you can help with the artwork; that is the place where I am the weakest. The bullet points in this issue's description are a good starting point for the material to cover. I will go back and make a more complete list, but I think the biggest help for developers will be a clear explanation of coordinate systems and the difference between Universal Time (UT) and Terrestrial Time (TT). In general, there is a lot of ancient jargon in astronomy! Practical examples will help people a lot.

[SEscobedo]

@matheo I can help with animation you need, specially if you mean 3d animation. I have an open source project for this purpose in case you want to see it.

[matheo]

Sounds good @SEscobedo! thank you very much for the offer, I will message you right away

[cosinekitty]

@SEscobedo I looked at your website https://www.astrasolaris.org/ . The graphics for the planets are amazing! How do you do that?

[SEscobedo]

Thanks @cosinekitty. The graphics are made using three.js, I also tried to find the right textures and shaders to give the best possible effects. If you want to know anything about the code or the techniques, fell free to ask.

[jffaust]

This is a complicated process, unfortunately. The original source code that I work on is in the directory generate/template/. You can see all 4 language source files there. This is where I do the original programming work. Then I have a custom code generator (generate/generate.c) that transforms these files into usable code.

@cosinekitty Looks like a lot of manual work. Recently I discovered https://haxe.org/ which is "an open source high-level strictly-typed programming language with a fast optimizing cross-compiler". From a quick look, it seems to support all the languages that Astronomy Engine already support. Obviously it would be a lot of work to re-write the engine in Haxe, but then you'd no longer have to cross-compile manually. Not sure if it could help the documentation process though.

Thought you might want to take alook :eye:

[cosinekitty]

Recently I discovered https://haxe.org/ which is "an open source high-level strictly-typed programming language with a fast optimizing cross-compiler".

Haxe does look like an intriguing language. I definitely want to learn more about it.

If I were to use this for astronomy calculations, it would be for a complete overhaul as a separate project, while leaving Astronomy Engine as-is. I doubt it would be feasible to convert everything without breaking code that depends on the existing library.

However, the idea of a language designed for cross-compiling to other languages has a lot of appeal. I would strongly consider this for any future projects where I want to support multiple programming languages and/or platforms.