Board index FlightGear Development Documentation

Fork manual into user guide and installation guides

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

Fork manual into user guide and installation guides

Postby jharris1993 » Thu Nov 22, 2012 8:14 pm

Ref: http://www.flightgear.org/forums/viewto ... 15#p171105

In this particular article, I broached the idea of forking the manual into two major sections:
  • The "User Guide" manual. That is, all of the information about successfully using FlightGear that is not installation related.
  • "Installation Guide" manuals - there would be specific and individual manuals for each major operating system supported by FG,
    (i.e. the various 'nix flavors, Mac, Windows, et. al.)

My reason for wanting to do this - at least with respect to the older version of the FG manual I read - is that the installation instructions are a mish-mash of different instructions for differing platforms, with the lion''s share being 'nix-centric.

IMHO, this makes the installation of FlightGear a non-trivial exercise, especially for the non-linux user.

Ideally the installation guides should be expressed simply enough that someone at the "noob" level who wants to give FG a try would have an absolute minimum of difficulty getting FG running, configured, and a plane in the air.

I believe that bifurcating the manual into separate, independent, installation manuals will go far and do much to help overcome this barrier to entry.

Another valuable side-effect of forking out the installation instructions is that it places the various parts of a particular instal in much higher relief; allowing us to spot - and correct - systemic installation gaffe's that might otherwise go unnoticed.

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: Fork manual into user guide and installation guides

Postby stuart » Fri Nov 23, 2012 9:44 am

Hi Jim,

I think having different sections describing how to install FG on different OS is an excellent idea and would improve the manual significantly. However, I don't see much advantage in separating it into different per-OS documents given that the whole manual is only 5MB in size.

As a starting point I'd suggest re-structuring Chapter 3 (Preflight: Installing FlightGear) so that there are separate sections for each OS that includes how to install the base program, scenery and aircraft. You should be able to write each OS section in its own file and then use some LaTex to include them in the main document. That would make it almost trivial to generate per-OS install guides if we want to in the future, or even as an experiment.

-Stuart
G-MWLX
User avatar
stuart
Moderator
 
Posts: 1404
Joined: Wed Nov 29, 2006 9:56 am
Location: Edinburgh
Callsign: G-MWLX

Re: Fork manual into user guide and installation guides

Postby jharris1993 » Sat Nov 24, 2012 4:06 am

stuart wrote in Fri Nov 23, 2012 9:44 am:Hi Jim,

I think having different sections describing how to install FG on different OS is an excellent idea and would improve the manual significantly. However, I don't see much advantage in separating it into different per-OS documents given that the whole manual is only 5MB in size.

As a starting point I'd suggest re-structuring Chapter 3 (Preflight: Installing FlightGear) so that there are separate sections for each OS that includes how to install the base program, scenery and aircraft. You should be able to write each OS section in its own file and then use some LaTex to include them in the main document. That would make it almost trivial to generate per-OS install guides if we want to in the future, or even as an experiment.

-Stuart

An excellent suggestion.

I can see advantages to actually forking the document; but for the time being, your idea of simply rendering them as individual sections of whatever kind within the document itself is an absolutely superlative idea. This give us a chance to kick ideas around and see how things fit together without having to go through the trouble of actually forking the document. It will also give me a chance to work on my global document composition skills in a more benign environment.

One of the big "rocks in the road" that I see is that my experience with LaTeX is extremely limited, being limited to knowing how the waist-band on my BVD's works, and having Latex gloves to work with allergy-causing plants. :D

I do not expect to have any troubles working with individual document sections - once I gain some traction with the tools - but I still have absolutely now idea how I would go about taking all the individual sections and "compiling" them into a single monolithic document.

For the time being, I am going to ignore that aspect and concentrate or gaining traction with the tools and the LaTeX source documents you have already given me. Once I gain traction with that, we can move on into document composition.

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: Fork manual into user guide and installation guides

Postby Hooray » Sat Nov 24, 2012 5:09 am

This is trivial to do using any of the LaTex GUI editors that were previously mentioned. It all boils down to copy/paste into an external file and then referencing it via \include{filename}

Most GUIs can even hide these details. So please don't worry about the LaTex side of things ...
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: Fork manual into user guide and installation guides

Postby jharris1993 » Sat Nov 24, 2012 6:35 am

Hooray wrote in Sat Nov 24, 2012 5:09 am:This is trivial to do using any of the LaTex GUI editors that were previously mentioned. It all boils down to copy/paste into an external file and then referencing it via \include{filename}

Most GUIs can even hide these details. So please don't worry about the LaTex side of things ...

I am sure you are absolutely right.

In my experience, I have found that it is more effective to assume things are difficult, and find out that they're easy, rather than assume things are easy only to find out that they are horribly difficult!

I've faced worse challenges. . . . :wink:

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: Fork manual into user guide and installation guides

Postby wrench11062 » Fri Nov 30, 2012 6:36 am

HAY!
Here!!! Here!!!
Great idea, Linux/unix is the rule, but not all the rule..............
It is wise to to open the doors to all the other ops sytems....... How are all the other ops systems gonna Learn..............
I used Slackware in the 2k...... ran a front end for FIDONET.. 1:109/233, I just wanna make Win7 work aok, and I'm gett'n close, but the Linux/unix code is
not gonna let it happen 100%..... Besides.... The road to learn is hard as it is. Make it a tad bit more easier k?
I would suggest a an ops system area,forum,board,sub-board etc,echo as the old timers use to say....before p-4 etc............

I see that using unix type operating system would make all equal, but we are not cause of $$$$$$$$$$$$,.
I suggest Tolerance.
:wink:
Prime example of what happens when you put a monkey in a capsule full of buttons and switches...Now, wheres that damn banana?...
User avatar
wrench11062
 
Posts: 55
Joined: Sat Mar 24, 2012 1:55 am
Location: Los Angeles Ca. 1 nm east of KLAX 24R
Callsign: Tchaser/CrshLdr
Version: Git 64Bit
OS: Win7 64bit

Re: Fork manual into user guide and installation guides

Postby Hooray » Fri Nov 30, 2012 7:04 am

wrench11062 wrote in Fri Nov 30, 2012 6:36 am:I would suggest a an ops system area,forum,board,sub-board etc,echo as the old timers use to say....before p-4 etc............
I suggest Tolerance.


As a matter of fact, we are absolutely tolerant, such a "forum, board, sub-board" has been in existence for many years actually: viewforum.php?f=11
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: Fork manual into user guide and installation guides

Postby jharris1993 » Fri May 03, 2013 8:55 pm

I'm back!

Stuart,

I have tried fussing around with some LaTeX stuff and (so far) it seems to require witchcraft to install or use, and though I can be a very patient man, I really don't have much patience for voodoo when it comes to using an application.

I have tried to find a WordPerfect X5 to LaTeX conversion program, but the only one out there died with v7 - a rather dated version at this time. I tried it and it had significant troubles with large parts of the document.

I also tried converting the document into HTML, RTF, and Word formats, and it shot the source formatting all to hell.

So far, the only output formats I can find that appear to work are WordPerfect file, (.wpd), and searchable PDF (.pdf). The searchable PDF is generated by BroadGun's PdfMachine virtual printer device, which produces some of the most accurate PDF output I have seen.

Are either of these formats usable?

If either are, I would propose a test:
I have a fairly large document containing illustrations, formatted text, and such-like that I could send to you. Of course it is totally un-related to FG (It's a HUD housing "how-to-bid" document). However I was thinking you could make a trial run of a "manual", try to incorporate that document into it, and forward the completed document back to me for my own examination. This way we could work out a lot of the "mechanical" kinks prior to my actually beginning document creation - and spending significant time going down the Bogus Path! :roll:

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: Fork manual into user guide and installation guides

Postby Hooray » Fri May 03, 2013 9:32 pm

jharris1993 wrote in Fri May 03, 2013 8:55 pm:I have tried fussing around with some LaTeX stuff and (so far) it seems to require witchcraft to install or use

On Windows, you'll probably first want to download/install MiKTeX: http://miktex.org/download or TexLive: http://www.tug.org/texlive/
And then download/install an IDE/editor like TexNicCenter: http://www.texniccenter.org/resources/downloads/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: 11100
Joined: Tue Mar 25, 2008 8:40 am

Re: Fork manual into user guide and installation guides

Postby jharris1993 » Fri May 03, 2013 10:24 pm

Is there something like BaKoMa Tex that is not $140 a pop? I paid less than that for a full-up version of WordPerfect X5 Professional!

I gave up editing text in gibberish back when WordPerfect 5.3 for Windows came out in the '90's I can do better than that on a manual typewriter. . . . . :roll:
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: Fork manual into user guide and installation guides

Postby Hooray » Sat May 04, 2013 12:48 pm

the packages I mentioned are free and open source.
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: Fork manual into user guide and installation guides

Postby Thorsten » Sat May 04, 2013 5:21 pm

I gave up editing text in gibberish back when WordPerfect 5.3 for Windows came out in the '90's I can do better than that on a manual typewriter. . . . .


LaTeX is a professional typesetting tool, not a word processor. Which means you first have to accept the workflow, which in turn means that you don't have a what-you-see-is-what-you-get environemnt, but you have to trust the program to do the layout for you according to the specified format header, you just specify for each text element what it is, not how it is positioned.

You start realizing the power of TeX when it costs you less than 10 minutes to change the layout of an 120 page a4 document to a 230 page book with professional quality typesetting in both variants. Or when you want Hebrew text with reversed writing direction embedded into an English text. Pretty much all scientific books have LaTeX typesetting. It is an order of magnitude more powerful than word processors can deliver.

I typically write LaTeX using a default ascii editor and simply compile the text from commandline later on.

In the event, you can probably write all you want to say into a *.txt document and leave the formatting to someone who knows how to do it - given that you probably largely have plain text blocks, that's simplest.
Thorsten
 
Posts: 9549
Joined: Mon Nov 02, 2009 8:33 am

Re: Fork manual into user guide and installation guides

Postby Hooray » Sat May 04, 2013 5:52 pm

Thorsten wrote in Sat May 04, 2013 5:21 pm:In the event, you can probably write all you want to say into a *.txt document and leave the formatting to someone who knows how to do it - given that you probably largely have plain text blocks, that's simplest.


Agreed, and Stuart already offered to accept pretty much ANY format - with some experience (and/or the right tools), it doesn't really matter if it's just plain text - LaTex can be quickly formatted using a LaTex editor like Lyx for example:

LyX is a document processor that encourages an approach to writing based on the structure of your documents (WYSIWYM) and not simply their appearance (WYSIWYG).

Image
http://www.lyx.org/Download
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: Fork manual into user guide and installation guides

Postby jharris1993 » Sat May 04, 2013 8:20 pm

Thorsten wrote in Sat May 04, 2013 5:21 pm:
I gave up editing text in gibberish back when WordPerfect 5.3 for Windows came out in the '90's I can do better than that on a manual typewriter. . . . .


LaTeX is a professional typesetting tool, not a word processor. Which means you first have to accept the workflow, which in turn means that you don't have a what-you-see-is-what-you-get environemnt, but you have to trust the program to do the layout for you according to the specified format header, you just specify for each text element what it is, not how it is positioned.

You start realizing the power of TeX when it costs you less than 10 minutes to change the layout of an 120 page a4 document to a 230 page book with professional quality typesetting in both variants. Or when you want Hebrew text with reversed writing direction embedded into an English text. Pretty much all scientific books have LaTeX typesetting. It is an order of magnitude more powerful than word processors can deliver.


(Also referencing the "Operators with Limits" section just above this reply.)

I, (usually), never want to do anything that complicated. WordPerfect does wonderfully as a typesetting tool for everything I need it for.

What I want to do is get something that will let me get it reasonably close to what I think it should look like, toss it to you in a format you can use, (LaTeX if possible), and let you tweak to your hearts content.

As I read on the web somewhere last evening - "LaTeX isn't a word processor, or even a text editor, it' a compiled "programming language" that is used to typeset documents."

My beef with LaTeX right now is that I just don't have the time to fuss with it. I want to give you something formatted better than a plain-text ASCII document, but I'd like to get it to you sooner than the months and months it would take me to learn LaTex to a reasonable degree of proficiency.

I'm not really knocking LaTeX per-se, it's just frustration peeking through.

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: Fork manual into user guide and installation guides

Postby jharris1993 » Sat May 04, 2013 8:37 pm

We may have a winner!

I just discovered that there is a Libre Office extension - Writer2Tex (or something like that) - that takes Libre Office "Writer" docs (Or other OOD formatted docs) and converts them into LaTeX.

Supposedly, it does a reasonably good job too. So this way I can have my cake and eat it too.

What I can do is start fussing with the Windows installation, based on what we have now, document the installation process, and send you both a LaTeX source file and a .pdf of what I think it should look like. If you want - while you are fussing with the LaTeX, you can publish the .pdf up on the site so that people who need it can grab it right away.

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

Next

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest