Board index FlightGear Development Documentation

Short Reference

Discussion of the FlightGear documentation, how it can be improved and coordination of people working on it.

Short Reference

Postby Richie2154 » Fri Feb 12, 2016 11:56 pm

I've made the current short reference guide look a little bit nicer in word.
Word version: https://mega.nz/#!oVBzmB5S!VqiR02TM0r3T ... zesJq-Mzgg
PDF version: https://mega.nz/#!UIQj0Y6B!lomCsaUcXiJe ... U3NzHq-J4g
Richie2154
 
Posts: 1
Joined: Fri Feb 12, 2016 11:43 pm

Re: Short Reference

Postby Hooray » Sat Feb 13, 2016 12:36 pm

most FlightGear PDF files must be considered "binaries", i.e. files that are automatically compiled from source text (usually Tex/LaTex), which means that editing the binary file is usually not the preferred method, i.e. it is generally recommended to edit the underlying source files - keep in mind that the release process is currently being revamped to become largely automated, which means that more and more tools will be regularly re-run to produce updated binaries, including not just executable files, but also documentation.

In fact, given the currently discussed scheme to change default airports for each upcoming release and name the release accordingly, it is highly likely that FlightGear documentation will become increasingly parameterized, i.e. so that it can be customized in a scripted fashion to change otherwise "hard-coded" assumption such as the default aircraft, airport, location etc.
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 12707
Joined: Tue Mar 25, 2008 9:40 am
Pronouns: THOU

Re: Short Reference

Postby stuart » Sun Feb 14, 2016 10:13 pm

Hi Richie2154,

Thanks for taking the time to improve this. I maintain the documentation, and it's always great to see someone taking an interest :).

As Hooray points out, the pdf file is (auto-)generated from separate source files. However, I'm sure we can add the same changes you made to the source files.

Looking at your version side-to-side with the current version, I think the main change is that you've made the table headings and keys bold to make them more readable. Are there any other changes you've made?

Thanks,

-Stuart

PS: OT: 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.
G-MWLX
User avatar
stuart
Moderator
 
Posts: 1629
Joined: Wed Nov 29, 2006 10:56 am
Location: Edinburgh
Callsign: G-MWLX

Re: Short Reference

Postby Hooray » Wed Feb 17, 2016 7:55 pm

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
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 12707
Joined: Tue Mar 25, 2008 9:40 am
Pronouns: THOU


Return to Documentation

Who is online

Users browsing this forum: No registered users and 5 guests