Board index FlightGear Development Documentation

Automatic documentation generator

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

Re: Automatic documentation generator

Postby Hooray » Fri Jan 16, 2015 6:49 pm

I would add a disclaimer to all automatically-created PDF files that they're not to be edited manually, including a link to the new wiki article for additional pointers.
Equally, Aircraft Checklists should contain a link to the corresponding wiki article, just to ensure that people don't start editing PDF files for augmenting checklists.
And the FlightGear/FGData version should probably be a part of the footer/header, too ($FG_ROOT/version)
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: 11162
Joined: Tue Mar 25, 2008 8:40 am

Re: Automatic documentation generator

Postby Johan G » Fri Jan 16, 2015 7:02 pm

Hooray wrote in Fri Jan 16, 2015 6:49 pm:And the FlightGear/FGData version should probably be a part of the footer/header, too ($FG_ROOT/version)

+1 Very good idea/point. :D Maybe also month and year. :wink:

Edit: Noted that there already is a date there. Good. :D
Low-level flying — It's all fun and games till someone looses an engine. (Paraphrased from a YouTube video)
Improving the Dassault Mirage F1 (Wiki, Forum, GitLab. Work in slow progress)
Johan G
Moderator
 
Posts: 5292
Joined: Fri Aug 06, 2010 5:33 pm
Location: Sweden
Callsign: SE-JG
IRC name: Johan_G
Version: 3.0.0
OS: Windows 7, 32 bit

Re: Automatic documentation generator

Postby rubdos » Fri Jan 16, 2015 7:13 pm

Hooray wrote in Fri Jan 16, 2015 6:49 pm:I would add a disclaimer to all automatically-created PDF files that they're not to be edited manually, including a link to the new wiki article for additional pointers.
Equally, Aircraft Checklists should contain a link to the corresponding wiki article, just to ensure that people don't start editing PDF files for augmenting checklists.
And the FlightGear/FGData version should probably be a part of the footer/header, too ($FG_ROOT/version)


Isn't a pdf as a "sign" to the user for not editing it? It's not like I'm supplying a .docx file or so (don't shoot!)

Aircraft checklists are implemented in .xml files, you mean I should include a link to the main wiki article, right?

I will include the version data in the next revision, that's a very good idea;
Johan G wrote in Fri Jan 16, 2015 7:02 pm:Maybe also month and year. :wink:

I'll include the month and year in the header or footer. I'll have a look what looks best.

I don't have access to my fgdata atm, I'm not sure when I'll have time to give it a go.
User avatar
rubdos
 
Posts: 17
Joined: Sun Aug 28, 2011 5:48 pm
Location: Brussels
Callsign: FTL579
Version: git
OS: Linux

Re: Automatic documentation generator

Postby Hooray » Fri Jan 16, 2015 7:32 pm

  • we've seen several incidents where people would even edit "the manual" (the PDF file) even though the manual is maintained in LaTex
  • yes, a link to the wiki article would make sense, or some people might also start editing those PDF files (checklists)
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: 11162
Joined: Tue Mar 25, 2008 8:40 am

Re: Automatic documentation generator

Postby Johan G » Fri Jan 16, 2015 7:35 pm

Maybe all that information is not necessary in the footer or header on each and every page, but it should be somewhere in the document. I noted that the date already is there on the first page of the docs.
Low-level flying — It's all fun and games till someone looses an engine. (Paraphrased from a YouTube video)
Improving the Dassault Mirage F1 (Wiki, Forum, GitLab. Work in slow progress)
Johan G
Moderator
 
Posts: 5292
Joined: Fri Aug 06, 2010 5:33 pm
Location: Sweden
Callsign: SE-JG
IRC name: Johan_G
Version: 3.0.0
OS: Windows 7, 32 bit

Re: Automatic documentation generator

Postby clrCoda » Fri Jan 16, 2015 7:56 pm

Ruben,

stuart wrote in Sun Jan 11, 2015 8:17 pm:As an aside, it would be worth including the source repository (generally fgaddon) for each aircraft, so a use could read the PDF and know where to download the aircraft from.


I believe that Stuart means you might consider adding a line to the resulting doc that says where the plane can be found in the flightgear world. Is it at someones hangar? The main aircraft download page? Comes with FG by default?

Thanks for these, they will be well appreciated.

Ray
Ray St. Marie
clrCoda
 
Posts: 1228
Joined: Wed Apr 07, 2010 11:04 am

Re: Automatic documentation generator

Postby rubdos » Sat Jan 17, 2015 8:13 am

Hooray wrote in Fri Jan 16, 2015 7:32 pm:
  • we've seen several incidents where people would even edit "the manual" (the PDF file) even though the manual is maintained in LaTex
  • yes, a link to the wiki article would make sense, or some people might also start editing those PDF files (checklists)

Johan G wrote in Fri Jan 16, 2015 7:35 pm:Maybe all that information is not necessary in the footer or header on each and every page, but it should be somewhere in the document. I noted that the date already is there on the first page of the docs.


Ok. I'll add a title page to the checklists too, with a preamble stating the obvious to those users. And I'll add wiki links there.
clrCoda wrote in Fri Jan 16, 2015 7:56 pm:Ruben,

stuart wrote in Sun Jan 11, 2015 8:17 pm:As an aside, it would be worth including the source repository (generally fgaddon) for each aircraft, so a use could read the PDF and know where to download the aircraft from.


I believe that Stuart means you might consider adding a line to the resulting doc that says where the plane can be found in the flightgear world. Is it at someones hangar? The main aircraft download page? Comes with FG by default?


This one is not as easy, but I'll try to do that too.

clrCoda wrote in Fri Jan 16, 2015 7:56 pm:Thanks for these, they will be well appreciated.

You're very welcome. I liked to do this :-)

On a related topic: I checked in the python script in fgdata, but now I'm thinking it'd be better to separate it from it, as I'm planning to add other files to parse other data from flightgear (rendering airport diagram's, SID's, STAR's etc.). Would it be best to create a separate repository for these scripts?

On rendering those Airport diagrams, I know there is http://wiki.flightgear.org/Airport_Diagram_Generator, this topic viewtopic.php?p=229897 and I know people are implementing it in Nasal using Canvas, but having it in an external script can have advantages. Just to make the parallel with the checklists: people would be able to have those things on paper or an e-reader, people will be able to download them from this central website. All this to ask: would there be interest in having those sort of diagrams, just like you would download them from Jeppesen or other non-free sources, but based on flightgear data and licensed as such and as a pdf instead of in-flightgear?
On the other hand; it would mean some duplicate work.
User avatar
rubdos
 
Posts: 17
Joined: Sun Aug 28, 2011 5:48 pm
Location: Brussels
Callsign: FTL579
Version: git
OS: Linux

Re: Automatic documentation generator

Postby Hooray » Sat Jan 17, 2015 3:52 pm

This one is not as easy, but I'll try to do that too.

you only need to parse the catalog metadata to support this - which should usually contain a few URLs for each aircraft.
Which is how the aircraft center works internally, so that aircraft can be downloaded/installed at run-time (see the wiki for details):

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

Re: Automatic documentation generator

Postby rubdos » Thu Jun 15, 2017 12:43 pm

Hi again!

It's been quite a while, but I am currently reviving this a bit. First tried whether the scripts still worked (they did, more or less), and currently implementing a CI/CD chain to have the PDF's auto generate every week or month or so. The results can be seen on my server, e.g. this is Brussels International Airport Zaventem.

EDIT: and probably most importantly: I currently have it in a Git repo; should still add a license to it though.
User avatar
rubdos
 
Posts: 17
Joined: Sun Aug 28, 2011 5:48 pm
Location: Brussels
Callsign: FTL579
Version: git
OS: Linux

Previous

Return to Documentation

Who is online

Users browsing this forum: No registered users and 2 guests