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.

Using the wiki to maintain the manual / PDF tutorials

Postby Hooray » Mon Nov 19, 2012 5:10 pm

Taken from: Subject: Help needed - market research for FG

Bjoern wrote:
stuart wrote:7)"offer wiki-based tutorials," We have a series of tutorials in the FG Manual on flying aircraft. Or are you thinking about how to use particular features?

Move the tutorials from the .pdf to the wiki.
This would enable quick adaption to possible new features by the community and it would get rid of having a PDF reader open for reading up.
While certainly great for other uses, I find any PDF reader tedious to use for large, text based files. A wiki with its clear division into articles, cross-linking and a usable "search" function is much more usable.


I really have to agree with this. This is even though I'm familiar with LaTex, git and gitorious: I find it MUCH more *direct* to simply use the wiki to contribute a fix/change/improvement than going through the hassle of getting my changes committed to the manual via the LaTex route. I know all the pro & contra arguments here, given that this has been discussed on the wiki already (and rejected). However, let's keep in mind that the wiki our main source for new documentation, which is because it's so simple to contribute to it.
And there are solutions to import LaTex into docbook and use a wiki-based editing environment, that would allow all contributors to suggest changes.

Just by taking a look at the wiki, you'll see that we've had a number of users (wiki contributors) who requested such a change.

For reference, see:
http://wiki.flightgear.org/index.php?ti ... i_software
http://wiki.flightgear.org/index.php?ti ... PDF_Export
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: 11292
Joined: Tue Mar 25, 2008 8:40 am

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

Postby jharris1993 » Tue Nov 20, 2012 12:02 am

Hooray wrote in Mon Nov 19, 2012 5:10 pm:I really have to agree with this. This is even though I'm familiar with LaTex, git and gitorious: I find it MUCH more *direct* to simply use the wiki to contribute a fix/change/improvement than going through the hassle of getting my changes committed to the manual via the LaTex route. I know all the pro & contra arguments here, given that this has been discussed on the wiki already (and rejected). However, let's keep in mind that the wiki [is? should become?] our main source for new documentation, which is because it's so simple to contribute to it.
And there are solutions to import LaTex into docbook and use a wiki-based editing environment, that would allow all contributors to suggest changes.


While I agree with this in spirit, and while I have absolutely no objection to documentation being available within the wiki; I would oppose, in the strongest terms possible, the concept of migrating the documentation entirely to the wiki and nowhere else. I would also object strongly to allowing the documentation to be a free-for-all in the exact same way I would strongly oppose any effort to make the projects source code a free-for-all. And for the exact same reasons.

In the most literal sense of the word, documentation is code in the exact same way that some nasal or C++ procedure is code, and it needs to be maintained, handled, tracked, versioned, critically reviewed, and ultimately approved or rejected in the same way that any well organized software project is run. The only difference between a "software" project in C++ and a "software" project in English, is that the C++ code is documentation to the computer describing exactly how it is to function - and English code is documentation to the end-user on how the software has been designed to function and how to use it effectively.

A properly maintained documentation project is both easier to manage, and easier to "port to other systems" (i.e. translate to other languages), as the need arises.

Yes, getting source code committed to the source repository is a "hassle". But it is a necessary hassle to prevent the software from falling into utter chaos. In the exact same vein, it is also a "hassle" to get documentation committed to it's source repository. But this is absolutely necessary for exactly the same reason that source code repositories are important, lest the documentation itself fall into utter chaos.

I hope to work constructively with all of you to improve both the structure and quality of our documentation development environment, knowing that the quality of the documentation would improve as well.

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 Bjoern » Tue Nov 20, 2012 1:14 pm

jharris1993 wrote in Tue Nov 20, 2012 12:02 am:...


I think you're putting a bit too much emphasis on the documentation.
For me, code documentation is best located directly within the code or very close to it - a manual or wiki would not even count.

We were mostly talking about getting rid of the .pdf manual, which, claiming to know the average flightsimmer, one or two people read. At best. And only if they're new to flightsimming and slightly drunk.
Do a barrel roll!
User avatar
Bjoern
 
Posts: 384
Joined: Fri Jan 06, 2012 10:00 pm
Location: Nearest: THF
Version: Next
OS: ArchLinux, Win 7

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

Postby stuart » Tue Nov 20, 2012 2:26 pm

Jim - 100% agree with all you've said here. There is absolutely a place for the wiki, but the official manual needs proper editorial control. Note that we've added text from the wiki to The Manual in the past, but it needs to be done in a controlled manner.

Bjoern - We're talking here about end-user documentation rather than code documentation (which if it exists at all is in comments in the code). I disagree that no-one reads the PDF. It's also worth pointing out that the manual is also output as HTML from the LaTex source (see here: http://mapserver.flightgear.org/getstart/)

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

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

Postby Hooray » Tue Nov 20, 2012 4:11 pm

Also agreed with all that Jim said - but there's obviously a misconception here, the point was never to replace the manual or to make it editable by anybody - the point was to LOWER the entry barrier. Quality assurance is important, but funnily, wikipedia manages to do that just well using the same wikimedia software that we use. Editorial control is a NO-BRAINER using wikimedia, because articles can be LOCKED and STABLE VERSIONS can be shown by default, where all modifications would require review. That's EXACTLY how WP handles the whole issue. And I'm sure other wiki admins would agree here (Gijs/Johan): We tend to review ALL edits anyhow, so it would be trivial to either accept modifications or request further changes before accepting them. Exactly like gitorious merge requests work actually.

This kind of workflow is supported by wikimedia "out of the box" and we shouldn't use "quality control" as an excuse to make contributing to the manual harder than necessary.
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: 11292
Joined: Tue Mar 25, 2008 8:40 am

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

Postby stuart » Tue Nov 20, 2012 8:23 pm

Hi Hooray,

That's very interesting - I wasn't aware that wikimedia could be used that way. Though I was aware of the ability to lock articles, I didn't know that it provided the ability for admins to review and apply submitted changes.

However it still doesn't help us as the source-code for the manual is in LaTex and I don't see an alternative that produces a properly typeset PDF with multilingual support. I've looked at the PDF output from wikimedia in the past and wasn't impressed as it didn't seem to offer a "proper" book form in the way that our Manual is currently produced.

That said, I'm more than happy for people to draft changes on the wiki and then ask me to convert them to LaTex. I've always been quite happy to accept updates in whatever form they take. I think tutorials are an excellent way for people to write nice self-contained piece of documentation, without needing to be constrained by the current manual structure. They would be very easy to integrate into the manual.

Personally, I'm not convinced that the technical barriers to entry are what is stopping people from improving the existing manual. Rather, people prefer to write their own does outside of the structure the manual, or want to suggest a completely new form of manual (using whatever CMS, format they happen to favour). Just like with aircraft and VAs, everyone would much rather create something from scratch than maintain an existing resource.

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

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

Postby Hooray » Tue Nov 20, 2012 8:55 pm

stuart wrote in Tue Nov 20, 2012 8:23 pm:That's very interesting - I wasn't aware that wikimedia could be used that way. Though I was aware of the ability to lock articles, I didn't know that it provided the ability for admins to review and apply submitted changes.


http://en.wikipedia.org/w/index.php?tit ... ction=edit => This page has been semi-protected so that only autoconfirmed users can edit it.

For details, see:
http://en.wikipedia.org/wiki/Wikipedia: ... _revisions
http://en.wikipedia.org/wiki/Wikipedia: ... protection

However it still doesn't help us as the source-code for the manual is in LaTex and I don't see an alternative that produces a properly typeset PDF with multilingual support. I've looked at the PDF output from wikimedia in the past and wasn't impressed as it didn't seem to offer a "proper" book form in the way that our Manual is currently produced.


There are docbook backends available that can deal with LaTex properly.

Personally, I'm not convinced that the technical barriers to entry are what is stopping people from improving the existing manual. Rather, people prefer to write their own does outside of the structure the manual, or want to suggest a completely new form of manual (using whatever CMS, format they happen to favour).


That's a long-standing rumour, which was also added to the wiki by "someone" a while ago. I don't think that's true: I have never contributed to the manual, and I have never published tutorials on separate website. Yet, I'm a fairly active wiki contributor - even though I do know latex/git/gitorious/merge requests etc

And I know that this applies to many other wiki contributors: They contribute to the wiki because it's fast and simple, it doesn't require any complicated procedures - it's just a registration, and you can start editing right away.

Now, let's be honest here: If people who are perfectly familiar with the process and tools involved still consider the wiki more direct, what about the users who are not familiar with git, latex etc ?

I'm not trying to convince you, but I'd suggest keep the outside perspective in mind - it's far too simple to suggest that people have a tendency to create their own stuff rather than contributing to a shared resource. But it's just that, a knee jerk reaction ...

I think the wiki has proven that this is not generally the case. I don't know if you were around when the current wiki was suggested or not... but we actually had a different wiki previously (via seedwiki.com).

And it also had a number of users willing to contribute there. Back then, the manual maintainer back then also suggested that nobody would be interested in contributing to "The Manual", and even considered the wiki competition.

Fast forward half a decade later, the wiki has proven to be the single most successful source of documentation for FG, which is funnily not primarily maintained by FG core developers, but by end users - and which is regularly also being used as a content source for the manual or the official website meanwhile.

It's important to keep the whole picture in mind ... not too long ago, Curt even suggested that the wiki shouldn't compete with the official website, simply because it's now also CMS-driven, and content is intended to be published there.

But at the end of the day the only thing that matters is the number of contributors we have, QA is a no-brainer - and I really don't mind volunteering to handle locking/reviewing/approving articles.

Don't get me wrong, I don't think this is going to change anytime soon, after all we know how the project works ... and there's lots of inertia involved here. Including people and politics obviously, some of them very outspoken ... however, let's keep in mind how many proposals for "wikis", "issue trackers", "website improvements" we've had over the years for example, or how many requests for FGData/FGAircraft to be split up - these all boil down to optimizations of the project, and to make it more tangible to end users and new contributors.

As experienced users/contributors/developers we are obviously in a really bad position to judge which improvements/optimizations are important to address the needs of less experienced users. But we can at least try to learn from our past and draw the right conclusions.
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: 11292
Joined: Tue Mar 25, 2008 8:40 am

Using the wiki to maintain the manual / PDF tutorials

Postby jharris1993 » Wed Nov 21, 2012 2:31 am

Hello everybody, and have a happy Thanksgiving!

OK, now that I seem to have started a raging forest-fire, let me pour some more gasoline (petrol) on it just to keep things going. :D

I will apologize in advance if this seems a bit long; and no, I am not trying to get on a "soap-box" as was mentioned once before, however I do want to let all of you know what I feel, and why I feel this way.

1. Wikis and the review/commit cycle:
(a) As far as I know, having contributed to Wikipedia, (I am assuming that this is what "WP" means), entries can be, (and are), made by anyone, registered or otherwise, and are committed immediately. There is apparently some system in place for rapid critical review of new entries and things do get modified, backed-out, or whatever'd, but the commit process is (AFAIK) immediate.

(b) Having to depend on an after-the-fact review and correct cycle is not something I'd want to impose on an already overburdened staff. Likewise, one of the attractions of using a Wiki is the ability to edit, commit, and see results immediately; so a post-moderate-commit cycle goes "against the grain" as far as a Wiki is concerned.

2. Lowering the barrier to entry:
(a) Obviously, getting more people involved is a Good Thing. The more the merrier. And yes, even *I* will admit that a variety of viewpoints is good. :lol:

(b) Point conceded to the person talking about editing the manual. It is a non-trivial task for more than one reason.

In my case, I have been working on this for several days now. Though I believe I have finally, (finally!), found a tool that will let me do the actual LaTeX, ( \LaTeX :) ) editing, there seems to be no way to work with Git short of installing a mini-Unix on my system. (The whys and wherefores of why I desire to do most of this within Windows, though seemingly masochistic, is an entirely separate discussion in itself, which I will be glad to discuss within a separate thread, or off line.)

The other side of this is that LaTeX is no longer the only reasonable typesetting tool available to the PC community. As heretical as this may sound to many of you, I would beg to suggest that there is very little that you can do in LaTeX that I cannot do using Word Perfect and pdfMachine. Even though I am not conversant in the Mac world, I am sure that there are many capable document processing/typesetting programs available there that would also give LaTeX a run for it's money.

In the same vein, if everyone is so eager to lower the barriers to entry, so to speak, why is the manual written in a platform-limiting format like LaTeX? It would seem that a more platform agnostic documentation standard would be a better choice. Open Doc, (or whatever Libre Office / Open Office uses), Rich Text, HTML, or something else that is more platform agnostic than LaTeX would seem to be a better way to invite participation.

Q.E.D. LaTeX itself may be on of the largest reasons why people do not wish to contribute to the FG Manual.

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 2:43 am

(Part 2)

My opinion on the various user models and the varying documentation venues:

Obviously, there are more ways to do this than one. There are those of us who would love to take the existing structure and improve it. Then there are those who want to start from scratch.

I do not claim to be "typical", but I will also say that if I represent one way of doing things, and I am here being vocal about what I like and dislike, than I have to assume that I am not the ONLY one who feels this way.

In my own personal opinion, I like things neatly packaged and ready-to-go. Even though I have a 100+mbit broadband connection, I really don't like the idea of external dependencies. When I downloaded the BoKaMo LaTeX editing tool, I made a particular point of going through the libraries and downloading ALL the BoKaMo documentation to my local system. If I could grab a complete copy of the entire present-date Git source files for the FG manual, I would have them here too, where I could edit them off-line and then re-submit my corrections.

Why?

First:
Being forced to stop what I am doing and go find something on a Wiki or other online documentation, while I am in the middle of trying to do something else, is frustrating to the extreme.

I prefer to have the application open in one window and the necessary documentation for it open in another window. This way if I encounter a problem while, (for example), trying to install aircraft or scenery, I can flip right to the other window, scroll down through the Manual's TOC to the section I want, get the information I need, and get things going.

Likewise, anyone who has used a Wiki, (or a Forum), more complex than a listing of the alphabet knows that the ability to effectively search for content is not something that can be taken for granted. Even if you know the correct terminology, (or especially if you know the correct terminology!), finding the answers you need is often a daunting task.

Second:
IMHO external dependencies, (a network connection for example), represent potential points-of-failure. If I am not near a reasonably fast network connection, (and yes, that does happen fairly frequently as I travel a bit), and I depend on the Wiki for my documentation, or I depend on a network connection for some other important resource, then I am hozed.

In the same way, not everyone has a multi-gigabit broadband connection. I know a number of people who suffer with DSL connections that are not much faster than dial-up. Or if they are faster than dial-up, they aren't that much faster. Forcing people in situations like this to suffer while they wait for their internet connection to catch up with their documentation request seems cruel, bordering on sadistic.

For both of these two reasons, purely on-line documentation - even if it is on-line HTML documentation - annoys me to the extreme. I like to see, (and would wish to offer), a choice of either the on-line doc's or something that can be taken off-line, be it a monolithic HTML document, a PDF (which is my preference), or something else.

Third:
I divide the end-user community for FlightGear into two very broad categories: Those who are really serious about what they're doing, and those who just want to have fun.

Now, I am not saying that either one of these user models is better, or worse, than the other. But when I commit time to something like this, even if it is only just downloading and using the application, I take the time to read, thoroughly, the accompanying documentation.

Maybe I do it in bite-size chunks; read some, try something, read more, try something else, etc., or maybe I read the manual cover-to-cover and follow the external references before I start. In either case I like to have my arms around what I am doing before I do it.

And even if I am messing with FlightGear simply because I "just want to have fun", I sincerely believe that it is a matter of respect to those who have come before me and contributed their own time, effort, angst, and sweat, to read the documentation and make at least a trivial effort to understand what I am doing before I cry for help.

Finally:
The "engineer" within me wants to see a very clearly delineated "line in the sand" drawn as to the True and Authorized, canonical version of the documentation, be it the Wiki, or be it The Manual. If it's the Wiki, then say so. If it's The Manual, then say so. And, regardless of which you choose, make damn sure that they both track each other and stay up-to-date with respect to each other. Otherwise we risk confusion, angst, and a frustrated user-base.

If I were God, and I could wave my Magic Wand and make the world wonderful, I would make The Manual the canonical reference and use the Wiki for user contributions, bug-reports to The Manual, and - what I believe is the best use for something like a Wiki - the user's anecdotal information, tips, tricks, and other goodies they wish to contribute. Perhaps if this aspect of the Wiki gains traction, periodic "NOTAM's" (supplements), to The Manual can be released aggregating these useful updates where all can see and use them.

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 8:08 am

Not disagreeing with all you said. However, believe me: no matter how many people here you'll find that agree with you: FlightGear isn't going to change for the better anytime soon ... despite many good suggestions and feature requests being made every day, for years. There's lots of inertia involved here. Even if you were to post similar "essays" every day ;-)
The only way to bring such changes to FG is usually to volunteer and handle them yourself while demonstrating how this improves the project.

PS: Even though you say that you are Wikipedia contributor, you still have a misconception regarding the immediacy of editing articles, which isn't necessarily the case at all. Wikipedia simply couldn't work if all articles/pages could be directly changed.
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: 11292
Joined: Tue Mar 25, 2008 8:40 am

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

Postby Gijs » Wed Nov 21, 2012 9:37 am

stuart wrote:I've looked at the PDF output from wikimedia in the past and wasn't impressed as it didn't seem to offer a "proper" book form in the way that our Manual is currently produced.

We've looked at installing the "Collection" addon at our wiki. This allows users to select articles, place them in a certain order, add chapters/sections and have this exported to a nice PDF ( and a few other formats, eg ODF). The collection is saved and an update can be exported at any time. Alternatively you can send your "book" to Pediapress, which is a company that will print you book on real paper.

Admins can also create a predefined "Collection", so we could make a "Manual" and "Get started" collection/book. Jomo worked on a German handbook, that could act as an example for moving the manual to the wiki. This can be exported to PDF with each release, so there is an up to date manual.

Please note that the addon is currently disabled because we had some installation issues. I will give it another try today, so we can hopefully look at a working example.
Airports: EHAM, EHLE, KSFO
Aircraft: 747-400
User avatar
Gijs
Moderator
 
Posts: 9312
Joined: Tue Jul 03, 2007 2:55 pm
Location: Amsterdam/Delft, the Netherlands
Callsign: PH-GYS
Version: Git
OS: Windows 10

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

Postby stuart » Wed Nov 21, 2012 11:36 am

Gijs - Yes, I'd be interested in seeing what Collections can provide. Note that we currently autogenerate a new PDF every time there's a commit to the source. Is that possible?

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? (Thanks for the offer of reviewing, but I'd want to retain editorial control so I'd still need to approve every change).

Given that, it doesn't seem to offer more than the current approach where I accept changes in pretty much any format, will convert them to LaTex and the changes are automagically mirrored in the PDF and HTML version? I've yet to be inundated with changes to the extent that this won't scale.

Jim - There are some technical reasons why we currently use LaTex. We need to generate both PDF and HTML versions and support translations of a subset of the document (so a translator can translate a bit at a time). I'm happy to accept changes in plain text if you'd prefer not to use LaTex.

-Stuart
G-MWLX
User avatar
stuart
Moderator
 
Posts: 1455
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 » Wed Nov 21, 2012 3:16 pm

stuart wrote in Wed Nov 21, 2012 11:36 am:Jim - There are some technical reasons why we currently use LaTex. We need to generate both PDF and HTML versions and support translations of a subset of the document (so a translator can translate a bit at a time). I'm happy to accept changes in plain text if you'd prefer not to use LaTex.


Stuart,

That's a great offer - you've made before - and I appreciate. I was speaking in general.

Re: Autogen.

Point noted. Especially since the majority of the dev work seems to be done on Linux, then ported to / "make-file" compiled for, Windows. No disrespect to the DEV team, but the exact method is not really relevant to me. The fact that a Linux based source can be "automagically" ported to a new rev of the manual IS important to me. That is a 2000% convenience, where after the Autogen process all that needs to be done is to clean up the auto-generated code.

Re: Working on the manual to help Stuart:

Right now, I am having fits trying to "git" a copy of the manual from the Git repository. :wink: I still plan to work on that, but for the time being I think it would be more productive if I could actually work on improving the manual itself, rather than spending my time fussing with Git vs Windows.

N.B.: I have a Linux file server, and I'm thinking of implementing something there where it can "git" snapshots, store them somewhere, where I can "git" them, work on them, and re-submit to Stuart. However, that's not going to happen before the new year at the very least.

Is it possible for the entirety of the current revision of the Git manual sources, broken up into it's file segments, be compiled into some kind of archive, (WinRAR? tgz?), so that I could import it to a workspace on my own system and work with it there? If possible, maybe we could work out some way where I could "git" periodic snapshots of the current Git repository - maybe a script? - so that my copy and the canonical copy remain in sync. It would be great if there could be a place where this could be plopped on your server for me to "git". Maybe even a "here" script to e-mail me about updates so I can go "git" them?

Re: \LaTeX ( :wink: )

I still believe that \LaTeX went out with the steam-powered automobile. I also believe that we should get out of Afghanistan, mind our own business, that politicians should be both honest and truly representative, ( :roll: ), and that there should be Peace On Earth and Good Will Toward Men. And that pigs can fly. . . . . (Hey! That's a thought! Maybe someone who knows about making aircraft models can make a flying pig? :lol: )

However, the reality being what it is, I should make at least a small effort to support the documentation in it's native format, if for no other reason than to help reduce Stuart's workload. Also, if I am going to be doing this for more than five minutes a month, knowing something about \LaTeX would be useful. Ergo BaKoMo. With that, I should be able to work on the various sections of the manual natively and submit my changes, albeit informally, to Stuart for inclusion.

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.

Likewise, if the manual is autogen'd every release, what happens to the changes we make? Is it like my carefully crafted GRUB scripts that get casually tossed out and replaced with every kernel update?

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

Postby jharris1993 » Wed Nov 21, 2012 3:21 pm

Hooray wrote in Wed Nov 21, 2012 8:08 am:The only way to bring such changes to FG is usually to volunteer and handle them yourself while demonstrating how this improves the project.

I could not agree with your more.

This is why I am willing to "volunteer" to help with the manual, despite my "essays" :wink:
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 AndersG » 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
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: 2418
Joined: Wed Nov 29, 2006 9:20 am
Location: Göteborg, Sweden
Callsign: SE-AG
OS: Debian GNU Linux

Next

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest