stuart wrote in Sun Feb 14, 2016 10:13 pm:Hooray - I'm not aware of any intention or indeed work to make the main manual parametrized. I think it's much more likely that we'll just include instructions to enable Terrasync before doing any of the tutorials.
It was a discussion that took place behind the scenes between some of us in response to the new airport/scenery-focused versioning scheme that was suggested a while ago on the devel list - a few people mentioned potential challenges, such as hard-coded assumptions in tutorials and/or checklists or scripts (think AI tanker) - but also in the manual, so we started tinkering...
Thus, we discussed the possibility to identify such hard-coded assumptions and replace them with running a shell script/wrapper to obtain such information from a separate program (possibly even fgfs, e.g. via telnet/props), because the other challenge are all the outdated screenshots - many of which could be trivially re-created by encoding the relevant/surrounding parameters (location, aircraft, time of day, environment - aka fgfsrc & preferences.xml) - at which point it would be possible to run fgfs to update screenshots when compiling the LaTex sources.
We didn't discuss any of this in public because it's really just a brainstorming at this stage - but it would obviously help provide more up to date documentation, i.e. on the basis of having to encode the relevant parameters/settings for the screenshots in question, and calling a shell script to invoke fgfs with the corresponding fgfsrc/preferences.xml - which would then make it possible to write out screenshots to a configurable directory so that they can be included.
Note that this would also be an elegant way to show localized FG screenshots in different languages - for the time being, updating screenshots is a highly manual process - despite many things having changed "recently" (think menu items that got moved/renamed, dialogs that have changed etc)
Under the hood, most of the APIs/functionality is already there in various shapes and forms:
- fgfsrc, preferences.xml and the --config= argument for recreating startup settings
- fgcommands for taking screenshots
- the telnet/props and httpd/mongoose interfaces for serving screenshots
- the output directory/filenames for screenshots can be customized
Obviously, the main cost would be that of running fgfs to recreate screen shots while the LaTex compilation takes place (or shortly before).
The good thing is such a scheme would make it possible to "build" the manual directly on the jenkins build server, i.e. as part of the increasingly automated build/release process that Torsten is aiming for
Like I said, it's mainly a brainstorming for now - but not that far-fetched: we can already include external files in LaTex, and we can also include LaTex source by running an external program - at that point, we can basically run a wrapper that loads fgfs with a custom preferences.xml file and telnets/netcats into fgfs (or using TorstenD's mongoose work) to obtain a screen shot
Either way it would be a good idea to add a disclaimer to the PDF files that these are created automatically from LaTex source and that they should not be edited manually