Orbiter 2024 Launch readiness

[n72.75]

That is the doxygen-generated pdf, and that should "just" be pointing doxygen to the source files (easy), and have the code documented (not easy).

AFAIK we have only added a few new API functions. I know the one I added has doxygen code for document generation. There are a few older API functions (pre-open source) that are missing documentation, so that should be looked through.

They all do.
My idea is to combine "3DModel.pdf", "API_Guide.pdf", and (parts of) "Orbiter2DGraphics.pdf" into a single pdf called, e.g., "Orbiter Developer Manual", which would have all the info needed (except for the function list, which would remain in "API_Reference.pdf") for a developer to create an addon. Currently this document would have ~130 pages, and even with some additions, plus a chapter for lua (I see lots of activity in there, so there should also be some pen put to paper), IMO it would still end up with a manageable size.

After a bit more thinking, it's probably better to have 3 docs:

• "Orbiter User Manual" which would cover basics, included MFDs and vessels, etc, and it should end up having less than 200 pages, so still manageable;
• "Orbiter Developer Manual" described above;
• "Orbiter Technical Reference" with the stuff in the Technotes folder plus some some equations and constants that are currently spread in other docs, basically serving as a reference of how Orbiter works.

I like this idea. That sounds like a much better way to organize the documentation. Unless anyone has a strong objection, let's just move ahead with this.

A possible implementation for the "code block" is already provided in my demo above.
Again, the first thing to do should be define styles and such, so there is a common base for the docs. Then, IMO, a 2-step process is probably easier to handle: first a "conversion phase", when the current docs are converted to LaTeX, split into source files and combined into the final product with +/- the final structure, and then a "correction phase", when the updates and corrections are made, already having the overall final product in view.
LaTex supports comments, so TODOs can be added during the conversion phase, as early signals that some area needs work. This approach allows us to isolate the "LaTeX problems" from the "documentation problems": when checking and correcting the text we'll easily fire up Orbiter to confirm something and find something not working properly, and battling that and LaTeX at the same time would not be good.

Somehow I had missed your demo documentation, and I started on one of my own. Thankfully not too much though. I was using minted for highlighting code. Maybe we could stick those in your code boxes, with a light grey background, or just in some kind of box? I'm also using tcolorbox for any "Alert", so that it stands out.

\newcommand{\alertbox}[1]{\begin{tcolorbox}[colback=red!5!white,colframe=red!75!black,title=Alert]#1\end{tcolorbox}}

Also to consider is where do the files go?
Does the "Orbiter Developer Manual" remain in the Orbitersdk/doc folder, or does it join the other in the Doc folder?
Do the sources stay inside Doc (and Orbitersdk/doc), or do they go in the Src folder, and only the pdf products end up in the Doc folder?
In any case, each pdf product should have its own folder with the .tex sources and an images folder... for the images (duh).

IMO These should all go under /orbiter/doc. Having the Orbiter and OrbiterSDK documentation separated in to different directories is a holdover from the Orbiter 2006 and prior, days where the OrbiterSDK was a separate download.


So my question on this now becomes: how can I help? I'd rather not duplicate efforts and it seems like you have a good head-start on me

 

[Buck Rogers]

Impressive array of settings (appreciate the reset buttons), atmospheres are beautiful.
Post Pro. Conf. not working, unsure whether bug or user error, does it make sense to start a "OpenOrbiter2024 Testphase User Issues" thread, or discuss further here?

 

[Thunder Chicken]

As I am one of the resident Lua rabble-rousers, how is Lua being documented? Is that piggybacking off of the C++ API documentation, or does that need to be a separate thing?

 

[n72.75]

Impressive array of settings (appreciate the reset buttons), atmospheres are beautiful.
Post Pro. Conf. not working, unsure whether bug or user error, does it make sense to start a "OpenOrbiter2024 Testphase User Issues" thread, or discuss further here?

That probably makes the most sense. Threads are free. Once we identify something as an actual bug/issue, it should get added to the github issues with the appropriate tags.

As I am one of the resident Lua rabble-rousers, how is Lua being documented? Is that piggybacking off of the C++ API documentation, or does that need to be a separate thing?

I think as @GLS mentioned, this should probably be part of the "Orbiter Developer Manual". Have you and @Gondos and others working on Lua, if I'm forgetting, created any documentation so far?

 

[Gondos]

I think as @GLS mentioned, this should probably be part of the "Orbiter Developer Manual". Have you and @Gondos and others working on Lua, if I'm forgetting, created any documentation so far?

There is a Lua scripting manual in Html/Main/Script, it's in html with cmake rules to turn it into a chm file.
As far I can tell, it's manually updated by copy/pasting stuff from OrbiterAPI.h and co. when we map new functions from C++ to Lua.

 

[GLS]

Somehow I had missed your demo documentation, and I started on one of my own. Thankfully not too much though. I was using minted for highlighting code. Maybe we could stick those in your code boxes, with a light grey background, or just in some kind of box? I'm also using tcolorbox for any "Alert", so that it stands out.

\newcommand{\alertbox}[1]{\begin{tcolorbox}[colback=red!5!white,colframe=red!75!black,title=Alert]#1\end{tcolorbox}}

I just tried to emulate the existing look of the code box, and the listings package was the first thing that showed up, and it worked.
I skipped the alert box for my demo, but it should be a similar implementation to the code.

IMO These should all go under /orbiter/doc. Having the Orbiter and OrbiterSDK documentation separated in to different directories is a holdover from the Orbiter 2006 and prior, days where the OrbiterSDK was a separate download.

So my question on this now becomes: how can I help? I'd rather not duplicate efforts and it seems like you have a good head-start on me

So far I just made that demo and thought about the document structure I posted above.
If that 3-file structure is to be adopted, then 3 people can work concurrently in the conversion part. There could be more, as each document should have one source per chapter, so several files = absolutely no conflicts, but this part should be easy enough to be handled by one person per document, plus I'm sure there will be no stampede to write documentation.
Once that is done, and corrections begin, maybe have a ticket so the sources can be listed, assigned without conflict and then ticked off once work is done.
For a timeline, maybe we can wait until Monday or so, to let people read theses posts and think a bit.

 

[Thunder Chicken]

I think as @GLS mentioned, this should probably be part of the "Orbiter Developer Manual". Have you and @Gondos and others working on Lua, if I'm forgetting, created any documentation so far?

Not me, anyway. Frankly it's been a whirlwind of change and I'm not quite sure where the documentation is or where it lives or what I can do to help with it. I have been using the Orbiter 2016 Help dialog for Lua but that is pretty much out of date now.

 

[GLS]

I guess we could treat this as a wedding, and as there are no objections, we can proceed with the LaTeX solution.

First we need to define the general layout of the document, styles for all the boxes, headers and/or footers, and cover.
My ideas, for discussion:
General layout, keeping in line with the existing simple layout:
- cover, with logo, title and maybe date and/or version info
<new page>
- full index
<new page>
- chapter 1...
<new page>...
- chapter 2...

Same font as now (if possible, I haven't checked which one it is), used everywhere, except for the code blocks which would use Courier New, or some other monospace font.

Footer with document title and page, again keeping the existing design.

Chapter headings is were I'd move away from the existing design (blue box) and use just the chapter name and number. Starting a chapter in a new page should provide enough separation between chapters.

For the boxes, the Alert box @n72.75 posted looks nice, and could also be used in yellow or even green for a "simple" warning or an advise, and does away with the icon on the side of the text on the existing docs. For the code, I managed to replicate the existing code box, which IMO still looks good.



Switching to another issue, what to do about .chm files, that show in-sim help?


Also, maybe this documentation talk should move to https://www.orbiter-forum.com/threads/building-openorbiter-documentation.41542, and leave this thread for a higher level discussion?

 

[GLS]

Started a PR and 2 tickets (1, 2) for the documentation work. I've setup the basic document structure (but I just realized that I've used the 2016 pdf as source instead of the existing odt ), but some there is still some base work left: setting up the font, adding an Orbiter logo to the cover, and adding the warning and code boxes.

 

[GLS]

Current documentation results:

Documentation rework - part 1: Setup and conversion · Issue #439 · orbitersim/orbiter

The first of a pair of tickets for tracking (1) the conversion of the existing documentation to LaTeX and then (2) updating and correcting the new documentation, solving the existing documentation ...

github.com

Defining the font is the next main target, and also figure out how to add equations (cheaper in terms of disk space and more flexible than the current images of equations), before then gearing up the conversion to "industrial" levels.

 

[GLS]

So I hit a wall with the font definition... If anyone knows how to (reliably) define fonts in LaTeX, your knowledge is required. It should be "in-line" with the original, and easily available.
Then, I hit a really big wall: the original idea for Orbiter Technical Reference, i.e., merge the Technotes papers, won't work as LaTeX can't merge docs of different types. A (IMO, not very good) way around this is to have LaTeX merge the paper pdfs instead of the sources. The alternative is to go into the paper sources and edit the "paper style" out of them, which also isn't a good idea IMO, as I think the original style should be preserved as much as possible (a paper is more "official" than a "simple" manual).

Meanwhile, I've added a few equations to the Orbiter Developer Manual, so the math is working (no surprise there, just checking that box).

I guess I'll step up the conversion, as the foundations seem +/- solid, and at the moment I can't advance on the 2 issues above. I'll start with the Orbiter Developer Manual.

 

[Thunder Chicken]

So I hit a wall with the font definition... If anyone knows how to (reliably) define fonts in LaTeX, your knowledge is required. It should be "in-line" with the original, and easily available.
Then, I hit a really big wall: the original idea for Orbiter Technical Reference, i.e., merge the Technotes papers, won't work as LaTeX can't merge docs of different types. A (IMO, not very good) way around this is to have LaTeX merge the paper pdfs instead of the sources. The alternative is to go into the paper sources and edit the "paper style" out of them, which also isn't a good idea IMO, as I think the original style should be preserved as much as possible (a paper is more "official" than a "simple" manual).

Meanwhile, I've added a few equations to the Orbiter Developer Manual, so the math is working (no surprise there, just checking that box).

I guess I'll step up the conversion, as the foundations seem +/- solid, and at the moment I can't advance on the 2 issues above. I'll start with the Orbiter Developer Manual.

Haven't worked with Latex in a while, but does this help?

How Fonts Work in LaTeX? | Baeldung on Computer Science

Learn how to change the font of a LaTeX document to meet your needs.

www.baeldung.com

 

[n72.75]

So I hit a wall with the font definition... If anyone knows how to (reliably) define fonts in LaTeX, your knowledge is required. It should be "in-line" with the original, and easily available.
Then, I hit a really big wall: the original idea for Orbiter Technical Reference, i.e., merge the Technotes papers, won't work as LaTeX can't merge docs of different types. A (IMO, not very good) way around this is to have LaTeX merge the paper pdfs instead of the sources. The alternative is to go into the paper sources and edit the "paper style" out of them, which also isn't a good idea IMO, as I think the original style should be preserved as much as possible (a paper is more "official" than a "simple" manual).

Meanwhile, I've added a few equations to the Orbiter Developer Manual, so the math is working (no surprise there, just checking that box).

I guess I'll step up the conversion, as the foundations seem +/- solid, and at the moment I can't advance on the 2 issues above. I'll start with the Orbiter Developer Manual.

I would think the default [imath]\LaTeX[/imath] "Computer Modern" font would be acceptable, no? Is there a specific need for a particular font?

The commands for changing font family are: \rmfamily \sffamily \ttfamily

As far as the technotes. Since we're making a new document, let's just make the contents of the old technotes {sub}sections in the new document. That'll work a lot better with the document structure/ToC/etc. Maybe the book or report classes would be better for this? I think we can probably keep the styling similar to the origionals.

If this is an absolute no-go, you could generate the pdfs with pdfLaTeX and include them in some kind of meta-document with https://ctan.org/pkg/pdfpages?lang=en[/sub]

 

[GLS]

As far as the technotes. Since we're making a new document, let's just make the contents of the old technotes {sub}sections in the new document. That'll work a lot better with the document structure/ToC/etc. Maybe the book or report classes would be better for this? I think we can probably keep the styling similar to the origionals.

If this is an absolute no-go, you could generate the pdfs with pdfLaTeX and include them in some kind of meta-document with https://ctan.org/pkg/pdfpages?lang=en[/sub]

Yes, if there are no other issues, transplanting the paper contents into chapters is the easier solution. I was hoping to not have to edit anything, but the alternatives are not that great.


As for the font, yeah it can be the default... I was just trying to keep the original. So far the characters (plus code and math) are all showing up without issues, so maybe the font can be left as is (have to check if it currently is Helvetica or Computer Modern).


Small progress update: work is progressing fine, with the occasional "LaTeX hickup". Only having to worry about the LaTeX issues now and leaving the content rework for later is paying off.

 

[jarmonik]

What about the Debug Libs ?

Should we have:
Orbiterd.lib
OrbiterSDKd.lib
Lua/Luad.lib
...

Or would it be better:
Debug/Orbiter.lib
Debug/OrbiterSDK.lib
Debug/Lua/Lua.lib
...

The later wouldn't require renaming the libs and build tools might handle the sub directory easier.

 

[jarmonik]

What about the documentation ? Right now the GitHub doesn't build Doxygen nor LaTeX sources. Of course, we can build the documentation manually/locally and then commit the pre-build docs to a repository.

 

[GLS]

What about the Debug Libs ?

Should we have:
Orbiterd.lib
OrbiterSDKd.lib
Lua/Luad.lib
...

Or would it be better:
Debug/Orbiter.lib
Debug/OrbiterSDK.lib
Debug/Lua/Lua.lib
...

The later wouldn't require renaming the libs and build tools might handle the sub directory easier.

"<name>d.lib" is the usual solution, but if the Debug folder is easier to implement, it works for me.

What about the documentation ? Right now the GitHub doesn't build Doxygen nor LaTeX sources. Of course, we can build the documentation manually/locally and then commit the pre-build docs to a repository.

I think the "main" releases should be manually built and the zip uploaded. Uploading the pdfs IMO is not a good idea, as they are binary files: any documentation change will mean pretty much a new pdf file(s), and that will eat server space.
The "automatic github" releases would contain no documentation, but the previous "main" release will have, so there will always be some documentation available.

BTW, I'm still working as fast as I can in the conversion of the documentation.

 

[jarmonik]

I tried to build the "Orbiter Developer Manual" you have been working on and there was a problem with font "NotoSansMono" I found it from the internet but refused to work. I changed it to "Tahoma" and the document build worked. Would it be possible to tell LaTeX to avoid page breaks inside text boxes like code examples. Also the boxes having white text on grey background are little hard to read.

 

[n72.75]

What is everyone using for a [imath]\LaTeX[/imath] package manager? I would think we'd want to pick packages that can just auto download.

 

[GLS]

I tried to build the "Orbiter Developer Manual" you have been working on and there was a problem with font "NotoSansMono" I found it from the internet but refused to work. I changed it to "Tahoma" and the document build worked.

I was going (back) to the fonts when I finished converting the ODM, which should be soon. The font was downloaded automatically (see below).

Would it be possible to tell LaTeX to avoid page breaks inside text boxes like code examples.

Hmm, do you mean having the code box only in one page, as opposed to having part on one page and the other part on another page?

Also the boxes having white text on grey background are little hard to read.

Initially I had black text on gray background...

What is everyone using for a [imath]\LaTeX[/imath] package manager? I would think we'd want to pick packages that can just auto download.

Texworks and MiKTex here. I'm pretty sure everything was downloaded automatically (I only had to confirm on a popup).