Board index FlightGear Development Documentation

Improving Canvas docs (cont'd PM)

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

Improving Canvas docs (cont'd PM)

Postby Hooray » Fri Apr 10, 2015 5:51 pm

Thorsten wrote:Okay, some basic feedback:

What do people need in the wiki - compare the snippet page with e.g. the particle system
http://wiki.flightgear.org/Particle_System
that's not a great bit of documentation, but it got me working particle systems within 30 minutes.

Why? Starts from a working example first, then lists all the things I could change on it next - so I have something working, and then I know what I can change.

Canvas snippets leave me in the blank how to proceed

I read

Code: Select all
var myLayout = canvas.HBoxLayout.new();


and wonder what else I can insert here except HBox layout. Or how I can move the thing around. Or what not. That's the fundamental flaw in all canvas documentation - it's not enough to get something working, the user also needs an idea of what to change, how it can be adapted.


VBox is the only other layouting option available as far as I remember - so everything is made up using vertical/horizontal "boxes" (aka tables).
I am not sure if the simplicity of documenting available/supported XML tags can be easily mapped to a full-fledged programming language like Nasal - but you made a good point that we should probably document supported parameters/attributes or "modes" whenever possible. I think it would make sense to extend the underlying template accordingly and provide a list of documented options.

That said, for the Canvas stuff you're currently working on (i.e. visualizing orbital flights on a moving map), layouts are not necessarily relevant, unless you're intending to get really fancy - i.e. a simple moving map should be possible already - but given your previously outlined requirements, things are much more easily accomplished by using/extending the existing MapStructure framework:
Using Canvas for visualizing orbital flights (cont'd PM)
Image
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: 11100
Joined: Tue Mar 25, 2008 8:40 am

Re: Improving Canvas docs (cont'd PM)

Postby Hooray » Sun Apr 12, 2015 6:03 pm

@Thorsten: I've begun adding a few more code snippets to the wiki to add the missing pieces that you needed to prototype your orbital map - is there anything else missing in your opinion, or would you like to add any other features to that map for which we don't currently have demo code ?

I am really just thinking in terms of "building blocks" to grow a "toolbox" with snippets that are sufficiently well-commented so that they can be used as the foundation for similar efforts in the future:

http://wiki.flightgear.org/Canvas_Snippets
Image
Image
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: 11100
Joined: Tue Mar 25, 2008 8:40 am

Re: Improving Canvas docs (cont'd PM)

Postby Alant » Sun Apr 12, 2015 9:13 pm

The Canvas docs have a lot of Howto´s, which I believe should be entitled "development plan/suggestion" or similar.

The title "Howto" should be reserved for cookbook documents which show how to use an already working part of FG.

- just my 3 pence/dime/cent input ,-)

Alan
Alant
 
Posts: 710
Joined: Wed Jun 23, 2010 5:58 am
Location: Portugal
Callsign: Tarnish99
Version: from Git
OS: Windows 10


Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest