The SRESI bookmarks manager

Table of Contents

Entrance

Introduction

Examples

User Manual

  1. Overview
  2. Command-Line Mode
  3. Search Patterns
  4. Hints
  5. Export Formats
  6. Native Format
  7. Performances

Bookmarks Import

Technical Notes

Possible Evolutions

XBEL Formatting

Downloads

Links

User Manual

Overview

When called sresi-php, the program sends messages in HTML, otherwise in text. The command line version is good for a short set of actions, and quite compact. It only does what it is asked, nothing more (to be brief, it does not save its state unless you explicilty ask it to).
For successive modifications, You should use save and restore the data set from one invocation to another, or better yet, the program state. This last option allows you to save the undo stack, for example.

Command-Line Mode

Overview

The first argument can be the archive file to work on, as a shortcut. Otherwise, the possible arguments are as follow:

Usage of the CLI interface:
sresi [<archive name>] [COMMANDS]
Startup:
--help
-h
print this message;
--help formats
-h formats
print help on the possible formats;
--help selection
-h selection
print help on the selection patterns;
--version
-v
display the version information and exit.
Data input:
--import <file name> as <format>
read a file in the specified format;
-i <file name>
read a DSV file;
-ia <file name>
read an archive file,
this is also the default when the file is given without a -i switch;
-id <file name>
read a Delicious file;
-ih <file name>
read an HTML SRESI file;
-im <file name>
read a Mozilla file;
-io <file name>
read an Opera file;
-ix <file name>
read an XBEL file.
Selection:
-bf '<pattern>'
--filter-bookmarks '<pattern>'
filters bookmarks according to <pattern>,
this is a destructive operation, use '--undo' to cancel it,
type sresi -help selection to get more help on selection patterns.
Data merge:
--merge <file name> as <format>
merge a file in the specified format;
-m <file name>
merge a DSV file;
-ma <file name>
merge an archive file;
-md <file name>
merge a Delicious file;
-mh <file name>
merge an HTML SRESI file;
-mm <file name>
merge a Mozilla file;
-mo <file name>
merge an Opera file;
-mx <file name>
merge an XBEL file.
Data export:
--export <format> [to <file name>]
exports in the specified format to a standard output or a file;
-e <file name>
save as a DSV file (archival, hand-editing);
-ea <file name>
save as an archive file (archival);
-ed <file name>
export as a Delicious file;
-eh <file name>
export as an HTML SRESI file (archival, display);
-ej <file name>
export as an HTML and Javascript file;
-el <directory name>
export as a 'light' HTML portal;
-em <file name>
export as a Mozilla file;
-eo <file name>
export as an Opera file;
-ep <directory name>
export as an HTML portal;
-ex <file name>
export as an XBEL file.
Bookmark edition:
-ba <titre> <url> <tags>
--add-bookmark <titre> <url> <tags>
to add a bookmark;
-bd '<pattern>'
--delete-bookmarks '<pattern>'
to tag the bookmarks corresponding to <pattern> for later removal;
-bc
--confirm-delete
to really delete the bookmarks set aside previously;
-br <pattern> to <title>
--rename-bookmark <pattern> to <title>
to rename a bookmark;
-bu <pattern> to <url>
--update-bookmark <pattern> to <url>
to change a bookmark's URL.
Tag edition:
-ta <tags> [in '<pattern>']
--add-tags <tags> [in '<pattern>']
to add a tag, possibly in a subset of the bookmarks;
-td <tags> [in '<pattern>']
--delete-tags <tags> [in '<pattern>']
to delete a tag, possibly in a subset of the bookmarks;
-tr <tag> to <tag>
--rename-tag <tag> to <tag>
to rename a tag in all its occurences;
-ts <tags> to <tags> [in '<pattern>']
--swap-tags <tags> to <tags> [in '<pattern>']
to swap a list of tags for another, possibly in a subset of the bookmarks.
Hint edition:
-ha <tag> with '<tags>'
--add-hint <tag> with '<tags>'
to add a hint,
<tag> is the parent and <tags> are the descendants;
-hr '<tags>' from <tag>
--restrict-hint '<tags>' from <tag>
to limit a hint and reduce its descendants,
<tags> are the descendants to remove and <tag> is the parent;
-hd '<tag>'
--delete-hint '<tag>'
to delete the hint based on <tag>.
Miscellaneous edition functions:
-b
--balance
to balance the data structures if the data set was edited deeply enough to change the tag hierarchy since they were last computed.
-st <titre>
--set-title <titre>
to change the portal title.
Statistics:
-s [in '<pattern>']
--stats [in '<pattern>']
to count the bookmarks, tags and hints used;
-tl [in '<pattern>']
--tag-list [in '<pattern>']
to list all the tags used;
-hl
--hint-list
to list all the hints defined.
Cache functions:
--undo
to cancel the previous operation (can be chained);
--redo
to repeat a previously cancelled operation (can be chained).
Program state:
--dump
to dump the complete program state;
--restore
to restore a previously dumped program state,
program dumps are not compatible from one version of SRESI to the next

Search Patterns

The search pattern is a boolean expression, using tags, names and URLs. When special characters are used, it is better to put double quotes around the offending expression.

~
for an approximate match (name, URL and tag list only);
!
for boolean Not;
&
for boolean And;
|
for boolean Or;
( ... )
for block separation;
{ ... }
for a name match;
< ... >
for an URL match;
[ ... ]
for a tag list match.

An approximate tag list will match bookmarks with all relevant tags. An exact tag list will match bookmarks with only the tags and no other.

Be liberal with spaces, as the lexer can be easily confused. Please express complex patterns such as names or URL between double quotes ("). Real quotes must be escaped as usual (\").

When invoked from the command line, the selection pattern should be put between single quotes (') to single it out as one argument.

Hints

It is possible to deduce many relationships while working on tags and the bookmarks that bear them, but some things will get muddled without explicit help. That is what I call Hints.

A hint is an explicit declaration of relationship between tags:

  • one is the parent;
  • a set of others are the descendants.

Whenever it is useful to emphasize the relationship between the descendants, the parent tag will be added to the mix. This happens when, at any point in the bookmarks tree, branches originate from several descendants and unrelated tags all.

As hints are a SRESI exclusive, you will have to build them yourselves. Putting them in an otherwise empty DSV to merge with your bookmarks during operation is the easy way, and the smart one until SRESI is ready to take over all your bookmarks management needs. .

Export Formats

Sresi supports a few export models, described here. The names and alternatives used here are other ways to refer to them when using sresi.
Case does not matter.

SRESI (also Archive or Caml)
This is a serialisation of SRESI's data; it is not meant for users to parse, but the program can read it directly without any data manipulation. It can also keep the tree and portal structures if they have been created when the file is saved.
Del.icio.us (also Delicious, Del or Deli)
Del.icio.us is a (rather well known) social bookmarking system, also using tags. Delicious tags are single words, however, so while import into SRESI is easy enough, export may not always be possible.
DSV
DSV is a grand sounding acronym for a very simple thing: Delimiter-Separated Values. The delimiter is here the vertical bar ('|') between the main fields, with the comma (',') used to separate the secundary fields (at this time, the tags). More detail later.
DSV is the smallest way to store SRESI data is a user-readable way, but the program makes many checks while loading it, which takes a lot of time.
HTML Sresi
This is functionally equivalent to DSV, but written in a XHTML file: This displays better in a browser, but is more cumbersome to hand-edit.
Javascript (or Js)
Js gives an HTML plus Javascript page, directly filched from Torisugari's design. For a legible result, please use his stylesheet and icons.
Mozilla (also Firefox, Moz, Netscape)
The old Netscape and Mozilla bookmarks format, in its simple form. The recent additions are not supported.
Opera (also Op)
The Opera bookmarks format, as far as I understand it (I do not use Opera myself).
Portal (also HTML, XHTML)
This is the most complete export as far as navigation data goes. It is a portal-like structure, a file per folder and per bookmark.
Light Portal (also light)
This is similar to the full portal above, with slightly less information. It is a portal-like structure, a file per folder.
XBEL
XBEL is the XML-based format used by browsers such as Konqueror, Kazehakase or Galeon. There are slight variations, which I do not deal with.

It is relatively easy to add new exports: the structure and presentation of the data are well-separated.

DSV File Format

The file format is very simple, for user parsing and writing.

It contains one information per line: either title, bookmark or syntactic hint. These three categories must be clearly labeled as respectively TITLE:, HINTS: and BOOKMARKS:. While it is recommended to keep everything grouped, it is a matter of user convenience, not because the program needs it: they can be mixed with no problem (only the last title is used, though).

If necessary, the different fields in each line are separated by a vertical line ('|'). Blank lines and extra spaces are ignored. Initial tag capitalisation and order do not matter either, as all tags will end up sorted and lowercased.

Bookmark are defined by three fields of data:

  • first comes the name;
  • second comes the URL;
  • third and last comes a comma (',') separated list of tags.

Hints are defined by two fields:

  • first comes the master (or parent) tag;
  • second and last comes a comma (',') separated list of descendant tags.

As the programs cleans up the file for its own use, it is possible to do a straight read and export to get a better-formatted file: sorted bookmarks, with each tag cleaned-up and normalised.

Caveats

Do not use a vertical bar in your bookmark names, or you will mess up the DSV import. It is possible to escape them, however.

Similarly, while SRESI is tolerant about tags, do not use commas or vertical bars.

Apostrophes and quotes are probably not a good idea either, but they do work.

Performances

On reasonable data sets (a few hundred bookmarks and a few score tags), results are quasi instantaneous.

On the other hand, the algorithms are not so efficient, so increasing the size of the data set to the thousands of bookmarks and hundreds of tags sends everything spiralling down the drain. Besides the algorithms themselves, I also suspect the compared sizes of processor cache and data set matter quite a lot.

Here are my results, on about 3400 bookmarks and 700 tags, the processor is an AMD K7 2500+ (Barton core, 512 kilobytes of cache and 1800 MHz of real (not marketing) frequency):

  • import from the original XBEL or the corresponding DSV: about 13s;
  • linear export (Delicious, DSV or HTMLsresi): instantaneous;
  • hierarchical export (HTML+Javascript, Mozilla, Opera, XBEL): about 8s;
  • light portal: add about 3.5s to the tree;
  • full portal: add about 5s to the light portal.

Initial parsing is very slow, so using the archive format is recommended for repeat operations. DSV is human-readable and editable and the format will not change like OCaml's serialisation may: it is safer for storage.

As SRESI is not yet mature, especially as far as interface is concerned, using it for its advanced exports while keeping bookmarks in the original format is the safer option.