Update/add to documentation for controls

[readyready15728]

Took me a little to remember that I can view my current contracts by pressing F5 twice. That (and the primary function of F5) isn't mentioned here:

https://wiki.alioth.net/index.php/Oolit ... d_Controls

There is a reference sheet on GitHub which does mention this but it's stamped with "Outdated":

https://github.com/OoliteProject/oolite ... liteRS.pdf

I'd like to do more than complain at some point BTW. I don't know any Objective-C but I guess documentation could be a start.

[Cholmondely]

A year and a half ago, Phkb produced a new OoliteRS.pdf which he asked for help editing. There have been more changes to v.1.91 since October 2023, so he may well have something for you to help with.

Here's the PDF's of the most recent update I've made to the docs:
OoliteRS.pdf
OoliteReadMe.pdf

[another_commander]

Only the PDF Reference Sheet is outdated. The .odt (LibreOffice) source Reference Sheet file found in the same Doc folder on github is fully up to date.

[hiran]

Only the PDF Reference Sheet is outdated. The .odt (LibreOffice) source Reference Sheet file found in the same Doc folder on github is fully up to date.

Plus the odt document is bundled into future releases - if there are any.
The PDF version is there solely because not having it breaks the build.

[another_commander]

Plus the odt document is bundled into future releases - if there are any.

Actually, just checked and this is not the case. The current pre-release installers contain the outdated PDFs instead of the current ones.

[hiran]

Plus the odt document is bundled into future releases - if there are any.

Actually, just checked and this is not the case. The current pre-release installers contain the outdated PDFs instead of the current ones.

That is unexpected.

Here is the line that generates fresh PDFs based on the .odt:
https://github.com/OoliteProject/oolite ... ll.yml#L49

And here the generated PDF is injected into the build of the installer:
https://github.com/OoliteProject/oolite ... l.yml#L163

Did you build the installer you are referring to locally? I faintly remember when I removed the outdated PDFs the local builds would fail. The commit history states so...
https://github.com/OoliteProject/oolite ... 003c98d688

[another_commander]

No, I downloaded from GitHub.

[hiran]

No, I downloaded from GitHub.

Interesting. When I get to it I'll take a look. May need your support as I don't do Windows...

[another_commander]

Why not just revert to using the actual PDFs in the source tree instead of outdated dummy ones? Here is some justification:

1. If the PDFs are needed to complete local installer builds, might as well use the actual correct ones there. I note that release builds of the game should always be manually made because we need to be able to test / virus scan the binaries before publishing. This elevates the importance of manual builds and the importance of ensuring that the correct files - no dummy ones - are present.
2. If people look at the github source tree for those PDFs as has recently been the case, it would be best if they found the actual correct ones there rather than outdated dummy ones.
3. The PDFs we pack with the game are changed once every two or three years. It is really, really easy for anyone making changes to the .odt files to just run a conversion to PDF and commit the PDFs too at the same time. After all, this was how we were doing it in the past and never had a problem with it, not even once. The PDFs can be double-checked just before any release (and they should be checked as part of the release process anyway) and even if found outdated, they could be recreated just prior to release.
4. Removing the conversion to PDF from the github build script would simplify it and help it run faster.

[hiran]

Now this is strange. When the documentation is built (that means the PDFs are generated), there is an artifact called oolite-doc.zip. That one contains the correct files. Then this artifact gets downloaded and extracted. During extraction I see this log output:

Code: Select all

2025-05-05T00:01:54.9016942Z ##[group]Run unzip -u artifacts/oolite-doc.zip
2025-05-05T00:01:54.9017348Z [36;1munzip -u artifacts/oolite-doc.zip[0m
2025-05-05T00:01:54.9050987Z shell: C:\Program Files\PowerShell\7\pwsh.EXE -command ". '{0}'"
2025-05-05T00:01:54.9051313Z ##[endgroup]
2025-05-05T00:01:55.5482960Z Archive:  artifacts/oolite-doc.zip
2025-05-05T00:01:55.5500309Z  extracting: oolite/Doc/OOLITE_VERSION.txt  

That's it? Where are the PDFs?

Now checking the Linux build. It has similar output:

Code: Select all

2025-05-05T00:01:16.7026417Z Download artifact has finished successfully
2025-05-05T00:01:16.7121387Z ##[group]Run unzip -u artifacts/oolite-doc.zip
2025-05-05T00:01:16.7121745Z [36;1munzip -u artifacts/oolite-doc.zip[0m
2025-05-05T00:01:16.7169585Z shell: /usr/bin/bash -e {0}
2025-05-05T00:01:16.7169819Z ##[endgroup]
2025-05-05T00:01:16.7254030Z Archive:  artifacts/oolite-doc.zip
2025-05-05T00:01:16.7255092Z  extracting: oolite/Doc/OOLITE_VERSION.txt  

Hmmm. Is there only one file in the archive? Let's check how that is getting created:

Code: Select all

2025-05-05T00:00:10.6660248Z ##[group]Run find oolite/Doc -name "*.odt" -exec soffice --headless --convert-to pdf:"writer_pdf_Export" --outdir oolite/Doc {} \;
2025-05-05T00:00:10.6661051Z [36;1mfind oolite/Doc -name "*.odt" -exec soffice --headless --convert-to pdf:"writer_pdf_Export" --outdir oolite/Doc {} \;[0m
2025-05-05T00:00:10.6661638Z [36;1mzip oolite-doc.zip oolite/Doc/*.pdf oolite/Doc/OOLITE_VERSION.txt[0m
2025-05-05T00:00:10.6710122Z shell: /usr/bin/bash -e {0}
2025-05-05T00:00:10.6710354Z ##[endgroup]
2025-05-05T00:00:12.3792516Z convert /home/runner/work/oolite/oolite/oolite/Doc/OoliteRS.odt -> /home/runner/work/oolite/oolite/oolite/Doc/OoliteRS.pdf using filter : writer_pdf_Export
2025-05-05T00:00:12.3794199Z Overwriting: /home/runner/work/oolite/oolite/oolite/Doc/OoliteRS.pdf
2025-05-05T00:00:14.9934125Z convert /home/runner/work/oolite/oolite/oolite/Doc/AdviceForNewCommanders.odt -> /home/runner/work/oolite/oolite/oolite/Doc/AdviceForNewCommanders.pdf using filter : writer_pdf_Export
2025-05-05T00:00:14.9935548Z Overwriting: /home/runner/work/oolite/oolite/oolite/Doc/AdviceForNewCommanders.pdf
2025-05-05T00:00:16.5854121Z convert /home/runner/work/oolite/oolite/oolite/Doc/OoliteReadMe.odt -> /home/runner/work/oolite/oolite/oolite/Doc/OoliteReadMe.pdf using filter : writer_pdf_Export
2025-05-05T00:00:16.5855941Z Overwriting: /home/runner/work/oolite/oolite/oolite/Doc/OoliteReadMe.pdf
2025-05-05T00:00:17.0591008Z   adding: oolite/Doc/AdviceForNewCommanders.pdf (deflated 8%)
2025-05-05T00:00:17.0877430Z   adding: oolite/Doc/OoliteRS.pdf (deflated 9%)
2025-05-05T00:00:17.0949247Z   adding: oolite/Doc/OoliteReadMe.pdf (deflated 5%)
2025-05-05T00:00:17.0949928Z   adding: oolite/Doc/OOLITE_VERSION.txt (stored 0%)

That log output is looking good either. So I went back and checked the artifact again. And again I can see the intended files.

Can anyone spot the error that I fail to see?

[another_commander]

Maybe after the PDFs are created the installer script that runs to do the final packaging overwrites them with the wrong ones by just doing a blind copy of the Doc folder? Seems like a logical explanation, maybe worth checking it out.

[hiran]

Seems like I found the culprit!

The extract command would only extract newer or non-existing files (the -u option).
I switched to -v -o and have this output in a test branch:

Code: Select all

Run unzip -v -o artifacts/oolite-doc.zip
Archive:  artifacts/oolite-doc.zip
 Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
--------  ------  ------- ---- ---------- ----- --------  ----
  687248  Defl:N   635195   8% 2025-05-06 20:15 f7f8fb32  oolite/Doc/AdviceForNewCommanders.pdf
 1024112  Defl:N   934324   9% 2025-05-06 20:15 ac0c645d  oolite/Doc/OoliteRS.pdf
  261928  Defl:N   248402   5% 2025-05-06 20:15 5b03a6b2  oolite/Doc/OoliteReadMe.pdf
      42  Stored       42   0% 2025-05-06 20:14 09e350f1  oolite/Doc/OOLITE_VERSION.txt
--------          -------  ---                            -------
 1973330          1817963   8%                            4 files
 

But apparently the -v option prevents extraction completely.

[hiran]

Code: Select all

Run unzip -o artifacts/oolite-doc.zip
Archive:  artifacts/oolite-doc.zip
  inflating: oolite/Doc/AdviceForNewCommanders.pdf  
  inflating: oolite/Doc/OoliteRS.pdf  
  inflating: oolite/Doc/OoliteReadMe.pdf  
 extracting: oolite/Doc/OOLITE_VERSION.txt  
 

Verified: The Linux artifacts do contain the generated files.

Plus I know how we ended up here. It is an unfortunate chain of events. Nevertheless it's fixed now.

Could someone please check whether Windows artifacts are ok as well?

[another_commander]

Could someone please check whether Windows artifacts are ok as well?

Confirmed, the correct PDFs are now packaged with the Windows installer too.

In case it can be of help in the future, the Windows installer executables are accessible as LZMA archives by 7-zip. At least on Windows, I can open them inside 7-zip and extract any part of their contents without actually running the installer. It should be possible to do the same on Linux.

[hiran]

Confirmed, the correct PDFs are now packaged with the Windows installer too.

In case it can be of help in the future, the Windows installer executables are accessible as LZMA archives by 7-zip. At least on Windows, I can open them inside 7-zip and extract any part of their contents without actually running the installer. It should be possible to do the same on Linux.

Thanks for checking.
And I wasn't aware the installer can be treated as archive. Good to know.