Board index FlightGear Development Documentation

Proposed change to the help menu

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

Proposed change to the help menu

Postby jdc843 » Wed May 08, 2013 10:26 am

Proposal:
Create a /Docs subdirectory for each aircraft containing detailed documentation specific to each aircraft.
AND/OR
Create help menu item(s) pointing to (1)the /Docs subdirectory and (2)each aircrafts' respective wiki page at wiki.flightgear.org


REASONING:
(Good luck understanding this. :) )

wiki.flightgear.org has a very impressive number of articles. But I can't find information quickly while running FlightGear. Such As: maximum takeoff & landings weights, speeds, cruising altitude, etc.
In my case, I didn't know that information was even on FlightGears' website to begin with. I still 'stumble' across information, discovering new documents. BTW, this is my prime reason for this proposal.

The 'Fuel and Payload' menu item doesn't currently perform checks to insure safe aircraft operation with what the 'pilot' selects. (Maybe some aircraft do this? Maybe eventually all will do so.)

Other information (speeds, altitudes) are not listed unless the developer places that information into the 'Aircraft help' menu item. Doing so would increase the size of the *-set.xml files. Unless a separate file is used that is included by a reference within the *-set.xml file (Is this even possible?).

'Documentation Browser' - brings up a list of README documents that cover FlightGear as a whole.
'Help' - does the same. But with file types other than the READMEs.
I ASSUME that these two commands will one day be combined into a single menu item ? Maybe not.

'Aircraft help' - brings up condensed key commands, procedures, HOWTOs, etc specific to each aircraft. Leave this alone. I like being able to QUICKLY find out what key to press that will apply thrust reversers if I forget how while landing. Displayed data can't be images, HTML formatted, etc (That I know of). Data is displayed in FlightGear itself.

Decided against placing these menu items under the aircraft specific menu. Aircraft help needs to stay under the help menu. This calls for the menu change to be made at the 'application' level. Similar to the 'Aircraft help (?)' menu item. Not to each aircraft. This method should/might also lessen the work load on each aircraft developer figuring out how to modify the menu more than they already do.

Add option to the help menu using the 'open-browser' command that points to the wiki pages for each aircraft.

Another link that points to help in each aircraft's /Docs directory. Wiki page could be lost or corrupted. Convenient access to information without requiring internet access. And not as easily corruptible.

How to transfer data from the wiki to the aircrafts' git repository ? Menu item and wiki. Duplication of information. Double the work to keep them the same. Same as now. (Unless the wiki and the git repositories can be linked?) Read in forums that developers don't like the wiki being so open to editing by many people. Make data transfer from wiki to git a manual operation by each aircrafts developer. This necessitates another link to the wiki for current information.

Including help for each aircraft will significantly increase the size of the 'standard' FlightGear package. Possible solution: Reduce the number of aircraft included in the 'standard' FlightGear package. Maybe have only the Cessna 172. Vote for the top 5 aircraft to include? Use website to download any other desired aircraft as now happens. Or have the help files as a separate package. And use an over-writable, by the docs package, /Doc directory that refers to online docs or the docs package.

References:
http://wiki.flightgear.org/Howto:Make_an_aircraft - determined that there isn't a /Docs sub-directory for each aircraft.
Other docs used to puzzle out how FlightGear works and if what I'm proposing is even doable.

*********************
Unless you are congressmen and I'm applying for a large government grant, I've edited this enough. I think that I've made this understandable and made my point.
jdc843
 
Posts: 4
Joined: Wed May 08, 2013 3:29 am
Callsign: 1085
Version: 2.10-git
OS: GNU/Linux

Re: Proposed change to the help menu

Postby Thorsten » Wed May 08, 2013 11:39 am

Create a /Docs subdirectory for each aircraft containing detailed documentation specific to each aircraft.


It's up to the aircraft developers. Some (notably Russian) aircraft come with 30+ pages of illustrated pdf reference documents. Some aircraft (like the Concorde) have been documented by users in great detail on the Wiki because the info shipped with the aircraft was too opaque. Some aircraft have detailed checklists in the specific help, some just barely document the keys. Some come with tutorials for the most important bits, others don't.

Even if we could agree on a standard (for instance, the novice user is better off with a tutorial, the advanced user would prefer a quick reference guide), there's no way to force aircraft developers to adhere to the standard - they have to do so voluntarily.
Thorsten
 
Posts: 12490
Joined: Mon Nov 02, 2009 9:33 am

Re: Proposed change to the help menu

Postby Hooray » Wed May 08, 2013 1:07 pm

Hi & welcome,

thanks for taking the time to provide feedback!

Create a /Docs subdirectory for each aircraft containing detailed documentation specific to each aircraft.

There's a "convention" to provide an aircraft-specific doc folder as part of the aircraft directory, see: http://wiki.flightgear.org/Standard_aircraft_structure
Like Thorsten said, it's just a "recommendation" - and nobody is forced to adhere to such a structure. It might be possible to require default aircraft to follow certain standards, prior to accepting them into $FG_ROOT or prior to shipping them with a release ...
Also see: http://www.mail-archive.com/flightgear- ... 22132.html

Other information (speeds, altitudes) are not listed unless the developer places that information into the 'Aircraft help' menu item.

There's a new feature that will be increasingly used in the future: http://wiki.flightgear.org/Aircraft_Checklists

I ASSUME that these two commands will one day be combined into a single menu item ? Maybe not.

They're different things: aircraft-specific help and simulator-specific help - so not sure if we should merge them ?

linking to the wiki via open-browser is implemented in merge request # 190: https://gitorious.org/fg/fgdata/merge_requests/190


Your wiki<->git related comments are valid, but it would be a lot of work to change that - because we'd need a wikimedia extension that directly uses git as a backend, or some other way to access the git repo. So unless you are volunteering to look into doing something along these lines, it's probably not a priority.
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: Proposed change to the help menu

Postby jdc843 » Wed May 08, 2013 3:00 pm

http://wiki.flightgear.org/Standard_aircraft_structure - I remember reading that document. Now that you pointed me to it again :oops: Good. I like easy solutions. Even if the solution is that I screwed up and missed something.

http://wiki.flightgear.org/Aircraft_Checklists - This looks to be handy. If it gets implemented.

Neither Help|Help or Help|Documentation Browser brings up aircraft specific documents. Not on my system anyway. One brings up docs in a web browser. The other brings up docs internally in FlightGear. I'm guessing that they will be merged whenever someone writes code for 'Documentation Browser' that makes it function as an internal web browser so it can display multiple file types; .txt,.pdf,.jpg, etc.

Help|'Aircraft help' - Seems to function as a quick reference guide. Plus whatever else the developer put in it.

wiki<->git - I didn't know if a way of doing that already existed. I'll leave this to someone else that knows how. Off topic: FlightGear seems to have several 'staging areas' for scenery, aircraft, etc. FlightGear files then go to git repositories. I think. I'll still trying to figure out what data comes from and goes to where. It is very frustrating. FGDATA doesn't have everything there. But I mirrored a 40GB ! scenery repository from somewhere. And of course that repository and FGDATA doesn't quite match up. I merged the FGDATA repository and the 40GB repository together. And that's what I use to play FlightGear. While I have scenery for the entire world now, I'm not sure if things are/will work correctly. Haha. Using those .tgz files for downloading scenery was too much of a pain. Hmm. So is the way I'm doing it now..

OK. So we have a /Docs directory. Now,
How to put docs in it. What to do if it isn't present or doesn't have docs in it.

The first Help menu item would depend on the developer placing docs in the /Docs directory. Maybe they would accept volunteers? If not, oh well.
Have it first point to a file (what will we name it?) in the /Docs directory - If it points to a file that doesn't exist, try loading a cached file. Maybe have it return an error message, or refer to the wiki page, or gray it out

The Help menu item that points to the wiki page - Maybe use the property /sim/aero to determine the aircraft name. Use that name to point to the wiki page.
This would not depend on the developer. This is why these menu items need to be implemented in the FlightGear sources. Not in the aircraft directories.

Maybe use a cache system - If no docs are in /Docs, create a /Docs directory (user specific unfortunately), fill it with the wiki page. Reduce the load on wiki/flightgear.org
Make these two buttons open the help docs in a browser window. See 3 paragraphs above for why.

Complication: Neither one of the docs in /Docs or the wiki page is considered the DEFINITIVE document. One that is always considered correct.

It would be nice if one menu item could be used to try to load the document in /Docs, if that fails, then automatically load the wiki page. But if/when the documents in /Docs is out of date compared to the wiki page, the wiki page would not be seen. This is why I propose using two menu items. Let the 'pilot' choose which he wants.

The wiki pages would remain as they are. Neither the docs in /Docs or the wiki page would contain EVERY spec of information known about an aircraft. But they can contain links to other documents anywhere on the Internet. (I'm not sure why I just wrote this paragraph.)
jdc843
 
Posts: 4
Joined: Wed May 08, 2013 3:29 am
Callsign: 1085
Version: 2.10-git
OS: GNU/Linux

Re: Proposed change to the help menu

Postby Hooray » Wed May 08, 2013 4:31 pm

Aircraft Checklists are intended to be implemented by all default aircraft, I've been in touch with Stuart (the developer who came up with the feature), and we have collected end user feedback, in order to improve consistency among those aircraft shipped with each release, see: http://wiki.flightgear.org/Release:Airc ... n_Criteria

Regarding the help menu: It's exactly like Thorsten mentioned, it's up to aircraft developers to provide such dialogs and resources - currently, we do not require them prior to including aircraft in the base package or the default release, we probably should consider doing that to improve the experience for end users.

Regarding the documentation "browser": It's rather simple and crude hack, I may say that - because I'm the guy who added it ...it's basically just the Nasal console dialog with 5 Lines of Nasal code. So it's really extremely simple and not suitable to be extended the way you envision.

I'm guessing that they will be merged whenever someone writes code for 'Documentation Browser' that makes it function as an internal web browser so it can display multiple file types; .txt,.pdf,.jpg, etc.

Conceptually, that would be possible using the new canvas system, which already does have support for rendering raster images (JPG, PNG etc) and vector images (SVG). Supporting a subset of HTML would not be too difficult - just by using regex to create corresponding OSGText animations (which are also already supported by the Canvas). So, using a very small subset of HTML (bold, underlined, italics, headers, paragraphs, links) would be pretty doable and not even complicated.

Now, regarding PDF support: that's a different beast, and not currently supported by ANY FG/SG code at all. Which is why PDF charts are usually converted to PNGs - i.e. in the 787 EFB. On the other hand, OSG (OpenSceneGraph, the rendering backend used by FG) does support rendering PDF - this is a feature that simply isn't used anywhere in SG or FG. Changing that would not be very difficult - but it would add more dependencies, and it would obviously require changes to the C++ code.
A simple Nasal/Canvas-based "HTML-browser" could be implemented using just an unmodified binary.

I'll still trying to figure out what data comes from and goes to where. It is very frustrating. FGDATA doesn't have everything there.

There's work going on to generalize the TerraSync functionality using WebDAV (IIRC), and to use that code not just for fetching/deploying scenery, but also other resources, such as aircraft:
http://wiki.flightgear.org/Aircraft_deployment
http://wiki.flightgear.org/Catalog_metadata

Eventually, the idea seems to be supporting multiple "repositories" (think "hangars") - so that people could download FG resources from several places.
We are well aware of the issues, see: http://wiki.flightgear.org/Simplifying_ ... Deployment

OK. So we have a /Docs directory. Now,
How to put docs in it. What to do if it isn't present or doesn't have docs in it.

Ideally, each aircraft directory would have its own "docs" folder - if it doesn't, try to get in touch with a maintainer/contributor with fgdata access, so that you can contribute corresponding files, which would ideally also be integrated with the gui/menubar, so that things are easily accesible.

The first Help menu item would depend on the developer placing docs in the /Docs directory. Maybe they would accept volunteers? If not, oh well.
Have it first point to a file (what will we name it?) in the /Docs directory - If it points to a file that doesn't exist, try loading a cached file. Maybe have it return an error message, or refer to the wiki page, or gray it out

That's definitely possible, and merely requires some XML/scripting familiarity, and even if you don't know anything about XML or scripting, you can probably learn how to do that by referring to other dialogs and aircraft. So if you'd like to help here, just let us know, so that we can provide pointers as required.

The Help menu item that points to the wiki page - Maybe use the property /sim/aero to determine the aircraft name. Use that name to point to the wiki page.
This would not depend on the developer. This is why these menu items need to be implemented in the FlightGear sources. Not in the aircraft directories.

I am not sure, I'd rather prefer adding simply another tag like <wiki-url>http://wiki.flightgear.org/787-8</wiki-url> - which does not require ANY changes to the source code at all - and it would be 100% optional, Nasal code could check if the property is set/available, and then enable the open-browser binding (like you suggested earlier).


I don't know if you are interested in working on this, or if you are familiar with git - but you could simply check out the merge request that I mentioned earlier and see if/how you can improve it according to your ideas, see: https://gitorious.org/fg/fgdata/merge_requests/190
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: Proposed change to the help menu

Postby jdc843 » Thu May 09, 2013 5:38 am

The following is not finished. I saved this once to drafts? But I couldn't find it and retrieve it without using my browsers' BACK button.
I don't want to lose what I've wrote. And I need to stop working on this for now.


1 - Rename the menu item Help|Help to Help|FlightGear Help. Or similar.
2 - Rename the menu item Help|Aircraft help to Help|Quick reference guide. Or similar. Note: I don't like this. "Quick reference guide" for what ? FlightGear or the aircraft ?

Might just be better to have sub-menus for help. Maybe Help --> FlightGear & Help --> Aircraft. With appropriate help items under each. But I think that "Common Aircraft Keys" & "Basic Simulator Keys" needs to stay together.
Note to self: Show/diagram how I think that this should be. Rather than expecting someone else to figure out what I mean. Then it can be critiqued. PS You suck at teaching.

I'm assuming that there is no objections to adding both menu items to the Help menu? The only question is how to implement them.
Keeping my lack of programming abilities in mind, I'll concentrate on basic functionality.
If this is a good idea, creating and using cache files is beyond my ability.

There are two menubar.xml files in fgdata/gui/. Find out when each is used.
I'm creating script commands below. But I doubt if they are correct. And not finished. I'm just typing stuff as I encounter it while examining FlightGear's files.

3 - First menu item
Problem: How to store the wiki page in /Docs in such a way as to not lose the wiki-specific formatting
Need to load common java scripts, image files somewhere assessable by every aircrafts' /Docs. What will happen to wiki formatting?
These docs are not to require internet access, remember?
Use nasal to determine which aircraft we are interested in using /sim/aero. Verify that property.
Insert that information into the path statement below.
Edit fgdata/gui/menubar.xml as follows:
<item>
<name></name>
<binding>
<command>open-browser</command>
<script>
var p = getprop("/sim/aero");
</script>
<path>Aircraft/aircraftname/Docs/index.html</path>
</binding>
</item>
Problem: What about the aircraft in /Aircraft-uiuc ?

4 - Second menu item
Edit fgdata/gui/menubar.xml as follows:
<item>
<name></name>
<binding>
<command>open-browser</command>
<path>wiki.flightgear.org/aircraftname</path> <--- There is supposed to be "URL" in there somewhere. I remember it from last night.
</binding>
</item>

The first Help menu item would depend on the developer placing docs in the /Docs directory. Maybe they would accept volunteers? If not, oh well.
Have it first point to a file (what will we name it?) in the /Docs directory - If it points to a file that doesn't exist, try loading a cached file. Maybe have it return an error message, or refer to the wiki page, or gray it out

That's definitely possible, and merely requires some XML/scripting familiarity, and even if you don't know anything about XML or scripting, you can probably learn how to do that by referring to other dialogs and aircraft. So if you'd like to help here, just let us know, so that we can provide pointers as required.

The Help menu item that points to the wiki page - Maybe use the property /sim/aero to determine the aircraft name. Use that name to point to the wiki page.
This would not depend on the developer. This is why these menu items need to be implemented in the FlightGear sources. Not in the aircraft directories.

I am not sure, I'd rather prefer adding simply another tag like <wiki-url>http://wiki.flightgear.org/787-8</wiki-url> - which does not require ANY changes to the source code at all - and it would be 100% optional, Nasal code could check if the property is set/available, and then enable the open-browser binding (like you suggested earlier).


I don't know if you are interested in working on this, or if you are familiar with git - but you could simply check out the merge request that I mentioned earlier and see if/how you can improve it according to your ideas, see: https://gitorious.org/fg/fgdata/merge_requests/190[/quote]
I've read the description of what it is. But haven't examined the code. I can clone and checkout. Don't know how to push changes via git. I'll ask for help on that when/if I get to that stage.
jdc843
 
Posts: 4
Joined: Wed May 08, 2013 3:29 am
Callsign: 1085
Version: 2.10-git
OS: GNU/Linux

Re: Proposed change to the help menu

Postby Hooray » Thu May 09, 2013 1:43 pm

Keeping my lack of programming abilities in mind, I'll concentrate on basic functionality.
If this is a good idea, creating and using cache files is beyond my ability.


For now, you could focus on the XML side of things, which should not require any programming skills.

To run open-browser using an aircraft-specific URL, you would use getprop() to get the custom part from the property tree, and then build the url using WIKI_URL + CUSTOM_PART - In Nasal, this concatenation is accomplished using the tilde operator:

Code: Select all
var base_url = "http://wiki.flightgear.org/";
var aircraft_url = "787-8";
var final_url = base_url ~aircraft_url;
print( "Final URL is: ", final_url);


You could then also use getprop() to read the aircraft_url from the property tree - so that aircraft developers can configure it, i.e. by using something like getprop( "/sim/wiki-url");. By default, you can fall back to the /Aircraft URL, i.e. : http://wiki.flightgear.org/Aircraft

Finally, you will want to run the open-browser using the custom-built URL: http://wiki.flightgear.org/List_of_Nasa ... mand.28.29
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: Proposed change to the help menu

Postby jdc843 » Sat May 11, 2013 5:33 am

Per README.gui, PUI/PLIB doesn't allow submenus. IE, I can't create Help|Aircraft help|{several menu options here}. I vote to dump Plib and use another system. I can hear every aircraft developer scream "NO!" about that idea :) I did read where this has been discussed before.

I originally thought of having two separate Help menu items. However :

There may not be a wiki page on wiki.flightgear.org for an aircraft. Especially for aircraft not hosted on FlightGear's website. Even if there is one for a particular type of aircraft, the page that exists could be for an aircraft with a different developer. In which case the wrong help page would be presented to the user. So having a fallback won't always work.

No way, that I know of, to easily convert a wiki formatted webpage to other formats that could be stored in /Docs. This necessitates manual intervention. Because this is done, just ask (and depend on) the person doing the work to place a URL pointing to any external documentation into /Docs/index.html

What can be done about the graphics, script files, etc that so nicely format the displayed pages on wiki.flightgear.org? Put them in a common area in the data tree ? /fgdata/Docs/{img,scripts}

Do not create another a property. Can't depend on developer to use it. Instead depend on /Docs/index.html Can't depend on developer to use this either. But it would provide an easy way to point to documentation wherever it is. If /Docs/index.html doesn't exist, execute fallback.

1 - Help page on wiki.flightgear.org (Y/N)
2 - Help page/index in /Docs (Y/N)
3 - Help page elsewhere (Y/N)

For the 'viewpoint' of FlightGear's executable:
321
NNN - No docs anywhere. Execute fallback.

NNY - Help exists. But don't know that it does. Execute fallback.
YNN - Help exists. But don't know that it does. Execute fallback.
YNY - Help exists. But don't know that it does. Execute fallback.

NYN - Display /Docs/index.html
NYY - Display /Docs/index.html Depend on it to provide pointer to external docs
YYN - Display /Docs/index.html Depend on it to provide pointer to external docs
YYY - Display /Docs/index.html Depend on it to provide pointer to external docs

FALLBACK:
Perform a check that the developer has provided contact info.
Possible fallback message :
"Sorry.

Can't find the documentation for this aircraft. You will have to
manually search for any documentation yourself.

You can also contact the developer at INSERT DEVELOPER'S CONTACT INFO
HERE and (nicely) ask for help. This will have the added bonus of
informing the developer that someone is interested in his/her aircraft.

Click on the following link for some help resources

INSERT LINK HERE"
This link will open the same page as "Help|Help" does.
END FALLBACK

So basically do this:
Rename "Help|Help" to "Help|FlightGear Help"

Rename "Help|Aircraft Help" to maybe "Help|Aircraft Quick Ref" or "Help|Aircraft Quick Help" ? Developer's can later move instructions from it and place them into the Checklists.

Insert new "Help|Aircraft Help" into fgdata/gui/menubar.xml that will:
getprop "/sim/aircraft-dir"/Docs/index.html
If found, execute open browser to display it.
If not found,
getprop{developer's name | developer's email address} - Is there a property for developer's email address ?
Display fallback message including developer's information.
Display button to do the same as "Help|FlightGear Help"

Developers are to create /Docs/index.html if they wish.

Place link in /fgdata/Docs/index.html referring to aircraft list at wiki.flightgear.org

Done.

What do you think ?
jdc843
 
Posts: 4
Joined: Wed May 08, 2013 3:29 am
Callsign: 1085
Version: 2.10-git
OS: GNU/Linux


Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest