FLOSS Manuals

FLOSS Manuals is about providing quality manuals about how to use free sofware. We are a not-for-profit foundation established in Amsterdam in 2006. We are also a website (wiki), and a community of free documentation writers.

What we do 

With 60% of all websites running on free software, why do only 1.7% of all computer users have free software on their desktops? The answer is simple and the Free Software Foundation has said it already :

"The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals"

FLOSS Manuals exists to provide this information to anyone, for free.

We do this through our website which is a wiki. If you are used to Wikipedia you might think FLOSS Manuals doesn't look much like a wiki. You would be right. However, the website is in fact a wiki, it is based on the very nice software called TWiki. Since we are a wiki you can read and contribute to the manuals.

READ, WRITE, REMIX

There are three basic parts to the FLOSS Manuals website - READ, WRITE, and REMIX.

In the READ section you can read manuals online or download them via PDF.  Here we have arranged many manuals on how to use various free software. They are organised into software categories. Each of the manuals will help you get started and in general they cover the following:

1. What does the software do?
2. What does the software not do?
3. Introduction to the software's context
4. How to install the software
5. How to configure the most important elements
6. A basic introduction to the interface
7. Using the software's most important features with hands-on step by step tutorials
8. Where to go for more help

Through the WRITE section you can write manuals. This is the 'wiki' part of the site. You need to register for an account and then you can start contributions. Registration is required so that we can credit you with the changes you make. With FLOSS Manuals all material is licensed so that it can be used by anyone for any purpose. However we believe it is important you get the credit for the contributions you make so registration using your full name helps this process.

The REMIX section is the area which is undergoing the most on-going development. In the REMIX section you can actually make your own manuals from existing content. All chapters in the manuals are written so they are 'self contained' this means you can re-use them in other contexts. Hence we have built tools so you can remix manuals specific to your own requirements.

In REMIX you can drag chapters from existing manuals onto a template for your own manual and change the chapter names and their look-and-feel through the browser. You can then download your newly remixed manual as HTML (in a zip or tar file), which is good for including on CDs/USB sticks or reading offline. Alternatively you can export the remixed manual to a indexed PDF. Lastly, you can include the remixed manual in your own webpage or blog by cutting and pasting 5 lines of HTML.

Printed Manuals

In addition to the online free manuals, you can also buy some of the manuals through our print-on-demand service. We sell these manuals at a small mark-up. All money raised through selling a manual is put directly back into the development of that specific manual. Remember, you can always get the manuals for free from the FLOSS Manuals website.

Why Use FLOSS Manuals?

If you wish to create documentation about a free software project and you are in search of a community and documentation tool set then FLOSS Manuals is designed for you. Generally speaking, the types of projects that use FLOSS Manuals can be broken down to two paradigms:

1. Manuals published by FLOSS Manuals
2. 'Official' documentation written by of software projects
   

Manuals published by FLOSS Manuals

If you wish to contribute to, or create, a manual published by FLOSS Manuals then you simply need to create an account and begin writing. For example, you can do this if you have found a manual linked from the READ section (http://www.flossmanuals.net/read)  and decided you wish to contribute to, extend, and improve the it. This is, at the time of writing, the most common motivation for using FLOSS Manuals.

Official documentation of software projects

However it might be that you are working with a software development team and you are in search of a documentation platform to create the 'official' documentation. In this case FLOSS Manuals offers you a repository to create your own manual and manage it yourself. You can utilise all the tools available and host the manual on your own site by using the FLOSS Manuals 'live manual' API or by linking to the PDF. We can also host templates created by your own team so you can publish static HTML manuals with your own look and feel. If you point a sub domain at our sever we are more than happy to change our hosting configuration so that your sub-domain points directly to your manual.

In a short time we also hope to have the Print on Demand process automated so that you can publish to a print on demand service and control the resale value of the book yourself. This means you can sell your manual at a profit to raise funds for the software project. FLOSS Manuals asks no fee and we expect no income from sales of your manuals.

So, you may decide never to list the manual on the front page of FLOSS Manuals, preferring instead to have the docs hosted under your domain.

Our principle aim is not to be a publisher but to create as many tools and outlets for quality free documentation as possible. If that means you wish to use the FM tool set but host or 'publish' under your own banner, then that's excellent. We are very happy to offer you a documentation platform to meet all your documentation needs.

Of course, all this is for free software / open source software projects only. If you create proprietary software then...
 

Free Manuals for Free Software

Many times I have searched online for information about how to use a particularly exciting free software and been disappointed about the lack of information I could find. This situation was particularly frustrating when it came to leading workshops. I wanted to spread the word on the wonderful applications available, from real time audio and video processing applications like PureData or Kino, through to office applications like Gimp or Inkscape. However I had to create my own manuals for my workshops as there was nothing else appropriate available online. Sure, some of these applications had books available which I could (rather expensively) purchase at the local bookstore, however I would have to require my students to buy the book too or rewrite (backward engineer) the material to avoid copyright infringement.

It seemed crazy to me that I had to buy a book to learn how to use a free software. The problem seemed not just financial but idealogical. How can a software be free if you have to buy a proprietary book to learn how to use it?

At first I thought this was just a gap in the free software ecology. Someone simply needs to write free manuals. As it turns out this is largely true, however there are a few embedded issues that need to be dug out before the free documentation sector can identify itself and flourish. Through observation and experience I have come to the conclusion that the free software / open source sector has a blind spot when it comes to documentation which is retarding the development of this sector. This prejudice begins with a general belief that documentation is not that important and extends to much more extreme positions such as the Free Software Foundations inability to extend the same license freedoms for documentation as they extend to software.

In time this will change as more people realise that free documentation is not just an important promotional tool for the advancement of free software, but that free documentation is as socially and economically empowering, and subscribes to the same ideals, as free software itself.

In this article, I'll describe what I see as problems with existing free software documentation, licenses, and delivery mechanisms. Then I'll describe attributes I think free documentation should have, along with the economic ecology that it needs. Finally, I'll talk about how the FLOSS Manuals Foundation is attempting to address these issues, and how you can help.

Free as in education

Free software has developed outside and alongside of the more restrictive licenses and copyrights of the proprietary software environment. (i) Free software can be used by anyone for any purpose: users can study the source code, adapt it to their needs, and whether or not they modify it, they can redistribute both the software and its source code. This co-operative model has meant that free software has had a high rate of uptake in the cultural sector - artists and activists have been amongst its active promoters. Its appeal is strong amongst those who recognise the productive political and social ambiguity of the word 'free'. A number of artists also make a living through teaching and workshops centered on free technologies they use in their practice. Exhibitions, symposiums and festivals engaging with these ideas have brought these issues into the public arena, while cultural and digital theorists have reinforced the need to develop and use both free software and free hardware. This support has often risen to the point of hyperbole, and for many years every digital art event seemed to be 'open' this or 'free' that.

However, despite these efforts, it seems that the uptake of free software is very slow. Although most of the internet runs on free software (60% of web servers run Apache and 90% of Domain Name Servers run BIND), if we look at operating systems the share is somewhere under 2%. (ii) Free software, as opposed to free operating systems, does a little better, with the current estimate for usage of the Firefox browser across all platforms coming in at something between 20-30%. (iii) Still, this is very small. The user uptake of Firefox is an impressive achievement, but why haven't other fine tools such as the image editing software Gimp or the audio editing software Audacity taken similar 'market' share? Why, given that we all know how good free software is, that a wide variety is available, and that it is free as in gratis as well as libre, (or, Free Libre Open Source Software - FLOSS) is the uptake so low?

The Free Software Foundation think the answer is quite simple: "The biggest deficiency in free operating systems is not in the software - it is the lack of good free manuals." (iv)

Many years of teaching free tools (mostly for streaming media) have led me to the same conclusion. It is not that there is no documentation. Often you can find something on a developer's site, or in a bookstore, or perhaps in the comments on a forum, a mailing list, or maybe in a wiki somewhere. This seems to satisfy most geeks. Many 'advanced' users tell me this is enough. Google is their index, and they know how to use it to find solutions. The thinking is that when it comes to solving a problem in software you aren't the first to encounter it and that someone somewhere has written down a solution. This is often true. If it isn't true then either you solve the problem yourself (by hitting your head against the wall until it works), or you find the appropriate IRC channel and quiz the developers. Even better...you're using open source, right!? READ THE SOURCE CODE!

Well, I don't know about you but maybe, just maybe, I feel that I should not have to be a programmer to work out how to use a particular piece of software. Perhaps this threshold is a little too high and might be deterring users.

Free software should be well documented. You should be easily able to find out what a particular software does, what it doesn't do, how it fits into the software universe, what the interface looks like, how to install it, how to set the up most basic configuration and how to use its main functions. These things should be well explained and kept in a place that is easy to find. The easier it is to access well written documentation for a given software, the larger the potential user base.

I have often heard that it is simply not the case that there is a lack of documentation. 'There is a manual for XX!' (replace 'XX' with your favorite free software). 'What do you mean? XX has a great manual!' Well, I admire the effort put into the documentation of some free software. Unfortunately however, the documentation is seldom adequate.

There are some very good manuals available at a price for some of the more well known free softwares. In general there is more published about server-side softwares than desktop software. These books are usually published in the traditional publishing model under restrictive copyright with no easy way to modify or re-use the contents. I don't subscribe to using closed documentation for these reasons and other idealogical and practical reasons which I outline later in this article.

The most common flaws of existing documentation of free softwares include:

• that assumptions about the user's knowledge are set too high

• the documentation has bad navigation

• it contains unexplained jargon

• there is no visual component

• the documentation is proprietary or 'closed' material

• the documentation's design is unreadable

• operational steps are missing or unexplained

• the documentation is out of date

• the documentation is not easily re-usable

• the documentation is not easily modifiable

These mistakes are very common, and the situation is so bad it amounts to a crisis in the world of free software. I have made my own efforts to address this situation but I thought it is about time I wrote about some of the basic issues in order to encourage others to consider the importance of free documentation and to encourage you to contribute to free documentation projects.

First of all I want to say something briefly about why documentation should be free, and then to look at some parameters for identifying good documentation.

Free documentation for free software

Making documentation ideologically aligned with the software it documents seems to me to be a natural relationship. Documentation should be able to flow as freely as the software itself, making unhindered migrations across media, onto the screens and bookshelves of anyone that wants it. Documentation should be able to be redistributed, altered, sold or given away for free by anyone to anyone. If documentation cannot do this, it is not free.

It is with regret that author notes that the Free Software Foundations "Free Documentation License" [sic] tethers content to an unwieldy set of requirements which impede this freedom. It is perhaps the rationale of this license - marrying documentation to manual, manual to book, book to publisher, publisher to commerce - which has set the Free Software Foundation on a course that undermines their reputation as staunch defenders of freedom.

In particular :

• the FDL does not allow for easy duplication and modification (an absolute necessity in this day and age)

• it does not allow for the easy inclusion of documentation in software itself

• it appears to be written for hard copy books and does not engage issues of digital documentation very well

• it is difficult to know how to implement

These issues emanate from the founding rationale of the license. There are two particular assumptions that lead to problematic clauses:

1. The FDL seems to assume that technical writing should contain embedded free software political editorial. I refer to this statement (amongst others):

"Our manuals also include sections that state our political position about free software. We mark these as "invariant", so that they cannot be changed or removed. The GFDL makes provisions for these "invariant sections".
http://www.gnu.org/licenses/gpl-faq.html#WhyNotGPLForManuals

Political editorial is not a prerequisite (nor, in my opinion, desired) for good technical writing.

2. the FDL assumes documentation writing is a book business. I refer to :
"the GFDL has clauses that help publishers of free manuals make a profit from selling copies"
http://www.gnu.org/licenses/gpl-faq.html#WhyNotGPLForManuals

'Free Licences' should not shy away from commercial use of the substance it is applied to. That is the principle of freedom - to use the software or documentation as you wish, as long as you preserve the same freedoms for others. However the focus should be about preserving freedom not preserving particular business models. Can you imagine a similar clause in the GPL? It would be lamblasted by Richard Stallman and the FSF for limiting freedom and immediately dropped. A pity neither Richard Stallman or the FSF apply the same freedoms to the materials of free software education. If they did this issue and others would be cleared up quickly I am sure.

The above are just the main concerns with the rationale of the FDL. These two issues have both idealogical and pragmatic consequences that make it very difficult to use the FDL if you wish to write free documentation for free software.

The idealogical issues are clear - but these rationale also simply make the license practically unusable. For example, there are constant references to book elements such as 'Title Pages', 'Covers' etc. One particular clause that is hard to maintain is this section which stipulates that a modified version of a work must:

"A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission."

There are so many issues with this statement its hard to know where to begin. What, for example, is the role of a 'History Section' in documentation that might be one 'page' long? What about documentation that is a few sentences long? The main problem with this clause however is that digital documentation should flow like water from one author to the other with as much flexibility to add, alter, delete, and remix as much as possible. Requiring a 'traceback' to the original author so you can use the same title is cumbersome, stifles re-use of material, and logistically hard to maintain in this age of free flowing digital document distribution.

Here is another 'book' issue which limits freedom:

" If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects."

Why should free documentation writers care how many documents you might print? In my case I want the material to be used as much as possible. Go ahead, print as many as you like, however you like, on whatever medium you like. Free documentation writers don't want to get involved in complex clauses involving 'Cover Texts', 'Front-Cover Texts' and arbitrary numerical limits which are going to limit your freedom to use the documentation as you want. They want the material to be used as much as possible.

We need the same principles of freedom for documentation as we have for code and the Free Documentation License (FDL) does not preserve the above principles of freedom. At the time of writing there is a redraft of this license and it looks like it will be split into two licenses, however neither of the redrafts address these fundamental issues. We need a license that goes further that the FDL and can allow the users to do with the documentation as they can do with the source code. Thankfully there is a license that does this - the General Public License (GPL). This is the license that most free software / open source projects use to release their source code. Due to the well known history and legacy of the GPL many believe it to be only applicable to software, however the license can be applied to any content as the FSF itself acknowledges :

"any work of any nature that can be copyrighted can be copylefted with the GNU GPL." http://www.gnu.org/philosophy/nonsoftware-copyleft.html

Documentation of free software should share the same principles of freedom as the software itself. It should therefore use the GPL when the code of the project it documents is also under the GPL. If you are not convinced of this idealogical argument then ask yourself these two simple pragmatic questions. Should programmers be able to benefit from the efforts of free documentation writers by embedding their documentation into the software itself? Should it be possible to distribute free documentation with the software it documents? If your answer is "yes" to either of these then you do not have many choices when it comes to licenses. License interoperability (compatibility) is laden with complex problems that few outside of the Software Freedom Law Center seem to understand. Many, for example - the Debian project, argue very convincingly that the Free Documentation License may not be compatible with the GPL. There is, however, one license that enables documentation to be easily distributed with GPL software - the GPL. The only reason to bother about another license is if the free software project you are documenting uses a license other than the GPL. In this case give the documentation the same license as the code.

Free Documentation is Better

Less ideologically and more practically speaking, free documentation presents a better kind of documentation than closed documentation. Ease of modification is a strength that proprietary documentation cannot match. Free documentation can be updated at the same time as the software is updated and improved through distributed problem solving (a la 'many eyes make bugs shallow'(v), it can be translated into your own language or re-contextualised to better suit individual or organisational needs. Free documentation in these terms alone is a better argument than closed documentation and if done well, can be a tremendous asset to the uptake of free software.

So, now I would like to talk a little about some essential qualities good free documentation should have :

Easy to Access and Easy to Improve.

It makes sense that if the intention is that something can be improved that it should be able to be easily improved. Many free documentation projects inherit their technology strategy from free software development methods. These projects store their content in a CVS (Concurrent Versioning System) which means that you need to be pretty technically competent to be able to access the source material and contribute to it.(vi)

What this system overlooks is the fact that writers are not programmers. Writers have a different tool set (usually based on word processors), and do not have a familiarity with the typical programmers tool set. To expect a free documentation writer to access content via CVS or similar tools is to make the same mistake as assuming the audience for your documentation knows more than they do: setting the threshold for contributions so high means that many people that could contribute won't contribute.

There is no need to trap content in CVS. All we are dealing with is text and images and there are plenty of tools that are easier to use. I recommend a wiki with WYSIWG (What You See Is What You Get) editing - these look and work like word processors except they are available anywhere you can get online via your browser. I personally don't recommend using mark-up languages as even wiki mark-up is harder to use that WYSIWYG editors and is a barrier to contributions.

Well structured

Many projects are now setting up unstructured wikis for their developers and users as a base for writing documentation. At the moment, mediawiki is often used, although which specific platform gets used tends to depend on the winds of software fashion. These resources can be extremely good, however I believe unstructured wiki content, with contextual navigation systems, is a poor substitute for well-structured content with a clear top-level index. Unstructured content is a good secondary documentation strategy and certainly useful for documenting the nooks and crannies of sometimes archaic interface issues or strange hardware-specific conflicts, however it doesn't replace content that is designed to document the software thoroughly with a clear and structured flow.

Tell it as it is

I have found that documentation written by developers can make the simple mistake of writing how the software should work and not how it does work. Writing free documentation should not be done from memory or done by those who cannot see the problems. Telling the user what is wrong with the software, what does not work and what could be improved is absolutely necessary. It is not bad-mouthing a free software to point out a quirk that should not be a quirk. It is far worse for potential users of that software if the user reads documentation that is inaccurate or glosses over these issues.

Make it look good

Documentation should be attractive to read. Over the years, free software developers have discovered that in order to interface with humans, software must look nice and allow the eye to easily engage with it. The same is true for documentation. Black text with blue links on a white background are not enticing. Embrace a layout than enhances readability but make sure it also looks good.

Quality

Now we come to the bugbear. Quality. What is good quality documentation? Some benchmarks include:

• no spelling mistakes

• set a style guide and stick to it

• make sure no steps are glossed over

• make sure the documentation is accurate

However, beyond the purely procedural there is the subjective issue of quality. There is no solid rule, the best you can do is to get people to read the content and tell you if it makes sense. If you belong to a community of contributors then look to peer reviews.

Before talking a little about what FLOSS Manuals has done addressing the issues listed so far, I want to talk a little about the need for a free documentation sector.

The Call for a Free Documentation Sector

Free software has developed a methodology and economy that free documentation lacks. The traditional method of making money in the manual business is to write a manual and sell it. To protect your interests you use a standard 'closed' copyright notice. This is the publishing model. Outside of this circle of proprietary content you do the best you can voluntarily and put your work online wherever you can.

The free software sector has much better resources. Free software projects have established working models and a number of content and management tools including development and distribution sites like Savannah and SourceForge. The financial model is much clearer too. Most obviously, if you need to make money working on a free software project you hone your skills and find a company that will pay you for your work.

Free documentation is lacking all these components - there is no standard technical tool set, there are very few 'communities' of free documentation writers and less chances of being able to pay the rent if authors choose to do this full time. Finding our way to build these elements is critical to the evolution of a healthy free documentation sector, and, I would argue, to achieving the widespread adoption of free software. It is imperative that we find and develop these models and tools, as the standard model of closed documentation for free software contains an ideological paradox.

We need to build an ecology around free documentation in much the same way as the free software sector has done. Free software enables programmers to work with communities of programmers, with tools that enable collaboration, and the opportunity to learn from their peers.

There is an economy of reputation at work in these communities which encourages best practices, and a lucky minority can leverage their reputation to be paid to work on free software projects.

Free documentation needs these tool sets, communities and economies. Free documentation needs to identify itself as a sector and build a consciousness as a community. This in itself can lead to better documentation and to the potential for an economically sustainable practice for individuals wishing to make a living writing free manuals.

There are a few shallow myths about documentation that hinder this sectors development a little. The first is that writing documentation is boring. Well, it can be boring, but it can be hugely satisfying and it certainly can be fun. I have indeed actually witnessed people being happily proud of their docs and equally excited when someone comes along and improves them. Sound familiar? It sounds a little like the free software sector. Yes, documentation writers enjoy what they do, they enjoy doing a good job, they enjoy getting better at it, they enjoy being recognised for it, and they especially enjoy people benefiting from their efforts.

There is another myth that needs to be popped. I have noticed a certain amount of hesitancy in the free software world towards contributing to free manuals. This seems to stem from programmers holding onto the belief that writing a book is a cornerstone of the free software economy. Well, I hate to break the news here, but the publishing world is going through the same massive challenge to this commodity model as the other industries that have their medium digitised. Not that book sales which relied on proprietary content and the sale of information, ever actually made many authors much money but there is a bigger issue at play. Many programmers fail to see that the world of publishing has changed. It is not just software, music and movies that routes itself around artificial obstacles to distribution - books do too. If programmers hold on to outmoded models of proprietary information resale then they will find themselves without a secondary revenue stream The new model is, as technical writer Janet Swisher says, to "charge for time, but give away the artifacts".

The same situation is true for documentation writers in general. It is entirely possible to be commissioned, for example, to write manuals, or to be employed by a company to write inhouse support docs that can also be contributed to the general community under a free license. As with this example, in many instances the free documentation economy can map directly onto, and learn from, the economy that has developed around free software. It could be argued that the software is already there but the documentation largely isn't so the potential demand is very high.

FLOSS Manuals and the Pursuit of Funky Docs

It is easy enough to point out what is wrong with something and harp on about how it should be. It's another issue to actually do something about it. In order to address this, I founded a not-for-profit foundation called FLOSS Manuals. We are a community of free documentation writers committed to writing excellent documentation about free software. Anyone can join FLOSS Manuals and anyone can edit the material we publish. All content is licensed under a free license (the GPL (GNU General Public Licence)).

When we started (we officially launched in October 2007) there were, and still are, no good publication platforms for collaborative authoring. Some may say that there are too many CMS (Content Management Systems) already and surely, SURELY, there must be a CMS to meet our needs?

Well, no. The closer you get to collaborative publishing systems the further you stray from the functionality of most Content Management Systems. So we have hacked our way into the wonderful TWiki and developed our own set of plug-ins. TWiki has proven to be a very good platform for online publication. It has all the structured content features and user administration that makes it a good shell for authoring collaborative content. What was missing, and what is missing from other CMSs is good copyright and credit tracking, easy ways to build indexes, and a nifty way to remix content. We have remedied that now with our own custom plug-ins (available through the TWiki repository). (vii)

Remixing

So, the word 'remix' may have caught your eye and you may have fleetingly thought 'remixing manuals?'. It might not seem intuitive at first glance but there are a lot of very good reasons why manuals are excellent material for remixing. I don't mean remix in the William S. Burroughs sense of cut-up - we do cherish linearity in the world of free documentation. I mean remix as in re-combining multiple chapters from multiple disparate manuals to form one document. Doing this enables the user to create manuals specific to their needs whether they be, for instance, learning by themselves, teaching classes or running inhouse training programmes.

The FLOSS manuals remix feature (http://www.flossmanuals,net/remix) enables the remixing of content into indexed PDF and downloadable HTML with your own look and feel provided by Cascading Style Sheets. Now we have also added a Remix Application Programming Interface. This means that you can remix manuals and include them in your website by cutting and pasting a few lines of HTML. No longer is messy FTP necessary. This part of FLOSS Manuals is new and in test form, but so far it works very well. Combining remixing with print-on-demand is an obvious next step. It can be done now, as print-on-demand services use PDFs as their source material, but the trick is in getting it to look nice on paper.

A word on remixing - if you want to make documentation that is reusable then consider the way you write it. It is a good idea to keep it modular - with no dependencies on other content and with as little single-context language as possible.

Print on Demand

In addition to the free online manuals FLOSS Manuals material is also turned into books via a print-on-demand service. The books look very nice, having been tweaked for print production, and they are available at cost price (we don't put any mark-up on books so they cost what the print-on-demand company charge to produce the book and send to the buyer). This is pretty exciting and FLOSS Manuals has its own embeddable Book Store. Anyone wanting to support the promotion and uptake of free software can embed the FLOSS Manuals book store on their website with the addition of a few short lines of HTML.

As I talk to people, I find that the physicality of books is the best way to get across the idea of what the FLOSS Manuals project is doing. Talking about a website is one thing, but handing over a book sparks understanding and gets people excited. Books are an excellent promotional medium for free software itself.

Quality Control

Lastly, a word on quality. These manuals aim to be better than any available documentation. (Sometimes this is not hard, as there is no available documentation!). When working with an open system maintaining this level of quality raises some interesting issues. Anyone can contribute to FLOSS Manuals - it is completely open. You need to register, but this is not a method for gating contributions, but so we can abide by the license requirements of the GPL to credit authorship.

Spam is an obvious issue with an open system, as is the possibility of malicious content. Incorrect or malicious information in Wikipedia might lead you to quote the wrong King of Scotland or may misinform you about the origins of potatoes, but incorrect information in documentation might lead you to wipe-out your operating system. So we have separated the 'backend' - where you can write manuals - from the 'frontend' - where you can read manuals.

Manuals in the 'Write' section are in constant development. (viii) However, the same manual linked from the front page will be in the 'stable' form, ready for use. This is managed by some existing TWiki tools we twisted together to form a simple one-step publishing system. It works like this - every manual has a Maintainer. A Maintainer is a person - a volunteer - that keeps an eye on that particular manual. Edits and updates are added to the Write section by anyone that wishes to contribute. When the Maintainer thinks the manual is in good shape and an update is appropriate they push the 'publish' button and all the material is copied to the 'frontend' version of the manual. This way the reader gets stable reliable documentation and writers can continue working on documents without the reader being confronted by half-finished content. It's a simple and effective system.

How you can help

Good free documentation is not just a necessary component of good free software, it is the most important part of bringing the software to the largest potential user base. Free documentation is simultaneously a education tool and a marketing device - without it the software will undertake a gradual growth as users inform each other as to what is available and pass on experience and knowledge to each other on an almost one to one basis. This is a powerful mechanism in its own right but to break beyond this barrier into the world of the average desktop computer user we need comprehensive and attractive free docs.

If you love free software then join us making free documentation! We have a growing number of very talented contributors and Maintainers and good manuals available online, but we need more. Contributing is pretty easy. If you would like to be a part of helping create good manuals then register with the project and read our manual on FLOSS Manuals. (ix).

Anyone can contribute: you can spell check documents, tidy up layout, test or review material, design icons, write, remix or improve material. Contribute in any way that you can and not only will you be helping to make the documentation better, you will be assisting in the development and spread of free culture and free software.

Reading Manuals

We aim to provide you with good quality free information on how to use free software. By 'free' we mean the information costs no money, apart from an internet connection of course. However, we also mean 'free' in the sense that you can copy, distribute, and modify the manuals in any way you see fit.

All of the manuals are accessible through the front page of our website, where they are organised into several sections which are categories of software.

You will notice a list of categories in Orange and the softwares listed below each category in grey. If you click on one of the software names you will be taken immediately to that manual. For example, if I click on 'Audacity' I will see the latest version of the Audacity manual :

This is the Audacity Manual.

In each manual there are four sections you need to know about:

 

Navigation

On the left side you will see the index of the manual:

The index shows a list of sections in black with the chapters underneath. To read a chapter you simply click on the white chapter title.

Content

If you click on a chapter title the content will be displayed in the section on the right. For example if I click on 'Ubuntu' in the 'Installing' section I will see something like this in the box on the right:

This is the content of the chapter I just chose to read.

PDF and Print Version

If you wish to download the entire manual you can download a PDF version. This can be done by clicking on the 'MAKE PDF' icon:

This icon is always under the heading of the manual and when you click on it you can download a manual with exactly the same content as you see online in PDF format. The PDF also includes a cover and a linked table of contents.

If you wish to print the manual on your printer at home or the office, you should click on 'VIEW ALL & PRINT':

If you click on this icon the manual will be displayed all one one HTML page and without any extra design. It is simply the 'plain', single page, version of the manual. This means you can print it easily on your printer.

Comment and Edit

If you wish to comment on the contents of the manual you can do so using the links at the top right of the content box:

Clicking on 'Edit this page' will take you to the WRITE section of FLOSS Manuals, where you can create an account and edit any of the manuals. Clicking on the 'Discussion' takes you to a page where you can comment on the content without needing to register.

Exit the manual

When you wish to return to the READ section click on the arrow at the top left of the page:

Editing Overview

Editing manuals is where all the fun begins! Free documentation writing should be an enjoyable experience, so focus on a task you think is fun and get started. You don't have to 'think big' when making a contribution, every edit helps. Making the images better, improving lay out, spell checking, laying out the print-on-demand manuals, re-writing a sentence, or adding whole chapters or manuals are all tasks that help improve the manuals. So pick something that appeals to you and go ahead and do it.    

The best way to learn how to contribute is to jump in and do it. Don't worry about making mistakes, just get stuck in and edit away. If you make a mistake someone else will spot it and correct it later.

If you are worried that errors will put readers wrong, then don't worry! All edits to the manuals are not 'live' but are filtered through a simple publishing process where edits are checked before they go into the final manual.

FLOSS Manuals is about creating good documentation, but we are also about participation and collaborative knowledge building. There is a community involved in producing the manuals, and if you want to discuss issues then consider joining the mailing list:
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

WRITE

The WRITE section (http://www.flossmanuals.net/write) of FLOSS Manuals is where all the manuals are located for editing.

You can see two basic sections of this page. On the left is the navigation bar and on the right is the content window. In the example above this is displaying the WRITE home page. You can see a list of manuals under the title MANUALS:

By clicking on any of these titles you will be taken to the 'Home page' for that manual. If I click on the GIMP manual I will see something like this:

This page contains the information about the GIMP manual. Notice this page is not the page that the reader sees if they clicked on GIMP from the READ section (the front page of FLOSS Manuals). The actual GIMP manual looks like this:

The above is the 'published' version of the GIMP Manual. You might ask 'why there are two versions of the manual?' Well, all manuals have a development version and a published version. The development version may contain half finished edits, chapters that have not yet been included in the final manual, material that needs to be spell checked etc. It is not nice for readers to see all this, so when all the edits and spell checking etc is done these changes get copied to the manual the reader sees.

The development version, where you make all the edits, is kept in the WRITE section, and the readable version is kept in the READ section. If a manual does not have a version in READ it means it is not yet ready to be included there and more work needs to be done.

Having the two different versions like this also means that you shouldn't be worried about making mistakes when editing manuals. The reader will never see these mistakes.

Chapters

Every manual is made up of chapters. When you edit a manual you are actually editing a chapter within that manual. Chapters can be accessed for editing through the manuals WRITE home page (lets call this the manuals 'homepage'). If I look at the example of the GIMP homepage I can see that there is a list of chapters :

I can see three columns. The first column contains the name of the chapter. This name is linked to the editable version of the chapter. If I like I can edit the chapter directly by clicking on the 'edit' in the next column. In the final column is text from the first sentence in that chapter.

The name of each chapter is spelt using a system common to many wikis called 'camel case'. A camel case is a compound word (one or more words joined together) without  spaces and the first letter from each word is capitalised. For example, instead of 'Installing Windows' we have 'InstallingWindows' etc.

The names are like this only in the WRITE section. When a new version of a manual gets copied to the READ section these titles are changed to something more reader-friendly. Also note that the list of chapters above contain chapters not in the version of the manual in READ and also that they are in a different order. Choosing the right names for each chapter, deciding which ones to include and exclude, and putting them in the right order is the job of the manuals Maintainer.

Maintainers

Each manual has a Maintainer. A Maintainer is someone that keeps an overview of the manual. Their job is to keep an eye on quality, communicate with people contributing to the manual, and publish the most recent 'readable' version of the manual as necessary. If you are contributing to a manual it is nice to keep in touch with the manual's Maintainer, but it is not necessary. You could just edit away without ever being in touch with the Maintainer. However the Maintainer is the central point for all information about the manual so it can be useful to drop them a line (especially if you create a new chapter and want it included in the manual). The Maintainer's email address is always displayed :

Not all the manuals have dedicated Maintainers, so in general if you see the email address 'adam@flossmanuals.net'  it means the manual is by default maintained by Adam Hyde. If you want to become a Maintainer drop him a line.

Managing Accounts

FLOSS Manuals gives you lots of tools for managing your account. If you ever get stuck you can always email the system administrator : adam@flossmanuals.net 

Creating an Account

It is necessary to register (create an account) before you can start editing. Anyone can register, and your account is active immediately.

We require registration before you can contribute so that you can be credited for your contributions. All chapters carry a credit notice for both the creator of a chapter and all those that modified the content. 

Registration also helps to reduce SPAM. Some nasty SPAMMERS have automatic processes that submit content to wikis and other open systems. These 'contributions' are annoying and waste everyone's time. By requiring registration we avoid most of these automatic processes and keep the site clear of most SPAM.

To register you need to go to http://www.flossmanuals.net/register

You will see a simple form :

In this form you can enter your details. All fields are required except the country.

First Name and Last Name

It is a good idea to use your correct first and last names for the purposes of crediting you for your contributions. 

Username

You use the Username to log into FLOSS Manuals. It is automatically (by default) changed to a combination of your first and last names. However you can change it, and doing so will make no difference to how you are credited.

Email 

Please note that FLOSS Manuals does not publish your email anywhere, even on our own site. Your email address is sinply required for admin purposes (such as mailing you your password if you forget it).

Password 

It is not a good idea to use a password you use for storing sensitive information anywhere. This is good practice for any accounts you create on any new system.  Use instead a password you haven't used before or one that you might use just for these kind of purposes.

Country

Its interesting to know where contributers are from but it's not compulsory for you to tell us. 

 

If you enter all the information correctly you should receive an email telling you everything is ok, and then you will be automatically logged-in and sent to the WRITE part of the website where you can start contributing to manuals.

You can see that you are logged in by checking the top of the navigation bar on the left. If you are it will display your user name:

When you have registered you can later log in using the Username you entered and the password you gave.

Logging In

To log in to FLOSS Manuals you need to first open the WRITE section of FLOSS Manuals. If you already have FLOSS Manuals open in your browser then just click on 'WRITE' :

Or you can point your browser to http://www.flossmanuals.net/write 

Then you click on the LOGIN text :

This will bring up the login page :

 

In the text boxes shown enter your Username and your Password and press 'Logon'. You will then be directed to the WRITE section.

Logging Out

You may wish to log out when you have finished working with FLOSS Manuals for the day. This is usually a good idea if you are sharing a machine as it ensures no one else can make edits under your name. If, at anytime, you wish to log out simply click on LOGOUT at the top left of the navigation bar:

This will instantly log you out of FLOSS Manuals and you should see that your Username disappears and LOGOUT changes to LOGIN.

Forgotten Your Password?

If you you come to log in and you realise you have forgotten your password then in the log-in window you will see a link to resetting your password :

This last link will take you to a new page where you can request a new password be sent to you via email.

Want to change your password?

If you decide you need to change your password then in the login page you can click on 'change' :

You will be directed to a new page where you can change your password.

Creating a New Chapter

Anyone that has registered and logged in can create a new chapter, the process is pretty simple:

Start by going to one of the manuals listed in the WRITE section, I will use the GIMP manual as an example, where you will see this:

If you look at the bottom of the first orange box you will see 'Create a new chapter' (in some manuals this box may not be located in the same place) :

 

To create a new chapter (make sure you are logged in) type the name of the new chapter in the box provided and press 'Create'. If I want to create a chapter I can type something like 'Improving photos' :

When I press 'Create' a new chapter will be created and I will be taken directly to the new chapter so I can start editing :

What you may notice is that the name of the chapter is now displayed at the top and it is displayed in 'Camel Case'. So I see 'ImprovingPhotos' not what I wrote, which was 'Improving photos'. All chapters are converted to Camel Case like this automatically.

You should also see a default text everytime that you create a new chapter. You should delete this text before you start writing you chapter.

Credits

When you create a new chapter you are immediately credited as the copyright owner and the chapter is licensed under the GPL. The GPL is the 'General Public License' and this is the license used by FLOSS Manuals to ensure all content is kept free. For more information about the license see http://www.flossmanuals.net/license

Some think it is odd that the we use copyright at all... after all isn't the content meant to be 'open'? Well, all free licenses, including Creative Commons, are not outside of copyright. They are all licenses that manage copyright so that others can use and re-use the content. Hence there is always a 'copyright holder' - and that person is the one who created the content. If you create a chapter you 'own' that chapter. However the license (GPL) means anyone can use it, for any purpose, forever, as long as any changes they make are also licensed using the GPL.

The credits are listed on every output of FLOSS Manuals. So your name will be associated with the chapter in the online manuals, the downloadable PDF, and in a print-on-demand version of the manual. You can also see the credit notice at anytime by looking at the chapter in the WRITE section. For example, if I save the chapter created in the above example I see this:

You would of course see your name here. The name comes not from your Username but the First Name and Last Name you gave when you registered, so it is important you entered that information correctly.

Editing

To edit a manual you first visit its home page in the WRITE section.

For an example, let's take a look at the GIMP Manual:

If we scroll down the page there is the list of chapters that you can edit:

The quick way to begin editing is just to click on the 'edit' link next to the chapter's title. However you might want to look at the chapter before you edit it. If that's the case then just click on the title of the chapter.

In this example I will click on 'OpenAFile', which shows me this :

This is the development version of the chapter 'OpenAFile'.

Chapter Information

At the top of the page there is a lot of information about the chapter :

Quicklinks

This takes you back to the manual's homepage in WRITE

Software 

You can use this drop down menu to jump to other manuals to edit.

Chapter

This drop down displays all the chapters for the current manual you are working on. Choosing a chapter from the drop down jumps you directly to it.

Chapter Info

This is the current revision number of the chapter (each time you edit the chapter this number progresses by 0.1).  Also displayed is the date of the last edit, and the copyright notice. All material is licensed under the General Public License and ('GPL)' which means the content is free to use by anyone for any purpose as long as they also license any changes under the GPL. For more information on this see http://www.flossmanuals.net/license

Edit

    This is the big red edit button that you click to start editing the chapter. 

Begin Editing 

To begin editing you simply click on 'Edit' and you can start editing. If you are not logged in you will first be presented with the log in page :

 

When you have filled in your Username and Password and pressed 'Logon' you will be directed immediately to the editing page for the chapter :

The above is the WYSIWYG (What-You-See-Is_what-You-Get) editor for the chapter 'OpenAFile' . The editor works just like a word processor. 

Text Only Editing

If you don't like the WYSIWYG editor then you use the text-only edit function. To do this you will first need to be logged in. When you are logged in you will see some tools appear on the left toolbar of the chapter you wish to edit :

The top two tools are EDIT and TEXT ONLY EDIT. If you click on EDIT you get the WYSIWYG editor. If you click on TEXT ONLY EDIT you get something that looks like this:

 

This is the plain text version of the chapter. You can use wiki mark-up (the syntax some use to contribute material to wikis) here, or you can write the text in HTML. If you write in wiki mark-up it will be, at some stage, converted to, and stored, as HTML.

Edit Tools

By default all editing is done via the WYSIWYG (What-You-See-Is-What-You-Get) editor. A WYSIWYG editor looks like a word processor or text editor except that it works within your browser. FLOSS Manuals uses a version called XINHA, which looks something like this:

The above is an example of the WYSIWYG editor in action (editing a chapter from the GIMP manual).

As you see, at the top of the page there is a list of tools that look remarkably like many of the tools you will be used to if you have used a text editing software like Microsoft Word, OpenOffice, GEdit, TextEdit, Notepad, or Wordpad.

The tools pretty much work the way you would expect them too. In fact, they even use some of the same keyboard shortcuts.

WYSIWYG Tools 

Lets look at the tools one a time :

Save

This is a very handy tool, it enables you to edit the text as you are working, very much like 'save' in a text editor. Actually you can use the keyboard CTRL-s instead of clicking on the icon.

Fullscreen

 

This will make the editor use as much of your browser window as possible. It helps extend the editing area and generally makes life easier if you have a larger screen. If you wish to 'shrink' the window back to normal size then click this button again.

Font Style

This is how you choose the style of the font you will use. There are five types of font styles available from this drop down menu :

1. Heading 1 - this is generally used on the heading at the top of each chapter
   
2. Heading 2 - this is a sub heading under a Heading 1
   
3. Heading 3 - the next level of sub headings
   
4. Normal - for all 'normal' text
   
5. Formatted - used for showing quotes or code snippets
   

To apply any of these styles just choose it from the drop down menu and begin typing. If you wish to change the style of a specific text then highlight that text (click and drag your mouse across the text to be changed) and then choose the style you wish to apply.

Bold, Italics, Underline and Strikethrough

These are 4 separate buttons and they each apply a different effect to a word or words. They all literally apply (in this order) bold, italics, underline, and a strikethrough.  Apply them by clicking on the buttons or use the keyboard shortcuts : CTRL b, CTRL i, CTRL u and CTRL s.

Superscript and Subscript

These two buttons enable you to smaller text slightly below or above the normal text like so:    super^script         sub_script

Aligning Text

   

These four buttons allow you to decide the alignment of the text. The text can be aligned left, middle, right, or justified. All of the text in FLOSS Manuals chapters is aligned left.

Bullet Points and Numbering 

 

There are three tools to help with creating numbered lists and bullet points. The button on the left will turn any text into a number list like so :

1. one item
2. two items
3. three items

If you wish to change the style of the numbering you first create the numbered list, and then click anywhere on that list and choose a different style from the drop down list. You can do the following (for example)

1. one item
2. two items
3. three items
   

or

1. one item
2. two items
3. three items

The button on the right allows you to create bullet points like so:

• one item
• two items
• three items

Indent and Un-indent

You can create paragraph indents using the button with the right-pointing arrow. The button on the left 'undoes' the indent.

Separator

This button is used to place a separating line in text like so:

---

Create Link

This button enables you to create a link to webpages. You use it by highlighting some text and then click on it, you will see a small pop-up window like so:

You fill in the link URL at the top, including the 'http://' part. You can also provide a 'tooltip' - a text that will show when someone has their mouse hovering above the linked text. Additionally you can choose whether the URL should open in the same browser window or in a new window using the 'Target' drop down menu.

Place/Upload an Image

 

This is how you add images. Its quite a simple process but you might need to try it a few times before you get it right. To place an image, first place the cursor on the page where the image should go. Then click on this button and you will see a pop-up window like so:

You can browse the folders shown by double clicking on them. When you find an image you want to use click on it and press 'OK' and the image will be placed on the page.

If you wish to first upload an image, then select the directory you wish to upload the image to. Each manual has its own directory, so it's best to find that directory (usually it has the same name as the manual) and then create or find a directory within the manual directory with the same name as the chapter you are editing. Then press 'Browse' :

When you have browsed your computers file to find the image highlight it, and press 'Upload' The image can then be placed in the page. The maximum width for all images is 600 pixels.

Tables

To create a table use the button shown above. It will bring up a pop-up window like so :

Here you can set some of the attributes for tables.

Erase Formating

 

If you have some text which you have perhaps copied from another webpage or has a mixture of fonts and styles, you can highlight the text and then click on this button and all formatting will be removed.

View HTML

If you click on this button you will be shown the raw HTML code for the chapter. You can edit the chapter using this mode, to turn back to WYSIWYG click on the icon again.

Spell Check

This button indeed does a spell check. It will pop a window like this :

You can then replace words with one of the suggestions by clicking on 'replace' or 'replace all' or 'Ignore' if you want to leave it as it is.

Help and Info

The first of these buttons tells you about the keyboard shortcuts for the above functions. The second button shows the credits for the XINHA WYSIWYG editor.

Remixing Manuals

You can make your own manuals using the REMIX section (http://www.flossmanuals.net). Remixed manuals can contain any chapters from the available manuals. Remixes are done through a drag-and-drop interface through your browser, and you can export them to PDF, or downloadable HTML. It is also possible to embed the manual in your website through the 'live manual' feature.

Why REMIX?

Remixing enables you to create a manual that suits your needs. I don't know about you but I often only use a chapter or two from any manual I purchase, because not many manuals cover exactly what I want. By remixing manuals you can get exactly the chapters you need. If you are leading workshops, for example, you can include only the chapters from the softwares you will use and for the functions you are teaching. Inhouse training material can also be customised for your needs, or you might just wish to take a PDF away with you which covers specific topics.

Additionally, you may wish to explain to people how to do something related to your website. This is where the 'live manual' remix comes in handy. You can remix a manual and have it appear in your website, although it is hosted and kept up-to-date at FLOSS Manuals. If you are a software developer it might also be useful to host your manual at FLOSS Manuals and embed it in your website using the live manual feature.

Begin Your Remix

The first thing to do is to visit the REMIX part of the site. You can get there by clicking 'REMIX' on the navigation bar on FLOSS Manuals :

This will take you to the front page of the REMIX section :

There are three steps involved in making a Remix.

Step 1- Remix

The first step involves choosing the chapters for your remix. This is a drag and drop process. First choose a manual from the drop down box :

Here we can see there are a number of manuals that we can choose from. If you select one and then you will see a list of chapters appear. Let's choose the Icecast manual as an example :

Now we can click on these chapters and drag drag them to the remix box in any order. You can also drag the section titles (the yellow boxes) to the remixed manual :

Then you can also select another manual from the drop down box and add chapters from those manuals :

If you want to change the name of the chapter you can click on 'edit title' :

Then you can type whatever you like here and press 'enter' when you are finished renaming it:

Keep adding chapters and renaming until you are happy with the arrangement of your manual.

Step 2 - Style

In step 2 you can determine the look and feel of the remixed manual. First click on 'Step 2 : Style' and then you will see something like this :

If you feel your manual needs to be re-arranged or another chapter added (or removed) then you can always go back to Step 1 by clicking on Step 1 - Remix. First call your manual somethng by typing a name in the 'Title' box. Then Choose the format you wish to export the manual, this is displayed in the drop down menu under 'Export as :'. Live Manuals come in Step 3 so if you wish a live manual you can skip to that step. The options available from the drop down box are :

PDF 

This will output your manual as a PDF with a cover and a linked index (table of contents) and a credits section at the back listing all the contributers to the manuals. If you choose PDF you need to then also choose the cover you will use from the 'Select Cover Page' drop down menu. Once you have selected the cover you can go to Step 3.

HTML zip

This option will export your manual as a 'standalone' manual in a zip (compressed) file. This is good for including on CDs or putting on a website (although live manuals are better for this). You can design the look and feel of the manual through style sheets, more on this below.

HTML tar

This is the same as HTML zip but the compressed file is downloaded as a tar file (good for linux users).

If you have chosen one of the HTML options then you will have seen the page change a little. It should look somehting liek this:

What you see here is a box with style sheet information, and a box with an example of the look and feel of the manual. To alter the look and feel of the manual you change the style sheet information and then you can press 'Update Preview' to see the results. If, for example, I change the value of font-size on the body{} section to '20px' and press 'Update Preview' I see this:

You can change what you like and see how it affects the final look of the manual. When you are ready you can then go to Step 3.

Step 3 -  Export

So, this is the step when you can export the manual. If you press 'Export' now you will be delivered a PDF or an HTML (zip or tar) file, depending on what options you chose in step 2.

You will also see a new section which is the test version of the Live Manuals (called AJAX MANUAL BETA).

Live Manuals

If you cut and paste these lines of HTML into a webpage or Blog then you will see the manual appear in the webpage. This means that you can have a manual on your webpage but have that manual hosted and maintained at FLOSS Manuals. The default manual looks something like this:

You can change the look and feel of the manual by altering the parameters in the code you paste :

var FLOSSConfig = {'style': {'title': 'color: black; font-size: 20;font-family:
Arial,verdana, sans-serif;font-weight: bold', 'heading': 'font-weight: bold;
color:black;font-family: Arial,verdana, sans-serif;font-size: 12','embed':
'font-size: 12px;font-family: Arial,verdana, sans-serif;font-weight: bold'},
'config': {'width': '870px', 'height': '500px', 'framewidth': '670px'},
'pages': [], 'title': ''};

Experiment with this a little and see what you come up with!

Introduction to INDEX

FLOSS Manuals provides a nice tool so that allows you to take all the chapters you have created and arrange them in a nice order, divided up into sections if necessary, and renamed so they are more user friendly. This toot is called IndexGen but we call it INDEX for short.

It looks something like this :

 

Before we get into how it all works let's first look at how manuals are created and presented.

Publishing Process

If you go to the front page of FLOSS Manuals you will see lots of manuals listed. If you click on one (let's choose Audacity), then you see something like this:

Here you see the first page of the manual and the index on the left. INDEX is what we use to generate the manuals index that you see here. The PDF that is linked from this index also follows the order of the chapters you arrange with INDEX.

So...where do these chapters come from? Well, the process of writing and publishing a manual occurs in three steps: 

1. First you write the manual in the manual repository (http://www.flossmanuals.net/write)
2. Then you arrange the index using INDEX
3. Then the manual is published to static HTML and PDF using another tool (PUBLISH)
   

By using this process we separate the material that is being worked on from the manual that the reader sees. Hence the reader can read the nice 'stable' version of the manual online or as a PDF, while the manual continues to be developed.

Anatomy of a Manual 

So if you look at the Audacity manual repository (where you write the manual) you will see something like this :

You can use this interface to add chapters and edit chapters without the changes effecting the manual the reader sees. What you will notice is that the names of the chapters listed are different than the names of the chapters in the published manual. The following is the index of the audacity the reader sees :

In the above image you can see three components of the index. The first, at the top, is the title of the manual, in this case 'AUDACITY'. After the print and PDF icons we can see a section heading  - the first one is titled 'INTRODUCTION' and there are two chapters under this section heading - 'INTRODUCTION' and 'WHAT IS DIGITAL AUDIO?'. Then comes the next section heading 'INSTALLING' followed by the chapters that occur in that section etc.

The following is the table that displays the title, section headings, and chapters in the Audacity repository where the manual is written .

You can see that it follows the same structure as the published manual. Some of the chapters are not included in the published manual, these are included as a list at the bottom ('EditID3', 'Tester' etc).

Using INDEX

­The INDEX tool is a very simple drag and drop mechanism for arranging the index of the manual you wish to publish. If you use this tool to arrange the index of a manual you will see something like this:

 

Here we have the chapters of a manual that we can arrange into a nice index. If you look at the same manual in the repository you will see the exact same chapters listed :

As you can see the lists of chapters are the same.

Dragging Chapters 

Now we use INDEX to build the manual index by dragging chapters from the left list to the list on the right :

You can arrange the chapters in any order you like. You can also re-arrange them once they have been placed by dragging them up and down the order. Additionally, if you wish to remove one of the chapters from the new index you can drag the chapter back to the left box.

Adding  Sections

To add a new section you just need to click on the button labeled 'add section' and you will see a new section appear with the default title :

You can then drag this new section header to anywhere in the index.

Renaming Chapters and Sections

When you first create a chapter it has a 'wiki' name.  For example, when you look at the original list of chapters in the above example we see chapters like 'WhatIsABlog'. If you drag this chapter to the INDEX then you may wish to change the name to make it a little more readable and friendly. To do this you just need to double-click on the chaprer name or click on the blue 'EDIT' link. When you do this the chapter name turns into a editable text box:

You can then change the name by typing in the box. This is the name of the chapter that the readers will see. You can also use this method for changing the name of the manual (In the dark grey box at the top) and the sections (orange boxes).

Saving

When you have finished creating your index don't forget to click on the 'save' button.

Book Sprints

Book Sprints are an intensive working period with many writers collaborating over a fixed period of time. FLOSS Manuals is designing the technology and methodology to make these sprints effective and effecient short bursts of 3-5 days. Collaborators are in real space or working remotely and commuicating by the FLOSS Manuals toolset and IRC (Internet Relay Chat).

Although we have been involved in a few sprints the first 'full' scale sprint was the Inkscape Book Sprint which brought a team of writers from the official Inkscape documentaation team together in Paris to create a manual on the well known Vector Graphics software.

The sprint was a tremendous success and we will follow this up with more and more sprints on a diverse range of softwares - most recently this has meant the co-ordination of the OLPC/Sugar sprint in Austin Texas (August 2008).

IRC

For the purposes of Book Sprints we use IRC (Internet Relay Chat) to communicate with everyone. If you have never used IRC then don't worry! We have made it easy for you by making a web-based IRC chat. You can visit it at http://irc.flossmanuals.net , it looks something like this :

If you simply click on 'Login'  you will be taken to the Book Sprint discusssion room (called a channel in IRC-speak). A few seconds after pressing 'Login' you will see something like this :

If you see this then you have correctly connected to the Book Sprint discussion.

Send a Message

To chat you need to type your message  in the bottom text field. For example if I wanted to say hello I would type 'hello' here :

When I press return I see this :

Localize

FLOSS Manuals has a simple mechanism for translating the interface of the site. This enables the creation of different language versions of FLOSS Manuals. Localize is the name of a group of tools we developed for this purpose.

 

The above is the 'front page' of our localize tools. These tools help you translate the interface of FLOSS Manuals into other languages. Please note, this is not the same as translating the manuals themselves, we have other tools for this purpose.

You may only be given access to the localize interface for the purposes of translation. So if you never need to translate the FLOSS Manuals interface you will probably never see these tools.

Portable Object Files 

If you wish to choose a language to work on you simply click on the short name of the language on the left. These abbreviations all have the suffix '.po' that is because the interface of FLOSS Manuals is rendered by substituting the source language of the site (in this case English) with the appropriate Portable Object file (.po).  Portable Object files are used increasingly in free software projects for managing interface languages. Essentially it works like this:

1. Each English phrase ('source phrase') in the interface is represented in each '.po' file
   
2. The entire source phrase is used as a unique variable name
   
3. For each source phrase there is a corresponding translation in the relevant .po file
4. This translation is essentially the 'value' of the unique variable mentioned above
   
5. When you choose a non-English language interface, you are asking the site to substitute 'on the fly' the relevant variable with its new value

To make a new language version of the FLOSS Manuals website you need to open the '.po' file and create a translation for every source phrase. To do this we have built some nice tools for you so you can do all of this editing from within the browser.

Images 

In addition to the text phrases which are managed with .po files, some of the interface elements are contained within images. We do this quite a bit with FLOSS Manuals because using images in the interface gives you more control over look and feel. So the localize tool set has some interesting possibilities for replacing images which contain texts.

CSS

Additionally, different languages may need some changes to the layout because there are different character sets used. For this our localize tools have a browser based stylesheet (CSS) editor.

Getting Started

To get started with the the FLOSS Manuals localization tools you need to first choose a language you wish to work on. You can see that the front page of the localize tools has a list of languages on the left :

The languages are represented by 'locale abbreviations' and all end wiuth the suffix '.po'.

If you wish to work on one of these languages (for translation) then you need to simply click on the appropriate abbreviation. For example, if I was to choose German I would click on 'de.po'. Once I have done this more options will appear in the interface like so :

You can click on each of these tabs for different translation functions. You can also, at anytime, click on the "LANGUAGE' tab (the one you started with) to be returned to the start page. You can also see that in each tab is the name of the language you have selected :

Additionally, you can always tell which function of localize you are using by the color of the tabs. The active tab will always be a different colour to the others. For example, when I am in the 'start page' you will notice that the colour of the 'LANGUAGE' tab is pale while the rest are yellow.

The other tabs are, in brief, as follows :

TRANSLATE

If you click on this tab you access functions that enable you to translate the text in the .po file you have already chosen.

IMAGES & CSS

This section enables you to download, upload, and replace images in the interface. You can also edit the stylesheets for the language here.

SETTINGS

Generally you won't need to alter anything here. The setting is technical information specific to the .po. file you are working on. Unless you know what you are doing it is best not to change anything here.

TRANSLATE

To start editing the language you have chosen to work on click on the 'TRANSLATE' tab in the localize tools. It will take a few moments for the loading to occur and you will be notified of its progress :

The loading process stores all the phrases in the memory of your browser so that moving between phrases is faster and not reliant on the browser 'reloading' each time you work on a new term. Depending on your internet connection the loading should take less than a minute. When the page has loaded you will see a list of a lot of phrases:

On the left you see the original phrase in English, on the right you will see the translated phrase in the language you have chosen. 

To translate a phrase click on it and you will see the translation window appear :

You can see that the phrase you clicked on that you wish to translate is located in the 'Original string' box. The translation itself is in the 'Translated string' box. The 'Translation string' might be empty if the phrase has not yet been translated.

To translate the phrase you must copy the original string and translate only the words. The format of the translation must be kept intact. For example, with the above phrase you can see that the English word 'hour' has been translated to the German equivalent 'Stunde'. However the rest of the symbols, and the order of the symbols remains the same. This is very important.

When you have translated a phrase you can either navigate to another phraase for translation by clicking on 'NEXT>>' or '<<PREVIOUS' or you can click on 'CLOSE'. If you click 'CLOSE' you will be asked if you wish to save the changes :

If you wish to save the changes click on 'OK'. If you do not wish to save them at this stage press 'Cancel'. Both options will close the translation window. If you have chosen 'Cancel' then you can always save at a later time by clicking on 'Save Changes' in the TRANSLATION interface :

Please note that choosing this option will save all the changes you made since you chose the language in the LANGUAGES tab, so make sure you really wish to save all changes before doing this.

Navigation

You can navigate between phrases either through the translation window by clicking on 'NEXT>>' or '<<PREVIOUS'. These two links will move you incrementally through the phrases one at a time. However if you wish to proceed at a slightly faster pace you can close the translation window and scroll through the complete list of phrases using the scroll bar on the right (or a mouse scroll button if you have one) :

You can also refine the selection to scroll through by selecting one of the options at the top :

The options are as follows :

All - Show all phrases

Translated - show all translated phrases

Untranslated - show all untranslated phrases

Fuzzy - show all Fuzzy phrases (a fuzzy phrase is one that may need to be re-translated).

Localizing Images

Many of the interface elements in FLOSS Manuals are made from images. Some of these images contain text so it's necessary to be able to change these images to reflect the language version of the site. To access the functions to do this via the localisation tools you must click on the 'IMAGES & CSS' tab, then you should see something like this :

FLOSS Manuals uses 'skins' for determining layout. Skins control which images are used, the interface texts, and the colors etc. It is easy to change the entire look and feel of the FLOSS Manuals site or individual manuals by using skins. How you do this isn't so important to know here.

In this process we are going to select a  skin called 'floss2' from the drop down box shown :

It is very likely that you will then see the text as shown above ('Does not exist. Do you want to create it?'). You should create this so press 'Yes' and after a few minutes the drop down box will be refreshed, and you choose 'floss2' from the list:

On the left you see the list of images and css files. You can click on any of these names to view the files (they will open in a separate browser window). Listed is also the size of each file (which really doesn't matter so much but maybe useful in helping you identify any images that could be optmized).

There are four columns following the size column.

edit

This column will only appear for css files. The edit function allows you to edit the stylesheets from within the browser. If you click on edit you will see something like this :

You can type directly into the text box and then press 'Save changes' when you are finished. All changes will be effective immediately so it's best to pick a quiet moment to do this to minimise problems that may occur to visitors of the site.

rename

'rename' enables you to rename an image or css file. If you do this you may cause yourself problems as the file may not be able to be found by the FLOSS Manuals site using its new name. So you want to have a pretty good reason to change file names, but it if you do then this is the function to use. Pressing 'rename' brings up a window like this :

Simply type in the new name and press 'Rename'. Note : if you change the suffix of the file the format of the file will not be changed, so do not change a '.gif' image name to end with '.jpg' unless you know that the file is actually a jpeg.

download & upload

These two columns are titled pretty literally: 'download' enables you to download the file, and 'upload' enables you to upload the file. To translate an image you would first download that image (by clicking 'download' and saving it to your computer) and then translate the relevant texts in the file using your favourite image editor. Then you need to upload the translated image. To do this press 'upload' and a pop-up window will appear :

Click on 'Browse...' and a file browser window will appear. Use this to browse to the image you just translated. When you have found it and selected it, then press 'Upload' and the file will be uploaded. It doesn't matter what the name of the file you are uploading is as it will be renamed to the same name as the file it is replacing. For this reason it is very important that the file is of the same type. Don't try and replace a gif with a jpeg for example.

remove

To delete a file click 'remove'. This file will be permanently erased so be careful. When you click on 'remove' you will be presented with a window asking you to confirm the choice :

If you are sure you want to delete the file press 'OK' else click 'Cancel'.

­XCHANGE Introduction

Each FLOSS Manuals language site is a separate installation. Essentially this means that languages ­can be handled much more efficiently. To facilitate the transfer of documents between these separate installations FLOSS Manuals has built a system known as XCHANGE. This tool set enables any site within the FLOSS Manuals network to get content from any other site in the network.

The XCHANGE interface is very simple to use but is only accessible to administrators so it might be that you will never see this interface:

­

What you see here is a mechanism for transferring entire manuals and individual chapters (with images) from one language version of FLOSS Manuals to another. The process allows you to :

1. Preview the material before transferral
2. Choose chapters and manuals for transferring
3. Mark the migrated material as 'published', 'unpublished' or 'untranslated'
4. Rename the individual chapters or the manual

XCHANGE Basics

The interface for XCHANGE is divided into four parts: server, manual, chapter, and preview.

server

 

Through this drop-down list you can choose a list of servers from the FLOSS Manuals network. The list contains the abbreviations for the language of each server. For example the French FLOSS Manuals site is listed as 'fr'.

When you have chosen a server the manuals for that server are listed in the manual drop-down box.

manuals

 

When you select a server the box on the right of the image above will load with a list of manuals from that server. The administrator for that server has control of what you can and can't see in this list. When you select a manual from the list you will see the list of chapters for that manual in the text window below the drop down :

 

On the right of the manual section you also have a list of manuals that are already on the server you are working on. If you select a manual from that drop-down you will also see a list of chapters displayed.

Transferring Manuals 

To transfer a manual from the remote server to your server follow this simple process :

1. Ensure no manual is selected in the 'Existing Manuals' list
2. Select a manual from the drop-down list on the left
3. Click 'Transfer Manual'
   

A pop-up window will then ask you to confirm the transfer and you have the opportunity to change the name of the manual if you wish to:

 

You may wish to translate the name of the manual to your own language. You can also mark the manual and all chapters with a status. If you are copying the manual for translation then choose 'untranslated' from the drop-down menu. This is very important if you are using the 'XchangeTranslate' functions in FLOSS Manuals, as chapters marked with 'untranslated' will be given the option to use a translation interface for editing/translation.

If you decide you do not wish to transfer the manual click 'cancel', otherwise click 'transfer' and you will see progress bars while the transfer takes place:

When this process has completed the 'Existing manuals' drop-down will be reloaded and will list your new manual. All images have been copied and are marked with a suffix to tell you which server the images came from. This is so you can easily see which screenshots may need to be replaced by screenshots of the software in your own language. The manual will also appear in the 'write' section of the FLOSS Manuals site you are working on so you can begin editing/translating.

Chapters

The chapter section lists chapters for the manuals selected in the manual drop-down lists :

Clicking on a chapter in either list will display that chapter in the preview window :

Transfer Chapter

To transfer a chapter from the remote manual to a manual on the server you are working on follow these steps:

1. Select a manual from the drop-down menu on the left (a manual on the remote server)
2. Select a manual that you wish to transfer the chapter to from the drop-down menu on the right
3. Click on the chapter you wish to transfer
4. Click on 'Transfer Manual'

A pop-up will appear :

Here you can translate (rename) the name of the chapter. You can also mark the chapter with a status. If you are transferring the chapter for translation choose 'untranslated'.

If you wish to cancel the process choose 'cancel' else click on 'transfer' and progress bars will be displayed so you can see how long the process is taking. 

 

When the process has finished you will see the new chapter listed on the list of chapters on the right.

Preview

This section displays chapters selected for preview.

XCHANGE TRANSLATE

The XCHANGE TRANSLATE functions enable you to see translated manuals that have been transferred from another FLOSS Manuals language server. If you choose a manual to be edited you will see a list of all the chapters. Chapters that are to be translated will have an additional link 'translate' :

To translate a manual click 'translate' and you will see the translation interface :

On the left you see the original chapter in the original language :

This page is loaded live from the remote server. If the other server has renamed this chapter it is ok, it will still be displayed because Xchange Translate gives each chapter a unique identifying number. You see the version number of the chapter displayed (in this case 1.8) in the top grey box. You can also choose an earlier, or later (if there is one) version of the chapter for translation by selecting the version number in the drop-down box. This is primarily so you can see newer versions of the chapter in case you wish to translate or add part of the newer version.

On the right is the translation window. This is a WYSIWYG editor :

This begins empty so you can create the translated text. You can see all the images for the chapter by clicking on the small picture icon in the tool bar. All images that have been transferred with XCHANGE will put the images for a chapter in a directory with the same name of the chapter nested within a directory with the same name of the manual you are working on. Each image will also have a two-letter suffix which identifies the original language of the server it came from. This is so you can identify which screenshots may need to be remade in your own language.

When you have finished translating you may save the chapter by clicking on 'save'. Before you do this you may wish to change the status of the chapter from 'untranslated' to 'unpublished' which signals that the chapter is ready for checking (proofing) or publishing. You can change this status in the drop-down box before you click 'save :

License

All chapters copyright of the authors (see below). Unless otherwise stated all chapters in this manual licensed with GNU General Public License version 2

This documentation is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this documentation; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Authors

BOOK SPRINTS
© adam hyde 2008

---

CREATING CHAPTERS
© adam hyde 2007, 2008
Modifications:
Zita Joyce 2008

---

ACCOUNTS
© adam hyde 2007, 2008
Modifications:
Zita Joyce 2008

---

CREDITS
© adam hyde 2006, 2007, 2008

---

EDITING TOOLS
© adam hyde 2007, 2008
Modifications:
Zita Joyce 2008

---

EDIT A CHAPTER
© adam hyde 2007, 2008
Modifications:
TWikiGuest 2007
Zita Joyce 2008

---

FREE DOCUMENTATION
© adam hyde 2008

---

IRC
© adam hyde 2008

---

ARRANGING AN INDEX
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

INDEX TOOL INTRO
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

WHAT IS FLOSS MANUALS
© adam hyde 2006, 2007, 2008
Modifications:
Carlinhos Cecconi 2008
Zita Joyce 2008

---

IMAGES & CSS
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

INTRODUCTION
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

TRANSLATION
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

GETTING STARTED
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

READING MANUALS
© adam hyde 2007, 2008
Modifications:
Zita Joyce 2008

---

REMIXING
© adam hyde 2007, 2008
Modifications:
Zita Joyce 2008

---

WHY USE FLOSS MANUALS?
© adam hyde 2008
Modifications:
Brian Jordan 2008
Zita Joyce 2008

---

EDITING OVERVIEW
© adam hyde 2007, 2008
Modifications:
s chen 2007
Zita Joyce 2008

---

BASIC USAGE
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

INTRODUCTION
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

TRANSLATE
© adam hyde 2008
Modifications:
Zita Joyce 2008

---

 

_{Free manuals for free software}

 

 

General Public License

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneous