initial work on user manual

.gitignore

@@ -4,3 +4,5 @@
 *~
 /icons_rc.py
 ankiqt/forms
+/docs/manual.html
+/docs/docbook-xsl.css

docs/Makefile

@@ -0,0 +1,5 @@
+all: manual.html
+
+manual.html: manual.txt Makefile
+	a2x -v -f xhtml -d book manual.txt
+	sed -i -e 's/margin: 1em 5% 1em 5%;/width: 65em; margin: 0 auto 0;/' docbook-xsl.css

docs/manual.conf

@@ -0,0 +1,2 @@
+[titles]
+	underlines="__","==","--","~~","^^"

docs/manual.txt

@@ -0,0 +1,474 @@
+Anki User Manual
+__________________
+Damien Elmes <anki@ichi2.net>
+
+Introduction
+============
+
+Anki is a program which makes remembering things easy. Because it is a lot
+more efficient than traditional study methods, you can either greatly decrease your
+time spent studying, or greatly increase the amount you remember in a given
+amount of time.
+
+Anyone who needs to remember things in their daily life can benefit from Anki.
+Since it is content-agnostic and supports images, audio, videos and scientific
+markup (via LaTeX), the possibilities are endless. For example:
+
+ - learning a language
+ - studying for medical and law exams
+ - memorizing people's names and faces
+ - brushing up on geography
+ - practicing guitar cord recognition
+
+There are two simple concepts behind Anki: 'active recall testing' and 'spaced
+repetition'. They are not known to most learners, despite having been written
+about in the scientific literature for many years. Understanding how they work
+will make you a more effective learner.
+
+Active recall testing
+---------------------
+
+'Active recall testing' means being asked a question and trying to remember
+the answer. This is in contrast to 'passive' study, where we read, watch or
+listen to something without any output. Studies have shown that active recall
+testing is far more effective at building strong memories than passive study.
+There are two reasons for this:
+
+ - The act of recalling something 'consolidates' the memory, increasing the
+   chances we'll be able to remember it again
+ - When we're unable to answer a question, it tells us we need to return to
+   the material to review or relearn it
+
+You have probably encountered active recall testing in your school years
+without even realizing it. When good teachers give you a series of questions
+to answer after reading an article, or make you take weekly progress-check
+tests, they are not doing it simply to see if you understood the material or
+not. By testing you, they are increasing the chances you will be able to
+remember the material in the future.
+
+You don't need to leave it up to teachers, however. Consider a language
+learner who wants to memorize the following Indonesian words:
+
+|============
+|one   |satu
+|two   |dua
+|three |tiga
+|============
+
+Many students will look at each line in turn, concentrating on it for a few
+seconds before moving on. This is passive learning, and so the results will
+not be great. However, if you cover the right-hand side and check if you
+recall each word, you'll find your initial memories are stronger.
+
+Active recall testing can make for stronger initial memories, but it's only
+part of the solution to learning efficiently.
+
+The importance of review
+------------------------
+
+Even with active recall testing, if you wait too long before testing again,
+you'll find you've forgotten most of the material you tried to learn. This can
+be very demotivating, as it can feel like no progress is being made towards
+your goals. In order to avoid this disappointment, it's essential to review
+previously learnt material.
+
+Despite the importance of review, it is often overlooked by learners. Part of
+the reason for this is that reviewing was traditionally difficult. If you have
+a page with 50 new words on it and you learn them in one day, some words will
+fall from your memory the next day, others a few days after that, and others
+may last a few weeks or more. It is difficult to return to the page and review
+only the words you're about to forget.
+
+Traditional paper flashcards make it easier to acquire material than a single
+page with a list of words, since you can separate the cards into "known" and
+"not-known" piles. They don't make it very easy to review the material in the
+following weeks, however.
+
+Spaced repetition
+-----------------
+
+The 'spacing effect' was reported by a German psychologist in 1885. He
+observed that we tend to remember things more effectively if we spread reviews
+out over time, instead of studying multiple times in one session. Since the
+1930s there have been a number of proposals for utilizing the spacing effect
+to improve learning, in what come to be called 'spaced repetition'.
+
+One example is in 1972, when a German scientist called Sebastian Leitner
+popularized a method of spaced repetition with paper flashcards. By separating
+the paper cards up into a series of boxes, and moving the cards to a different
+box on each successful or unsuccessful review, it was possible to see at a
+glance a rough estimate of how well a card was known and when it should be
+reviewed again. This was a great improvement over a single box of cards, and
+it has been widely adopted by computerized flashcard software. It is a rather
+rough approach however, as it can't give you an exact date on which you should
+review something again, and it doesn't cope very well with material of varying
+difficulty.
+
+The biggest developments in the last 30 years have come from the authors of
+SuperMemo, a commercial flashcard program that implements spaced repetition.
+SuperMemo pioneered the concept of a system that keeps track of the ideal time
+to review material and optimizes itself based on the performance of
+the user.
+
+In SuperMemo's spaced repetition system, every time you answer a question, you
+tell the program how well you were able to remember it - whether you forgot
+completely, made a small mistake, remembered with trouble, remembered
+easily, etc. The program uses this feedback to decide when to show you the
+question again. Assuming you don't forget a given question, the delay between
+reviews gets bigger and bigger - so you may see a question for the first time,
+then 3 days later, 15 days later, 45 days later, and so on. Because each
+successive repetition results in a higher interval, the number of reviews
+necessary on a given day is quite small, so this method can scale to hundreds
+of thousands of cards entered in over a decade or more. And because the next
+interval is adjusted depending on your previous performance for a given
+question, it ensures you do the absolute minimum number of reviews necessary
+to continue to remember the material.
+
+Why Anki?
+---------
+
+While there is no denying the huge impact SuperMemo has had on the field, it
+is not without its problems. The program is often criticized for being buggy
+and difficult to navigate. It only runs on Windows computers. It's proprietary
+software, meaning end-users can't extend it or access the raw data. And while
+very old versions are made available for free, they suffer from a number of
+bugs.
+
+Anki addresses these issues. You are not forced to pay for it, so stuggling
+students and teachers with budgetary constraints are not left out. It's open
+source, with an already flourishing library of plugins contributed by
+end-users. It's multi-platform, running on Windows, Mac OSX, Linux/FreeBSD, and
+some mobile devices. And it's considerably easier to use than SuperMemo.
+
+Internally, Anki's spaced repetition system is based on an older version of
+the SuperMemo algorithm called SM2. Subsequent versions have managed to
+squeeze out a little more learning efficiency, but they come at the cost of
+greatly increased complexity, and they are more susceptible to scheduling
+errors in real-world use. For a more in-depth discussion of this and the
+differences in scheduling algorithms, see the bottom of
+http://ichi2.net/anki/wiki/FrequentlyAskedQuestions[the Anki FAQ].
+
+Installing & upgrading
+======================
+
+Windows
+-------
+
+ - Download the installer from http://ichi2.net/anki/download/index.html[the
+download page].
+
+ - Double click on it to run it.
+
+ - If you are upgrading, there is no need to uninstall the existing version of
+Anki, but please close your current copy of Anki before trying to install the
+new one.
+
+ - If you want to run Anki from a USB stick, follow the instructions on
+http://ichi2.net/anki/wiki/FrequentlyAskedQuestions[the Anki FAQ].
+
+Mac OSX
+-------
+
+ - Download the DMG from http://ichi2.net/anki/download/index.html[the
+download page].
+
+ - Open it and drag the icon into your Applications folder.
+
+ - If you want to run Anki from a USB stick, simply drag it to the USB stick
+   instead.
+
+ - Follow the same steps to upgrade to the latest version, but make sure
+you've closed any running version of Anki first.
+
+Linux/FreeBSD
+-------------
+
+The currently recommend method is to install Anki from source, or use the deb
+on http://ichi2.net/anki/download/index.html[the download page] if you are a
+Debian/Ubuntu user. You may find a version of Anki is included with your
+distribution, but at the time of writing a number of distros include a very
+old version of Anki that has a number of known bugs.
+
+To install Anki from source, download the tarball from
+http://ichi2.net/anki/download/index.html[the download page], extract it, and
+read the README file.
+
+Getting started
+===============
+
+Anki is basically a intelligent flashcard program. First, you add a series of
+questions and answer pairs (called 'cards'). These cards are stored in a file
+called a 'deck' (as in "deck of cards"). You can add cards by typing them in
+yourself, importing them from a text file, or you can use a deck someone else
+has shared. Once you have a deck with some cards in it, you can start
+reviewing and improving your memory.
+
+[[creating-own-deck]]
+Creating your own deck
+----------------------
+
+The most effective way to use Anki is to create your own deck, by typing in
+questions and answers yourself. For example, you hear a new word on TV and
+decide you want to memorize it? Jot it down and add it to Anki when you have a
+chance. You learnt the chemical formula for Sodium Hydroxide in your text book
+and don't want to forget it? Type it into Anki. When Anki later shows you the
+idea again, you will probably remember the context you learnt it in, leading
+to a stronger memory.
+
+*To create your own deck*:
+
+ 1. Open Anki.
+ 2. Choose File->New.
+
+*To add a new card to your deck*:
+
+ 1. Click image:images/list-add.png[] on the toolbar.
+ 2. Enter the question on the 'Front' area and the answer on the 'Back'.
+ 3. Click 'Add', or press Ctrl+Enter (Command+Enter on a Mac).
+
+You'll see a screen like the following:
+
+image:images/addcards.png[]
+
+'Front', 'Back' and 'Add' are the important elements for now - the rest we'll
+return to later. Front is a required field, so it is marked yellow until you
+input something. The back can be left blank, so it is not drawn in yellow.
+
+Making questions
+----------------
+
+Turning a given idea into a question and answer pair is simple once you know
+how.
+
+For general knowledge
+~~~~~~~~~~~~~~~~~~~~~
+
+Imagine you've just heard the following sentence:
+
+  Canberra was founded in 1913.
+
+The easiest way to test this is to make a 'cloze deletion'.
+
+ 1. Type the above sentence into the 'Front'.
+ 2. Highlight '1913'.
+ 3. Click the >> button to reveal more options.
+ 4. Click the [...] button.
+
+As an alternative to steps 3 & 4, you can just press F9.
+
+You'll end up with:
+
+image:images/cloze2.png[]
+
+For languages
+~~~~~~~~~~~~~
+
+Imagine you're learning learning German and you hear the word 'bitte', meaning
+"please". There are a number of ways to add this to Anki.
+
+*As a word recognition card*:
+
+Put 'bitte' on the front of the card, and 'please' on the back. When this card
+appears later, you'll need to read the German word and decide if you knew the
+meaning or not.  Recognition cards are easy to answer and will ensure you can
+recognize the word when it pops up in the future.
+
+*As a word recall card*:
+
+Put 'please' on the front of the card, and 'bitte' on the back. When this card
+appears later, you'll need to think of how to say please in German. Recall
+cards are more difficult to answer, but will ensure you can produce the given
+word yourself, rather than just recognize it. They are best used in the early
+stages of learning, to reinforce basic grammar and core vocabularly. As your
+knowledge of the language grows, recall cards become less practical, as
+synonyms complicate matters.
+
+*As a sentence recognition card*:
+
+You can also add the full sentence you encountered to the front of the card,
+optionally underlining the new word. On the back you can place a translation
+of the full sentence, or just the target word. Adding the full sentence takes
+more time, but means you're exposed to the word in actual use.
+
+*As a sentence recall card*:
+
+Sentence recall cards should be limited to core grammar or essential
+phrases, as they are very difficult to answer correctly.
+
+*As a combination of the above*:
+
+It's possible to add more than one card at once by clicking on the button at
+the top right of the 'Add Items' screen. This can be useful if you're learning a
+language where reading a word is non-trivial, and you want to practice both
+reading and producing the word.
+
+Advanced input
+~~~~~~~~~~~~~~
+
+If you want to input audio, pictures, movies or scientific markup, please see
+the dedicated section below about adding content.
+
+Using a shared deck
+--------------------
+
+Using a shared deck saves you from having to type in information yourself.
+This is more convenient, but is not always the optimal way to learn. Consider
+the user in <<creating-own-deck>> who enters new words they hear on TV. To
+them, simply looking at the word should be enough to remember the context it
+was used in and the meaning, naunce, etc. But to a different person using this
+shared deck, it is just a single word with no context or personal
+significance.
+
+That is not to say shared decks are useless. Shared decks that are used in
+conjunction with third party material such as a textbook can be quite useful.
+If you and the original sharer are studying the same textbook, then you both
+has the same exposure to the original idea in context. 
+
+Shared decks that include some context on the cards (such as full sentences)
+can also be quite useful.
+
+To browse shared decks:
+
+ 1. Click File->Download->Shared Deck.
+ 2. Type in a string to search for, or scroll through the list.
+ 3. Select a deck you're interested in, and click OK. The deck will be
+ downloaded and will open up.
+
+Reviewing
+---------
+
+When you have found a deck you like or entered some cards in, it's time to
+start reviewing. If the 'Add Items' screen is still open, close it by clicking
+on close or pressing Esc. You should see a screen entitled 'Study Options':
+
+image:images/studyoptions-basic.png[]
+
+In the above example, it says there are 6 new cards today, and 6 new cards
+total. If you've downloaded a shared deck, there will probably be more than 20
+new cards, but Anki will only show you 20 per day by default. You can adjust
+this number by changing 'new cards per day', but be wary of setting it too
+high or you'll have many reviews to do over the next few days.
+
+When you're ready, click 'Start Reviewing'. You'll then see a screen like
+this:
+
+image:images/review1.png[]
+
+Here you need to look at the question and think about the answer. It can help
+to say the answer out loud, but that is not necessary. It's ok if it takes you
+a little while to recall the answer, but as a general rule if you can't answer
+within 10 seconds, you should give up.
+
+When you're ready, click 'Show Answer' or press the spacebar. You'll see
+something like the following:
+
+image:images/review2.png[]
+
+Now you need to decide how well you remembered. Anki gives you four options.
+
+Adding material via anki
+========================
+ - best practices
+ - all buttons / shortcuts
+ - changing fonts
+ - adding text to every card
+
+Fonts and colours?
+==================
+x
+
+
+Reviewing / main window
+=======================
+ - what you see on the main screen
+ - what buttons to press (see next section)
+
+
+Study options
+=============
+x
+
+
+Browsing your deck
+==================
+x
+
+Importing & Exporting data
+==========================
+
+Importing
+---------
+
+text files, mnemosyne, etc
+
+Exporting
+---------
+
+...
+
+Printing
+--------
+
+...
+
+Card props
+==========
+x
+
+Deck props
+=========
+x
+
+Preferences
+===========
+x
+
+Cramming
+========
+x
+
+Graphs
+======
+x
+
+Statistics
+==========
+x
+
+
+Plugins
+=======
+ - japanese/chinese/german etc
+
+
+Sharing decks/plugins
+=====================
+x
+
+Priorities
+==========
+x
+
+Inactive tags
+=============
+x
+
+Synchronization
+===============
+x
+
+Leeches
+=======
+x
+
+Media support
+=============
+x
+
+Progress bars
+=============
+x
+
+Running from a usb driver
+=========================
+x