Board index FlightGear Development Documentation

Using the wiki to maintain the manual / PDF tutorials

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

Re: Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Wed Nov 21, 2012 4:31 pm

AndersG wrote in Wed Nov 21, 2012 3:47 pm:
jharris1993 wrote in Wed Nov 21, 2012 3:16 pm:Stuart: Is there any way for \LaTeX to implement a "change marker"? (i.e. something like a black bar in the margin to indicate the parts I touched?) IMHO, this would greatly facilitate you migrating my changes into the mainline manual.


The tool you are looking for is probably diff - that is, exploring the changes is usually best done on the document source and not on the compiled output. With a very small amount of discipline (mainly keeping the line length in the source short) LaTeX documents work very well with version control systems.

Anders,

Point noted, though I am not sure we're both on the same page.

In my case, I already know what I changed since I am the one that changed it. Also remember that this is not being done on a 'nix box, so the use of standard 'nix utilities is not an option at the present time.

What I am talking about is a way to signal Stuart that I have made changes in the document at specific places.

Or, is submitting my files back into Git sufficient? (i.e. Will that notify Stuart that changes have been made at particular points?)

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: Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Wed Nov 21, 2012 5:00 pm

AndersG wrote in Wed Nov 21, 2012 3:47 pm:The tool you are looking for is probably diff. . . . .

I'd like to make something of a side-comment on, (what appears to me), to be an implicit assumption that everyone who works on FG, especially the FG doc's, works in some flavor of 'nix.

Likewise, one of the main topics is lowering the barriers to entry.

I believe that assuming everyone works in 'nix, or even has a clue about 'nix and it's inner workings and commands, is an unwarranted, and inherently limiting assumption.

In point of fact, one of the very reasons I am eager to contribute to FG in whatever way I can is to help bring a more Windows-centric viewpoint to the table here to help offset the highly 'nix centric assumptions that seem to prevail.

Since there are innumerably more Windows installs than 'nix installs, making things usable - and understandable - by the Windows crowd will only help spread the adoption of Flight Gear as a viable alternative to the other - payware - flight sim's out there.

Re: making the manual more easily understood.

I would like to suggest that making the manual try to serve two masters - both 'nix and Windows - only serves to make everything more difficult to read and understand.

How difficult would it be to fork the manual into two editions - a purely 'nix edition and a purely Windows edition? This way each manual can concentrate its efforts on making a particular platform's installation as easily understood as possible. I would be particularly interested in helping establish a more easily understood "Windows" version.

Thanks for all the help!

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: Using the wiki to maintain the manual / PDF tutorials

Postby Hooray » Wed Nov 21, 2012 5:11 pm

stuart wrote:Hooray - While editing the wiki is more immediate than contributing to The Manual, surely that benefit would be lost by the need for every change to be reviewed by a maintainer before it went live?


Actually, the way how WP handles this is by offering "stable/approved versions" and versions that are still pending review. I REALLY suggest to look at wikipedia to see how it works there. Basically, the contributions are applied to a "branch" of the documentation directly, but people are by default only shown certain versions of the docs.

(Thanks for the offer of reviewing, but I'd want to retain editorial control so I'd still need to approve every change).

Which is fair enough, as far as I know, you and others already have admin privileges ... and it would be easy to add other manual maintainers as wiki admins. I wasn't trying to become a manual maintainer at all. That said, it's sort of funny how some people are obviously more concerned about the quality of the docs meanwhile than the quality of our source code in the first place ? :D

stuart wrote:I've yet to be inundated with changes to the extent that this won't scale.

Well, look at the "automation vs. manual work" debate that we are having in the original "market research" thread you started ... as long as people volunteer to handle something (and as long as they're responsive), scaling is obviously not an issue. But merge requests taking weeks or even months to be reviewed is hardly appealing, even if that should "only" mean that merge requests for the core don't get reviewed in time.
So, I'd be careful here ... the wiki scales is so well because of the number of contributors who don't block each other when working on something.

Finally, I am too familiar with the project to expect changes anytime soon ... even the really good ideas have often taken half a decade to be recognized as such :D

jharris1993 wrote in Wed Nov 21, 2012 4:31 pm:What I am talking about is a way to signal Stuart that I have made changes in the document at specific places.



In addition it may help to send a heads-up to the devel mailing list or directly via eMail/PM (forum).
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: 11329
Joined: Tue Mar 25, 2008 8:40 am

Re: Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Wed Nov 21, 2012 6:03 pm

Hooray wrote in Wed Nov 21, 2012 5:11 pm:That said, it's sort of funny how some people are obviously more concerned about the quality of the docs meanwhile than the quality of our source code in the first place ? :D

As a Software QA Engineer of many years standing, I am absolutely ferociously concerned about the quality of the source code. However, my ability to contribute to the source code is limited and my ability to contribute to the documentations is much better, so which do you think I should choose?

Hooray wrote in Wed Nov 21, 2012 5:11 pm:But merge requests taking weeks or even months to be reviewed is hardly appealing, even if that should "only" mean that merge requests for the core don't get reviewed in time.

This particular issue - merge requests to the software itself or apps surrounding it - taking inordinate amounts of time to occur, if ever, is a theme I have seen raised again and again and again on these very fora. Though this is obviously out-of-scope on a documentation forum, it sounds like something that the development team should begin working on in dead earnest, if they are at all concerned with the level of participation in FG by developers.

Hooray wrote in Wed Nov 21, 2012 5:11 pm:
jharris1993 wrote in Wed Nov 21, 2012 4:31 pm:What I am talking about is a way to signal Stuart that I have made changes in the document at specific places.


Hooray,

Please look at my previous post. Not everyone is set up to work with the 'nix tools natively. In order to help expand even the possibility of others contributing to the manual, we need to make sure that there are no platform-specific barriers to entry.

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: Using the wiki to maintain the manual / PDF tutorials

Postby Hooray » Wed Nov 21, 2012 6:54 pm

jharris1993 wrote in Wed Nov 21, 2012 6:03 pm:Please look at my previous post. Not everyone is set up to work with the 'nix tools natively. In order to help expand even the possibility of others contributing to the manual, we need to make sure that there are no platform-specific barriers to entry.


Sorry, I'm not sure if you are asking for help here or if you are offering help?
If you don't understand the concept of merge requests via git, they are well explained actually (wiki/gitorious).
And there's nothing unix-specific. In fact, there are great Windows GUIs available for git, including some cross-platform stuff.

It's kinda moot to suggest I didn't read or understand your previous posting, because I actually agreed with your earlier points completely, we just didn't agree on the channel to be used here. But for now, there's a "standard" channel, i.e. gitorious -> merge requests -> heads-up notice via issue tracker/mailing list/forum.

All that said, there are excellent wiki platforms available which support not only latex but also git as their backend.
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: 11329
Joined: Tue Mar 25, 2008 8:40 am

Re: Using the wiki to maintain the manual / PDF tutorials

Postby AndersG » Wed Nov 21, 2012 9:24 pm

jharris1993 wrote in Wed Nov 21, 2012 4:31 pm:What I am talking about is a way to signal Stuart that I have made changes in the document at specific places.


Anyone receiving your file can use diff to see what you have changed by comparing to the version you started from. A diff tool comes with most version control systems (e.g. git) and I think you will find that even Word can do it (I have only used Word's diff tool between actual .doc documents myself, though). When I work on text or code I often use a diff tool (usually from the version control system since I tend to use one for most content) to verify what I have changed (e.g. to discover accidental pastes or deletes).

Btw. I have several colleagues that use Word to edit LaTeX source files - the spell and grammar checking in Word is pretty good - just make sure to save the file as plain text again and resist the urge to write whole paragraphs as single lines (which IMO is the main difference from writing "normal" Word documents). You only need a LaTeX installation to produce and view the typeset result - to produce the text content (which at least in my writing is the wast majority of the effort) you only need a text editor (e.g. Word or emacs or...).

/Anders
Callsign: SE-AG
Aircraft (uhm...): Submarine Scout, Zeppelin NT, ZF Navy free balloon, Nordstern, Hindenburg, Short Empire flying-boat, ZNP-K, North Sea class, MTB T21 class, U.S.S. Monitor, MFI-9B, Type UB I submarine, Gokstad ship, Renault FT.
AndersG
 
Posts: 2442
Joined: Wed Nov 29, 2006 9:20 am
Location: Göteborg, Sweden
Callsign: SE-AG
OS: Debian GNU Linux

Re: Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Wed Nov 21, 2012 9:34 pm

Hooray wrote in Wed Nov 21, 2012 6:54 pm:Sorry, I'm not sure if you are asking for help here or if you are offering help?

How about (C) - All of the above! :wink:

  • I want to help. I am especially interested in making sure that the "Windows" side of things is well represented here.
  • I also need help, as I have never worked in a LaTeX/Git based environment before

If you don't understand the concept of merge requests via git, they are well explained actually (wiki/gitorious).

I understand the concept of merge requests with a CVS system, but I have had no real "stick time" flying one. Ergo, I will probably need an instructor pilot, at least at the beginning.

In fact, there are great Windows GUIs available for git, including some cross-platform stuff.

Do tell! May I have links to this stuff please?

I still have the lumps on my head from my previous searches on just that issue - all I found were tools that were primarily command-line tools that required the co-installation of a mini-'nix within Windows. And though I am not specifically excluding that as an option, I feel that there are more productive ways for me to spend my time. For example, arguing with you and posting multiple chapter "essays". ( :lol: )

Seriously, I was, and am, more interested in verifying that I can actually handle the LaTeX files in Windows, and return usable files to Stuart, before I jump through the rest of the hoops, since if I cannot properly handle LaTeX using the Windows tools I have, then the rest of this is moot.

By the way, this is why I am so interested in getting at least SOMETHING in native LaTeX format for me to work with. I want to make some kind of change to it, even if it's just a "bogus" change for testing purposes, so that I can verify my LaTeX editor setup is valid. (Psst! Stuart!! Hint! Hint!)

It's kinda moot [make that read, "obnoxious"?] to suggest I didn't read or understand your previous posting, because I actually agreed with your earlier points completely, we just didn't agree on the channel to be used here.

Ahhh!

A thousand apologies if I seemed a bit gruff, (or obnoxious), there. Not intended, but it really DID look like you had completely "bleeped" over my other posting about windows inclusion. I also hope that all of you can see - behind my foot-stomping - that the reason behind this is because I am truly passionate about providing help in this way. And the apparent roadblocks are frustrating to the extreme.

But for now, there's a "standard" channel, i.e. gitorious -> merge requests -> heads-up notice via issue tracker/mailing list/forum.

Thanks!

If I can find some way of managing Git without having to constantly flip back-and-forth between one OS and the other, that would be great!

:idea: Then again, there's always a VM under Win-7 with 'nix in it. :idea:

(and why do I see the simple solutions so late in the game? :bonk head against brick wall: :roll: )

That would solve a great many issues. I could "git" what I need, use the windows tools I prefer, and then "git"-it right back to you. A VM is easily enough done and there's no real risk of unrecoverable damage to my base system, so I should get cracking and give this idea a try.

Any particular flavor you folks recommend? Right now I'm messing with Ubuntu and Mint.

What say ye?

Jim (JR)

p.s. I'd still like to see the links to the native Windows Git tools - if for no other reason that it might be possible to write a "how-to" on the subject of Windows, LaTeX and Git.
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: Using the wiki to maintain the manual / PDF tutorials

Postby Hooray » Wed Nov 21, 2012 10:02 pm

jharris1993 wrote in Wed Nov 21, 2012 9:34 pm:p.s. I'd still like to see the links to the native Windows Git tools - if for no other reason that it might be possible to write a "how-to" on the subject of Windows, LaTeX and Git.


There are tons of GUI clients available for windows meanwhile, some of the more often recommended ones being "MSysGit" and TortoiseGit. Depending on your IDE (Eclipse/Netbeans), you may even have integrated git support.
In general, see: http://wiki.flightgear.org/FlightGear_G ... a_from_Git


Yes: The VM is an option, but absolutely NOT necessary at all:
Again, there's really NOTHING Unix/Linux-specific here: There are excellent GUI tools available for both, using git and editing LaTex files.

http://code.google.com/p/texworks/downloads/list
http://tex.stackexchange.com/questions/ ... itors-ides

PS: RE: "obnoxious": not at all ... I just also got the impression that you didn't read my responses, because you repeated questions that I considered addressed already, such as Windows-only GUI editors for Tex sources ...

Regarding the whole browser-based tex-editing debate, see for example: http://www.scribtex.com/
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: 11329
Joined: Tue Mar 25, 2008 8:40 am

Re: Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Wed Nov 21, 2012 10:29 pm

Hooray wrote in Wed Nov 21, 2012 10:02 pm:
jharris1993 wrote in Wed Nov 21, 2012 9:34 pm:p.s. I'd still like to see the links to the native Windows Git tools - if for no other reason that it might be possible to write a "how-to" on the subject of Windows, LaTeX and Git.

There are tons of GUI clients available for windows meanwhile, some of the more often recommended ones being "MSysGit" and TortoiseGit. Depending on your IDE (Eclipse/Netbeans), you may even have integrated git support.
In general, see: http://wiki.flightgear.org/FlightGear_G ... a_from_Git

Hmmmm. . . . .

I just recently installed CodeBlocks so that I can begin working on C/C++. I'll have to check that.

Yes: The VM is an option, but absolutely NOT necessary at all:
Again, there's really NOTHING Unix/Linux-specific here: There are excellent GUI tools available for both, using git and editing LaTex files.

http://code.google.com/p/texworks/downloads/list
http://tex.stackexchange.com/questions/ ... itors-ides

Actually, some "flight time" using virtual machines won't do me any harm, especially from a sysadmin point of view. The nice thing about the VM idea is that this does not exclude investigating a "pure" Windows approach either. Installing a mini-'nix on my base system could well skew any review of a Windows based tool. Placing all the 'nix stuff inside a VM provides both access and isolation.

PS: RE: "obnoxious": not at all ... I just also got the impression that you didn't read my responses, because you repeated questions that I considered addressed already, such as Windows-only GUI editors for Tex sources ...

Or, maybe, I did not understand the answers as clearly as you did. From the point-of-view of someone who has been doing this since the time of Moses, this stuff is all trivially easy. From the nugget (noob) point of view, it's all hieroglyphics. I am also assuming that what is difficult for me - and I have used a computer for longer than the last five minutes :) - is very likely going to be difficult for others as well. Perhaps an explanation from an external viewpoint would be more effective?

Regarding the whole browser-based tex-editing debate, see for example: http://www.scribtex.com/

You're right. I'll go check that out. If nothing else, it will be both entertaining and informative.

In any event, both your patience and your help is gratefully appreciated! (And that applies to everyone else here too.)

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: Using the wiki to maintain the manual / PDF tutorials

Postby stuart » Thu Nov 22, 2012 10:59 am

Hi JR,

A couple of quick comments:

If you're keen to make some test changes with Latex without the overhead of understanding git right now, you can download the latest source code directly from https://gitorious.org/fg/getstart/archi ... all/master

You can then just email me the files you update. I can easily diff them against the actual source and apply your changes.

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

Re: Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Thu Nov 22, 2012 6:30 pm

Massive thanks to all of you!
Last edited by Gijs on Thu Nov 22, 2012 6:36 pm, edited 1 time in total.
Reason: No useless quoting please.
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

Previous

Return to Documentation

Who is online

Users browsing this forum: No registered users and 0 guests