߂


iPod Note Reader User Guide
April 25, 2003

iPod 2.0 software brings exciting new features to your iPod, including a Note Reader that
displays text files that are stored in the Notes folder on the iPod.

The Note Reader also displays the folder hierarchy in the Notes folder, allowing you to organize
your notes.

The size of any single note is limited to 4kb, any text beyond 4kb is truncated.

The Note Reader supports up to a thousand notes, if there are more than a thousand notes in the
Notes folder only the first one thousand will be loaded.
Notes are cached. If a note has been read into the cache, the hard disk can display it without
spinning up the iPodfs hard disk. Up to 64Kb of notes can be read into the cache at one time.
Once the 64Kb cache limit is exceeded, the oldest notes are discarded as new information is read
in.

Tags

The Note Reader supports some basic HTML style tags. These tags are not case sensitive.

Force a paragraph break by including <BR> or <P> and </P>.

By default, notes are listed using the file name unless you specify a name with the Title tag.

<TITLE>New Title</TITLE>

This is useful with .link files, described below. It can also be used in the Preferences file, also
described below.

The <INSTRUCTIONS> tag is unique in that it causes the entire contents of the note to be
replaced by short instructions on using the Note Reader, and the file name to be listed as
gInstructionsh, both in the currently selected language.

Links To Files

One note can link to another note. A link looks like this:

<A HREF="note file">Link to another note</A>

Links are underlined when displayed on the iPod. By pressing the select button the link is
followed. If more than one link is visible at a time, only one will be underlined. Use the scroll
wheel to move between multiple links.

Links can specify a file with an absolute or a relative reference. Absolute references always start
in the Notes folder. Relative references start in the folder the original note is in.

Absolute links look like this:

<A HREF="file:///note file">Link to another note</A>
<A HREF="file:///folder/note file">Link to another note</A>
<A HREF="/note file">Link to another note</A>
<A HREF="/folder/note file">Link to another note</A>

Relative links look like this:

<A HREF="file://note file">Link to another note</A>
<A HREF="file://folder/note file">Link to another note</A>
<A HREF="note file">Link to another note</A>
<A HREF="folder/note file">Link to another note</A>

Folder can be a link destination.

The top level of the Notes folder can not be link destination.

A file outside the Notes folder also can not be a link destination.

A link cannot refer to a .link file, described below.

File names in links are not case sensitive.

Links are checked to make sure they specify a file that actually exists. Dead links are listed in the
<ERRORS> tag, described below.

.Link Files

If a file name ends in .link and contains a link, when the user selects the .link file they
immediately follow the link to the specified file or song.

For instance, if the file named File1.link contains the text:

<A HREF="File2">The link</A>

When the user selects File1.link File2 will be presented and the contents of File1.link will not be
shown.

.Linx Files

If a file name ends in .linx and contains links, it is presented as if it was a folder containing .link
files, one for each link.

Regular items in folders are listed in alphabetical order. Links listed in .linx files are listed in the
order they appear in the .linx file and are not alphabetized.

If a file named Main.linx exists in the top level of the Notes folder, it is used for the Note Reader
main screen, replacing the actual contents of the Notes folder. If the Main.linx file has a <TITLE>
tag, it overrides the <TITLE> tag in the Preferences file, if one exists.

Path Delimiters

When linking to a file in another folder, the folders and file names in the path must be delimited
with either a forward slash e/f, backslash ef, or colon e:f as in the below example:

Folder/file
Folderfile
Folder:file

The three path delimiters are equivalent.
Note that all three path delimiters are illegal characters for FAT file names, and that colons are
illegal characters for HFS+ file names.

If a folder name itself contains these special characters they must be escaped with a backslash.

Example: A link to a file named gMeeting 10/12/02h would be represented this way:

<A HREF="Meeting 10/12/02">Link to another note</A>

If the first or last character of a file or folder name is a slash or backslash, even with escapes it
could be ambiguous which characters are part of the file or folder name, and which are path
delimiters. In this case you should use a colon as a path delimiter.

For example, a link to a folder called gFolderh would be represented this way:

<A HREF="Folder:note file">Link to another note</A>

You cannot specify a folder above the starting folder. For a link in a sub folder to specify a file in
a folder above it, it must use an absolute specification.

Full path names must fit in 255 characters. More specifically, they must fit in 255 UTF8 Unicode
bytes, and in 510 UTF16 Unicode bytes. Some characters expand to more than one UTF8 byte or
more than two UTF16 bytes, so some paths may not fit even though they would appear to. See
the Unicode specification for details.

Files whose full paths are too long are not loaded, and no error is reported. Note that this applies
to other iPod applications as well, such as Contacts and Calendars.

Links To Songs

Linking to a song is similar to other links:

<A HREF="song=My Way">Link to My Way</A>

If there are multiple songs named My Way, the user cannot select among using this link format.

<A HREF="ipod:music?playlist=Road Music">Link to Roadie</A>
<A HREF="ipod:music?genre=triphop">Link to a genre</A>
<A HREF="ipod:music?artist=Todd Rundgren">Link to FZ</A>
<A HREF="ipod:music?composer=Beethoven">Link to Beethoven</A>
<A HREF="ipod:music?album=The Wall">Link to Pink</A>
<A HREF="ipod:music?song=Althea">Link to Althea</A>

Filters can be combined to create a temporary playlist of songs that match all filters.

<A HREF="ipod:music?genre=rock&artist=Brian Eno">Combo</A>

By default, the Now Playing screen comes up when the user selects a music link. This can be
specified for all notes, or for a single note, with a preference setting. See the Preferences section
below.

You can override this for a single link with the Now Playing tag.

<A HREF="ipod:music?song=Althea&NowPlaying=false">Link to Althea</A>

If a play list is selected, the only other filter you can use is a song. You can only have one
selection for each filter type.

All matching is case insensitive, but otherwise must match exactly. Wild card characters are not
supported.

Links are checked for formatting errors but links are not checked for validity to see if the song
actually exists. Errors are listed in the <ERRORS> tag. See Preferences and the Errors tag,
described below.

Encoding

By default all note files are considered to be encoded in Latin1, unless the iPod language is set to
Japanese, Korean, or traditional or simplified Chinese, in which case all note files are assumed to
be in that encoding.

A note file can be tagged as having a different encoding. See the example below.

<?xml encoding="MacJapanese"?>

The following encodings are supported: Latin1, MacRoman, MacJapanese, Korean, simplified
Chinese, traditional Chinese, UTF8 Unicode and UTF16 Unicode.

The following encoding names are supported:

For Latin1: iso-8859-1, Latin-1.
For MacRoman: x-Mac-Roman, Mac, Macintosh.
For MacJapanese: x-Mac-Japanese, Mac-Japanese, MacJapanese, Shift-JIS, Shift_JIS.
For traditional Chinese: x-Mac-Chinesetrad, Mac-Chinesetrad , BIG5, CN-BIG5.
For simplified Chinese: x-Mac-Chinesesimp, Mac-Chinesesimp, EUC-CN.
For Korean: x-Mac-Korean, Mac-Korean, EUC-KR.
For UTF8 Unicode: UTF8, UTF-8.
For UTF16 Unicode: UTF16, UTF-16, UCS2, Unicode.

(Each line lists multiple names for the same encoding, not separate encodings.)

Some of these encodings are not actually identical, but they are treated as if they were; for
instance EUC-CN is not precisely the same as simplified MacChinese, but it is rendered as
simplified MacChinese on the iPod. This will work for almost all characters.

UTF8 and UTF16 Unicode can also be specified with a Byte Order Mark (BOM). Byte swapped
(little endian) UTF16 files are supported, but only with a BOM but not with an encoding tag.
Note that TextEdit adds a BOM when saving UTF16 files, but not when saving UTF8 files. BBEdit
7.0.3 will display the file encoding, whether or not it has a BOM, and has options to save it with
or without a BOM.

The only way to display multiple encodings in the same note is to use Unicode.

If the encoding tag and the BOM disagree, the encoding tag overrides the BOM. Encoding tags
are not case sensitive.

The encoding tag must be placed at the top of a file, before any non-ASCII text, otherwise, a null
char in non-ASCII text may prevent the parser from getting to the encoding tag. Only one
encoding tag is allowed per file.

Do not put null characters in encodings that use null as a terminator such as Latin1, MacRoman,
and UTF8 or else the text will be truncated at the null character.

Preferences

Global preferences can be specified by including a file called Preferences in the top level of the
Notes folder. Preferences are written in XML format.

Local preferences can be specified for any note file by including XML preference tags within the
file that overrides any equivalent global preference for that note.

If multiple tags for the same preference in a single note are found only the last preference parsed
will be used for the entire note.

Preferences for any note can be displayed with the <SHOWPREFERENCES> tag. If any local
preference overrides a global preference, the local value is displayed, otherwise the global value
is displayed.

Preferences are set with these XML incantations:
<meta name="LineWrap" content="true">
<meta name="ShowBodyOnly" content="true">
<meta name="HideAllTags" content="true">
<meta name="NowPlaying" content="true">
<meta name="NotesOnly" content="true">

One or several preferences can be set at once, and not all have to be specified. Preference values
can only be gtrueh or gfalse.h All preferences default to false except for NowPlaying, which
defaults to true.

If LineWrap is set to false, LF and CR in notes are respected. Mac, PC, and Unix style returns are
treated equally. If LineWrap is set to true, LF and CR are ignored, and only <P> and <BR> cause
new lines.

ShowBodyOnly will only display the portion of the note within <BODY> </BODY> tags, if
present. If <BODY> tags are not present, the entire note is displayed.

HideAllTags removes all <> style tags before displaying the note, including unrecognized tags.

NowPlaying controls whether the Now Playing screen appears after selecting a link to a song.

NotesOnly, also called Museum Mode, causes the iPod to boot into the Note Reader screen, and
prevents the user from exiting the Note Reader. This allows the creation of custom or restricted
user interface. NotesOnly can only be set in the global preferences file, not in individual note
files.

The title of the main Note Reader screen can be set by specifying a <TITLE> tag in the global
preferences file.

Preferences, like all tags, are not case sensitive.

Errors

To save time manually verifying your note files, the Note Reader automatically checks each note
for errors.

Any note containing the <ERRORS> tag will have its entire contents replaced by errors found
while parsing the note files.

Only one note with an <ERRORS> tag is required to see all of the errors in all note files.

Various types of errors are reported, including badly formatted tags and dead links that specify a
non-existent file or song.

Known Issues

A link to the Notes folder cannot be created.

While displaying the list view (list of files and folders), the hard drive sometimes does not spin
down.

Music filters cannot contain an ampersand. For instance, these links do not work:

<A HREF="ipod:music?genre=country&western">Link to genre</A>
<A HREF="ipod:music?artist=hall&oates">Link to artist</A>

When the preference HideAllTags is true, some HTML comments are not properly hidden.


Copyright (C) Apple Computer, Inc.
http://developer.apple.com/hardware/ipod/ipodnotereader.pdf