n72.75
Move slow and try not to break too much.
Orbiter Contributor
Addon Developer
Tutorial Publisher
Donator
- Joined
- Mar 21, 2008
- Messages
- 2,699
- Reaction score
- 1,361
- Points
- 128
- Location
- Saco, ME
- Website
- mwhume.space
- Preferred Pronouns
- he/him
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.
Code:
\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