Board index FlightGear Development Documentation

READ-ME (text-file) formatting request

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

READ-ME (text-file) formatting request

Postby jharris1993 » Wed Apr 17, 2013 2:05 am

Issue:
  • FlightGear is primarily developed by people using non-Windows equipment.
  • FlightGear is, and has been, ported to people who use the Windows O/S
  • It is essential that all users, both Windows and non-Windows alike, have good and sufficient access to the relevant documentation, (such as read-me files), so that they can install and use both FlightGear and the various installable items correctly, with a minimum of support headaches.
  • Because the embedded documentation, (i.e. read-me files in various Aircraft folders and other installable things), is generated on non-Windows systems, the line-ending format produces documents that are - in essence - unreadable by Windows users unless they go to the trouble of installing some kind of formatting conversion program.

Allow me to humbly suggest the following naming convention and formats for included text documents:
  • "Normal" documents, (those generated by Linux or Mac text editors), be listed without a qualifying extension. (i.e. A "normal" README file would be named "README", without a ".txt" extension.)
  • Documents formatted using the CR-LF line terminator sequence needed by Windows be named with the qualifying extension. (i.e. A "Windows" README file would be named "README.txt"
  • I would beg anyone creating items that have imbedded text based documentation to try to create both types of text document so that everyone can benefit from your hard work.
  • Failing that, I would humbly beg that these documents be transformed into a machine-agnostic format, like PDF.

Thanks!

Jim (JR)
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 139
Joined: Sun Nov 18, 2012 9:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-7 / Linux

Re: READ-ME (text-file) formatting request

Postby Hooray » Wed Apr 17, 2013 3:53 am

you are raising some fair points - a while ago, someone simply provided a LaTex wrapper that used \includefile{} or \verbatiminput{} to include all the README files (with proper headings) - so that they could remain Unix-style README files, while a PDF would be straightforward to create/update using Tex and the build system. For some reason that never got committed ...
I still believe that to be the superior solution, because it is fairly straightforward, doesn't require us to change/update our docs - and scales pretty well, because Windows/Mac-folks could simply refer to the PDF file.

http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbfile
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: 11326
Joined: Tue Mar 25, 2008 8:40 am

Re: READ-ME (text-file) formatting request

Postby Thorsten » Wed Apr 17, 2013 7:30 am

Because the embedded documentation, (i.e. read-me files in various Aircraft folders and other installable things), is generated on non-Windows systems, the line-ending format produces documents that are - in essence - unreadable by Windows users unless they go to the trouble of installing some kind of formatting conversion program.


Or you can install a text editor with actually deserves the name (like notepad++) under Windows :D It's less of a generic Windows and more of a notepad-specific problem.
Thorsten
 
Posts: 10844
Joined: Mon Nov 02, 2009 8:33 am

Re: READ-ME (text-file) formatting request

Postby Hooray » Wed Apr 17, 2013 7:41 am

Even just using wordpad should work, and it is available by default - no need for any downloads. Here, the main issue seems to be the non-Windows file extensions, like README.introduction for example - so that the proper program cannot be found. Thus, even as a Linux user, I do agree that we should strive to improve the situation - but I wouldn't change/touch those files, only provide a tex wrapper so turn them into a PDF for our users on handicapped OS. :lol:
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: 11326
Joined: Tue Mar 25, 2008 8:40 am

Re: READ-ME (text-file) formatting request

Postby Johan G » Wed Apr 17, 2013 8:33 pm

Hooray wrote in Wed Apr 17, 2013 7:41 am:...turn them into a PDF for our users on handicapped OS. :lol:

:lol: Not a bad idea though...
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: 5490
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: READ-ME (text-file) formatting request

Postby helijah » Wed May 01, 2013 6:02 pm

Thorsten wrote in Wed Apr 17, 2013 7:30 am:
Because the embedded documentation, (i.e. read-me files in various Aircraft folders and other installable things), is generated on non-Windows systems, the line-ending format produces documents that are - in essence - unreadable by Windows users unless they go to the trouble of installing some kind of formatting conversion program.


Or you can install a text editor with actually deserves the name (like notepad++) under Windows :D It's less of a generic Windows and more of a notepad-specific problem.


I absolutely agree with that. If a basic software is poorly designed and poorly written, it's not up to us to adapt our work to overcome that. It is at M$ to correct its mistakes. Do not reverse the problems. When we adapt our files for bad programs, they will never be corrected.

The ideal solution remaining to put the users what this horror that is Windows on an OS worthy of the name, GNU/Linux of course. But unfortunately the best choices are rarely most numerous :)

Regards Emmanuel
Some planes (and other) for FlightGear
http://helijah.free.fr
and
http://embaranger.free.fr
User avatar
helijah
 
Posts: 1002
Joined: Wed Dec 27, 2006 12:35 pm
Location: Chartres (France)
Callsign: helijah
IRC name: helijah
Version: GIT
OS: GNU/Linux

Re: READ-ME (text-file) formatting request

Postby Hooray » Wed May 01, 2013 7:01 pm

the original LaTex wrapper approach seems to be the simplest, most flexible and most scalable solution - basically, the files would remain untouched, and we'd just add a .tex file to $FG_ROOT/Docs which merely includes the plain text files using a proper heading - the TOC can be built automatically - and contributors would not have to go through the hassle of manually porting/maintaining files for different OS.

I am willing to get this going, so if anybody is interested, I can provide the required LaTex stubs - you should ideally have a LaTex toolchain installed locally, and maybe even know how to use a gitorious clone of fgdata, so that your work can be directly committed upstream. Note that you don't really need to intimately know LaTex or git - LaTex-wise you should only need to know how to use copy/paste, and adjust a file name. Git-wise, it would be kinda cool if you knew how to push something to gitorious and create a merge request (both well-documented via various wiki articles)

You /could/ use a web-based LaTex IDE which allows you to upload the FG README* files, something like: https://www.sharelatex.com/
I *think* they even have integrated git support.
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: 11326
Joined: Tue Mar 25, 2008 8:40 am

Re: READ-ME (text-file) formatting request

Postby jam007 » Thu May 02, 2013 8:17 am

What is the argument against reformatting the files under Doc to html and adding an index-file?
Then they could be viewed in a browser under any os and easily linked to online in GIT from here in the forum or from the wiki and the homepage.
jam007
 
Posts: 477
Joined: Sun Dec 16, 2012 10:04 am
Location: Uppsala, Sweden
Version: 2017.3.1
OS: Ubuntu 16.04

Re: READ-ME (text-file) formatting request

Postby Hooray » Thu May 02, 2013 12:20 pm

IIRC, there are already a bunch of HTML files in $FG_ROOT/Docs - most of them originally contributed by David Megginson. Now fast forward, the plain text files were always better maintained than any other files, including PDF or HTML. Which is because it is so much easier to add new stuff, or fix existing docs - it can be done in any editor, editing PDF, HTML or LaTex is often a little more intimidating
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: 11326
Joined: Tue Mar 25, 2008 8:40 am

Re: READ-ME (text-file) formatting request

Postby Johan G » Thu May 02, 2013 8:35 pm

Maybe the simplest solution is to just add support for OSes that are broken by default (*cough* Windows *cough*). :wink:

Personally I use a tiny text editor that can handle these text files perfectly. It is called SciTE, it loads faster than notepad, have tabs and can and have been be set to open files as read only, just to be on the safe side.
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: 5490
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: READ-ME (text-file) formatting request

Postby Hooray » Mon May 06, 2013 7:20 pm

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: 11326
Joined: Tue Mar 25, 2008 8:40 am

Re: READ-ME (text-file) formatting request

Postby jharris1993 » Sun Jun 02, 2013 11:41 pm

Because the embedded documentation, (i.e. read-me files in various Aircraft folders and other installable things), is generated on non-Windows systems, the line-ending format produces documents that are - in essence - unreadable by Windows users unless they go to the trouble of installing some kind of formatting conversion program.


helijah wrote in Wed May 01, 2013 6:02 pm:
Thorsten wrote in Wed Apr 17, 2013 7:30 am:
Or you can install a text editor with actually deserves the name (like notepad++) under Windows :D It's less of a generic Windows and more of a notepad-specific problem.


I absolutely agree with that. If a basic software is poorly designed and poorly written, it's not up to us to adapt our work to overcome that. It is at M$ to correct its mistakes. Do not reverse the problems. When we adapt our files for bad programs, they will never be corrected.


Pardon me, but this is exactly the kind of answer and attitude that prevents people from adopting operating systems like Linux, and software like Flight Gear.

If we assume for the moment that I was a total newbie at this, (which I am not, by the way), and I had come here with a simple and polite problem and question; an arrogant response like this would be a lead-pipe-cinch guarantee that, not only would I never darken the door of Flight Gear ever again, I would stay as far away from Linux as I possibly could.

It is not right for the users of any operating system, Linux, Mac, Windows, IBM-370 Mainframe, AIX, Solaris, or anything else for that matter, to denigrate or belittle any other operating system or its users.

Saying that the Notepad program in Windows is a "bad program" simply because it implements the end-of-line terminator differently than Unix and its clones do borders on. . . . I'm not even sure how to say it and remain polite. Is Solaris a "bad" operating system because because it defines on-screen widgets differently than Gnome or KDE? Is Apache or Free BSD "broken" because they use a different licensing model than either Linux or Windows uses?

Claiming that Microsoft's implementation of the end-of-line terminator is a "mistake" is not only narrow-minded, it ignores much of the history and development of microcomputers.

Microsoft didn't even invent it, they just brought it forward from the code for CPM/MPM written by Digital Research in the 1980's, and Digital Research borrowed it from even earlier code written in the '60's, '70's and earlier '80's by other computer manufacturers who were writing for ASR-110 Teletypes and Centronics printers that used discrete carriage-return, (0x0D), and line-feed, (0x0A), ASCII control codes to return the carriage and advance the paper.
http://academic.evergreen.edu/projects/biophysics/technotes/program/ascii_ctrl.htm

As a Flight Gear user, I feel I have a responsibility to invite other computer users to try, (and if possible adopt), this excellent flight simulation program. As a computer user, I use both Windows (Win-7, 64 bit), and Linux, (currently Mint 14 64 bit with Cinnamon), for various things - and I use the operating system that "feels right" to me for the task that I use it for.

My original issue and question was based on my desire for the documentation to be more inclusive rather than exclusive, to allow a broader user base to understand and properly configure the excellent efforts that many people have put into this software.

Two choices were suggested before the idea of throwing the baby out with the bathwater took over:
  • Create two copies of the text-based documentation files, one for 'Nix/Mac and one for Windows, with appropriate line-ending terminators for each.
  • Create ONE standard document type that everyone can read with a minimum of trouble, (.pdf, etc.)

I am willing to support either of these possibilities, along with any other suggestion or possibility that is germane, sensible, and inclusive.

I DO NOT, and I WILL NOT support or endorse any name calling or operating system bashing, here or anywhere else on these fora.

What say ye?

Jim (JR)
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 139
Joined: Sun Nov 18, 2012 9:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-7 / Linux

Re: READ-ME (text-file) formatting request

Postby Thorsten » Mon Jun 03, 2013 6:22 am

Pardon me, but this is exactly the kind of answer and attitude that prevents people from adopting operating systems like Linux, and software like Flight Gear.


Pardon me, but I really do think that notepad is a rather narrow minded piece of software and that even somewhat modern text editors on both Windows and Linux have zero problems to deal with ascii files regardless of where they were generated.

My question is: Why do you think it is reasonable to invest time and manpower in a problem that can be solved at the simple expense of a) using wordpad rather than notepad under Windows (I believe that is part of the standard Windows package) or b) using a free editor like notepad ++. We don't usually insist that websites have to display properly under Mosaic either nowadays, we deem it reasonable to ask people to run a halfway modern browser.

If we assume for the moment that I was a total newbie at this, (which I am not, by the way), and I had come here with a simple and polite problem and question; an arrogant response like this would be a lead-pipe-cinch guarantee that, not only would I never darken the door of Flight Gear ever again, I would stay as far away from Linux as I possibly could.


If you, on learning that Windows has a problem which Linux has solved a while ago, would stay away from Linux as far as possible, some might take this for an unreasonable reaction :-)

But as I said above - this manifestly isn't a Windows vs. Linux problem, it's a very specific problem of the Windows notepad editor. So please don't cast this into 'You don't support Windows' - there are plenty of Windows users who can deal with the files. Well, 'You don't support notepad users!' doesn't really sound quite as urgent...
Thorsten
 
Posts: 10844
Joined: Mon Nov 02, 2009 8:33 am

Re: READ-ME (text-file) formatting request

Postby Hooray » Mon Jun 03, 2013 7:24 am

For the record: I was going to post exactly what Thorsten said - it's not at all a Windows/Linux issue, Notepad is just an extremely simple implementation of an editor that simply doesn't provide many features that would be considered "standard" these days, and which is indeed the reason why wordpad.exe should be used. Still, many users are not aware of such notepad restrictions - and notepad may be associated with README files.

That being said, the deeper issue here is improving accessibility and usability which is 100% legit - and is exactly the reason why I am supportive of the idea of using a LaTex wrapper for the various README.* files in $FG_ROOT that compiles into a simple PDF that will automatically be opened by the correct viewer, i.e. acrobat reader, without being a PITA to maintain for fgdata contributors, who would still end up committing updates to the various README files.

So please, do not try to turn this into a MS vs. NIX issue - which it really isn't at all - I'd argue that it has taken all of us more time to respond here than simply provide a LaTex wrapper to get this thing started, and the topic closed for good :D

Here's a little Nasal helper that create a simple LaTex stub:
Code: Select all
var path = getprop("/sim/fg-root") ~ "/Docs";
var doc_path = func(file) return path ~ file;

var latex_begin = "
\\documentclass[12pt]{article}

\\usepackage[english]{babel}
\\usepackage[utf8x]{inputenc}
\\usepackage{amsmath}
\\usepackage{graphicx}
\\usepackage{sverb}

\\title{FlightGear READMEs}
\\author{FlightGear Community}

\\begin{document}
\\maketitle

% automatically created section

";


var files = [
 "README.introduction","README.electrical","README.sound", "README.3DClouds", "README.fgjs", "README.JSBsim","README.minipanel","README.submodels",
 "README.xmlparticles", "README.airspeed-indicator", "README.flightrecorder","README.jsclient","README.multiplayer", "README.systems","README.xmlsound",
 "README.checklists","README.gui","README.multiscreen", "README.tutorials","README.xmlsyntax","README.commands","README.hud","README.layout",
 "README.osgtext","README.yasim","README.conditions","README.properties","README.wildfire", "README.digitalfilters","README.IO","README.logging","README.protocol","README.xmlhud", 
 "README.effects","README.Joystick","README.materials","README.scenery","README.xmlpanel" ];

print( latex_begin );
foreach (var f; files) {
   var section =  "\\section{"~f~"}\n";
   var content =  "\\verbinput{"~doc_path(f)~"}\n";
   print (section, content);
}
print("\\end{document}");


(you would probably want to order the README files a little and maybe provide more descriptive titles - but for starters, that shoudl work - you could also directly write the whole thing to disk using io.nas obviously)

@Thorsten: could you please create a corresponding LaTex stub using the script, review it and add it to $FG_ROOT/Docs ?
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: 11326
Joined: Tue Mar 25, 2008 8:40 am

Re: READ-ME (text-file) formatting request

Postby jharris1993 » Mon Jun 03, 2013 2:17 pm

Hooray wrote in Mon Jun 03, 2013 7:24 am:<snip>
That being said, the deeper issue here is improving accessibility and usability which is 100% legit - and is exactly the reason why I am supportive of the idea of using a LaTex wrapper for the various README.* files in $FG_ROOT that compiles into a simple PDF that will automatically be opened by the correct viewer, i.e. acrobat reader, without being a PITA to maintain for fgdata contributors, who would still end up committing updates to the various README files.

So please, do not try to turn this into a MS vs. NIX issue - which it really isn't at all - I'd argue that it has taken all of us more time to respond here than simply provide a LaTex wrapper to get this thing started, and the topic closed for good :D

<snip code block>

(you would probably want to order the README files a little and maybe provide more descriptive titles - but for starters, that shoudl work - you could also directly write the whole thing to disk using io.nas obviously)

@Thorsten: could you please create a corresponding LaTex stub using the script, review it and add it to $FG_ROOT/Docs ?


First, you have been mis-reading me all along. I'm not saying this is a Windows vs anyone else issue. I'm saying this is an accessibility issue, and I think Hooray's idea of making corresponding pdf files out of corresponding 'nix generated text files is a good one.

That solves a problem within FlightGear itself, but what about individual aircraft packages? (Which, by the way, is what prompted this thread in the first place.)

These packages are often created, compiled, and submitted by third-parties who may not necessarily be on-board with this. In my own case I use Ultra Edit which handles "DOS/Unix" line terminator conversions very well, thank you. However, there are times when I want to avoid UltraEdit's overhead and simply use Notepad, and occasionally I'll miss something important because it ended up off the edge of the screen. (Which, by the way, is exactly what happened that time, and I boffed up an aircraft install until I figured out what I had done wrong.)

Seriously, I'm not trying to pound sand here, or bust anyone's horns. All I want to do is to try and make FlightGear as accessible and easy to use and implement for the broadest audience as possible. And not everyone who uses FlightGear is as brainy as you guys are.

OK?

Jim (JR)
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 139
Joined: Sun Nov 18, 2012 9:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-7 / Linux

Next

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest