The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Anki-Import-0.016
River stage zero No dependents
/ Anki::Import

NAME

Anki::Import - Anki note generation made easy.

VERSION

version 0.016

OVERVIEW

Efficiently generate formatted Anki notes with your text editor for easy import into Anki.

SYNOPSIS

    # Step 1: Create the source file

    # Step 2: Run the anki_import command
      supplied by this module...

    # ...from the command line
    anki_import path/to/source_file.txt

    # or

    # ...from within a perl script
    use Anki::Import;
    anki_import('path/to/source_file.txt');

    # Step 3: Import the resultant files into Anki

DESCRIPTION

Inputting notes into Anki can be a tedious chore. Anki::Import lets you you generate Anki notes with your favorite text editor (e.g. vim, BBEdit, Atom, etc.) so you can enter formatted notes into Anki's database more efficiently.

At a minimum, you should have basic familiarity with using your computer's command line terminal to make use of this program.

Steps for creating, processing and imorting new notes

Step 1: Generate the notes with your text editor

First, you create a specially formatted source file which Anki::Import will process. The source file is a simple text file with basic formatting rules you must follow.

See the "General description of the source file" section for details.

Step 2: Process the notes with Anki::Import

Once the source file is created and saved, run the anki_import command from the command line or from a script to generate the import files. This will create a new directory called "anki_import_files" containing one text file for each of the note types generated by Anki::Import and which you will import in the next step. By default, the directory is created in the current directory.

See the "USAGE" section for more details and options.

Step 3: Import the processed notes with Anki

In Anki, open the deck you wish to import and hit Ctrl-I or (Cmd-I on a Mac) to start the import process, navigate to the a file generated by Anki::Import and select one of them.

Next, check Anki's settings to be sure you are importing notes into the proper fields, deck and note type. Also ensure you have the "Allow HTML in fields" option enabled and that you have "Fields separated by: Tab" selected.

Click "Import" and repeat for each note type you are importing.

Consult Anki's documentation for more details on importing and managing your notes.

General description of the source file

The source file contains one or more Anki notes. To make importing easier, each source file should contain notes that will be imported into the same Anki deck.

Creating notes and fields in the source file

Each note in the source file contains fields which should correspond to your existing note types in Anki. Individual notes in the source file are delineated by two or more blank lines. Fields are separated by a single blank line. Fields for each note should be in the same order as your Anki note types to make importing more automatic. All fields must have content or left intentionally blank.

To create an intionally blank field, add a single '`' (backtick) character on a line by itself with blank lines before and after the line with the single backtick.

See the "Source file example" for more help.

IMPORTANT: Save the source file as a plain text file with UTF-8 encoding. UTF-8 is likely the default encoding method for your editor but check your editor's settings and documentation for further details.

Assigning notes to note types

You can indicate which note type a note belongs to by preceding notes with a #note_type comment at the beginning of a line. You can choose any note type name you wish but it is recommended that you use note type names similar to those that exist in your Anki database to make importing the notes easier.

Any notes appearing after a note type comment will be assigned to that note type until a new note type comment is encountered (see the example in the next section). If no note types are indicated in your source file, the "Basic" note type is used.

Note types are used to help Anki::Import ensure other notes of the same type have the same number of fields. If the notes assigned to a particular note type do not all have the same number of fields, an error is thrown so be sure each note has the correct number of fields.

Note: note type sections can be split across the file (i.e. you do not have to group the notes of a particular note type together).

Tagging notes

Place your space seprated lit of tags in the last field. As long as there is one more field in the source files that fields in the note you are importing to, Anki will generate tags from the last field.

You can automate tag generation by placing a single '^' (caret) character on a line by itself immediately after your list of tags. These tags will now be used for all later notes in the file until they are overridden by a new list of automated tags. Also any new tags you place at the end of a note will be added to the list of tags that are automatically generated.

To reset the automated list of tags, place a single '^' (caret) character in place of the field where your tags will go.

To suppress the application of an automated tag from the list of automated tags for a particular note, include that tag in the tag field and it will not be tagged with that term for that one note.

Note: If you use tags on any of your notes in a parcitular note type, you must use tags on all of your notes or indicate that the tag field should be left blank with a '`' (backtick) character on a line by itself.

Applying text formatting to your notes

Learning how to format the source file is key to getting Anki to import your notes properly and getting the most out of Anki::Import.

Following a few simple rules, you can assign notes to a note type, preserve whitespace in fields, create bold text, create blank lines in your fields, add tags, create cloze deletions, indicate which fields are blank and generate simple lists. Study the example below for details.

Note: Lines containing only whitespace characters are treated as blank lines.

Source file example

Below is an example of how to format a source data file. Note that the column on the right containing comments for this example are not permitted in an actual source data file.

    # Basic                              # Any notes below here to the next
                                         # note type comment are assigned to
                                         # the 'Basic' note type

                                         # You can have blank lines between the
                                         # note type comment and the next
                                         # question.

    What is the first day of the week?   # Question 1, Field 1
                                         # Blank line here indicates a new field.
    Monday.                              # Question 1, Field 2

                                         # Add two or more blank lines between
                                           questions



    How many days of the week are there? # Question 2, Field 1

    Our caldendar                        # Question 2, Field 2
    has seven days                       # Answers can run
    in a week                            # across one or more lines but
                                         # will be imported as a single
                                         # line into Anki.



    # less_basic                         # New note type called "less_basic"
                                         # with 3 fields
    What is the third day of week?       # Question 3, Field 1

    Wednesday                            # Question 3, Field 2

    Wed.                                 # Question 3, Field 3

    your_tags go_here                    # We set up automated tags on this note.
    ^                                    # These tags will be applied to this and
                                         # all future notes unless overridden.


    Put {{{another question}}} here.     # Surround text with 3 braces for a cloze

    Here is an field that has
    `                                    # Insert a blank line into a field
    a blank line in it.                  # with a single backtick character
                                         # surrounded by lines with text.
    go_here                              # The note will *not* be tagged with
                                         # 'go_here' but it will still be
                                         # tagged with 'your_tags' from
                                         # the automated tag list.



    What does this code do?              # Another less_basic question

    ```                                  # Preserve whitespace in a field with 3
                                         # backticks on a single line
    This_is_some_code {
        print 'Whitespace will be        # Whitespace is preserved between the
               preserved';               # sets of triple backticks
    }
    ```                                  # end whitespace preservation

    This is %comma,delimted,text%        # Bullet lists with %item1,item2,item3%

    '                                    # To suppress all tags for a note,
                                         # leave the tag field blank with a
                                         # backtick.


    Final question                       # Field 1

    `                                    # Field 2 is blank.

    This is *in bold*                    # Field 3 has bold words, followed by a
    `                                    # blank line, followed by
    %an,unordered,list%                  # an ordered list.

    new_tags more_new_tags               # This and future notes will use these
    ^                                    # newer automated tags.

USAGE

anki_import can be run from the command line or from within another perl script. It behaves the same way in both environments.

Command line usage

The Anki::Import module installs the anki_import command line command for generating import files which is used as follow:

    anki_import source_file [parent_dir] [verbosity_level]

    B<Example:> anki_import notes.text /home/me --verbose

anki_import processes the source file and generates files to be imported into Anki, one file for each note type. These files are placed in a directory called anki_import_files. This directory is placed in the current working directory by default.

Note: Previously generated files of a particular note type will be overwritten by this command without warning.

parent_dir is an optional argument containing the path you want Anki::Import to save the files for output. You may use ~ (tilde) to represent the home directory for the current user.

$verbosity can be set to either --verbose (-v) or --vverbose (-vv) for verbosity and maximum verbosity, respectively.

From a script

Invoking the anki_import function mirrors the arguments used from the command line:

anki_import($source_file, [$parent_dir], [$verbosity]);

Usage in a script is the same as for the command line except that the arguments must be enclosed in quotes.

    Example:

    anki_import('script_file.txt', '/home/me', '--verbose');

See the "Command line usage" for more details on the optional arguments.

INSTALLATION

Anki::Import is written in the Perl programming langauge. Therefore, you must have the Perl installed on your system. MacOS and *nix machines will have Perl already installed but the Windows operating system does not come pre-installed with Perl and so you may have to install it first before you can use Anki::Import.

If you are unsure if you have Perl installed, open a command prompt and type in:

    perl -v

If Perl is installed, it will report the version of Perl on your machine and other information. If Perl is not installed, you will get a "not recognized" error on Windows.

Installing Strawberry Perl on Windows

If you are on Windows and you do not have Perl installed, you can download a version of Perl called "Strawberry Perl" from the Strawberry Perl website. Be sure to install the proper version (64 or 32 bit).

Once installed successfully, see the next section for downloading and installing Anki::Import.

Installing Anki::Import with cpanm

Anki::Import is easy to install if you have a Perl module called App::cpanimus installed. This module provides a command, cpanm, to easily downloading and installing modules from the Perl module repository called CPAN. Simply run this command from the command line to install Anki::Import:

    cpanm Anki::Import

Strawberry Perl for Windows has the cpanm already installed.

Installing Anki::Import without cpanm

If you do not have the cpan command on your computer, you will need to use either the older CPAN shell method of installatoin or, as a last resort, perform manual installation. Refer to the Anki::Import INSTALL file for further details on these installation methods.

REQUIRES

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

  perldoc Anki::Import

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)

https://github.com/sdondley/Anki-Import

  git clone git://github.com/sdondley/Anki-Import.git

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at https://github.com/sdondley/Anki-Import/issues.

SEE ALSO

Development status

This module is currently in the beta stages and is actively supported and maintained. Suggestions for improvement are welcome. There are likely bugs with the text formatting in certain edge cases but it should work well for normal, intended use.

Anki documentation

AUTHOR

Steve Dondley <s@dondley.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Steve Dondley.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.