Help for LC BookMark engine

The new system of self-mantained bookmarks replaces the former self-mantained system based on manually edited HTML files, which in turn replaced any browser built-in (and dependent) bookmark system for "permanent" bookmarks.

The maintenance

• The auxiliary table booktopics
  This manually mantained table lists
  • the topic (unique)
  • the subtopic per-topic (more than one)
    in both topic and subtopic name avoid characters which require URL-encoding, in particular avoid the ampersand (write e.g. Web/HTTP not Web&HTTP)
  • the priorities per topic and subtopic (0 highest, 99 lowest)
    the priorities are used to sort the topics and subtopics for display

• The primary table bookmarks
  This semimanually mantained table lists
  • the url of the bookmark
    can be a full URL, a local URL, or a string without embedded blanks in the case of separators (e.g. a mnemonic like separator-antivirus)
  • the description (or title) of the bookmark
  • the topic selected from the list in booktopics
    if the same URL has to be assigned to more topics enter separate records
  • the subtopics which can be a comma-separated list of subtopics usually taken from the list in booktopics, but can be also other "free" subtopics or keywords (will be searched differently)
  • the priority for display (0 highest,99 lowest) (inside topic and subtopic when applicable)
  • the status of the bookmark which can be one of
    • remote (the default, the URL is a full remote URL)
    • local (the URL is on the local machine)
    • wayback (the original URL is no longer reachable, so the system will automatically prepend to it what is necessary to search on the wayback machine)
    • gone (the original URL is no longer reachable and is mantained just for the record)
    • separator (there is no URL but just a description, e.g. to make a title for a group of bookmarks ... in this case the separator should have an unique priority n, and all the group members a priority n+1 (or n+m provided there are no interlopers)
    Different status uses different colour for display as shown above.
  The table can be populated using the line-mode mysql client, or the private servlet, which is also the catch-all tool for maintenance (particularly when the reserved CGI scripts fail because of the presence of URL-encoding in fields).

The CGI scripts

These are the CGI scripts:

• BMindex.cgi
  is intended to be called as a <!--#include virtual="BMindex.cgi" --> from some home page. It presents a list of buttons for all the topics, plus a list of buttons for the first n (e.g. 5) subtopics of each-topic in priority order, plus a catch-all button per-topic and a search form.

• BMTop.cgi?topic=topic
  is called by the topic buttons, or can be saved in the browser bookmark list. It displays a frameset with two row of buttons in the top frame. The top row lists all the topics with the current one highlighted. The bottom row lists the classified subtopics of the current topic, plus a catch-all button and a search form.
  The output appears in the lower frame (initially blank)

• BMBot.cgi?topic=topic&subtopic=subtopic
  is called by the subtopic buttons in BMTop and produces in the bottom frame the list of bookmarks for the given subtopic (it should be avoided to call it directly since the output will go in the top/parent frame, and won't contain the navigation buttons)
  A subtopic of all is used for the catch-all buttons: it will list all the bookmarks, grouped by subtopic.

• BMBoth.cgi?topic=topic&subtopic=subtopicis called by the subtopic buttons in BMIndex, or can be saved in the browser bookmark list. It combines the previous two functions, i.e. generates a frameset and loads the button rows in the top frame (with both current topic and subtopic highlighted) and the result of the query in the bottom frame.

• BMButt.cgi?topic=topic and BMButt2.cgi?topic=topic&subtopic=subtopic
  are service calls used respectively by BMTop.cgi and BMBoth.cgi to generate the button rows in the top frame. They are actually soft-links to the same script. These scripts are not intended for direct use.

• BMSearch.cgi?topic=topic&subtopic=subtopic&what=subtopics|description|url
  is the service call invoked by the search form present in all the major pages.
  The topic is provided explicitly by the user in BMindex.cgi and as a hidden parameter by BMTop.cgi and BMBoth.cgi. A topic=all allows to search irrespective of topic. This is available only via the menu in BMindex.cgi.
  The subtopic is not really a subtopic but a search pattern, which can be matched (as an imbedded string) with either subtopic or description or domain as passed via radio button what.
  De facto this allows free searches for any subtopic even if not listed in table booktopics and not displayed in any button. It also allows free searches in the title, or for the domain or path in the URL.

• BMurl.awk
  is a service call used by BMBot.cgi and BMSearch.cgi to reformat the bookmark as returned by the mysql query (it takes care of colouring the link according to status, of prepending the "wayback" code to the URL, and of adding the hidden link for the reserved editing script.
  It receives the topic via an awk -v variable.
• BMtopic.awk and BMsubtopic.awk
  are service calls used by BMButt[2].cgi to generate the HTML code for the buttons (taking care of optionally highlighting the current topic or subtopic).
  They receive the topic (and subtopic when needed) via an awk -v variable.

The reserved CGI scripts

• BMedi.cgi?topic=topic&url=url&
  is invoked by an hidden link (you do not expect me to reveal it, do you ?) associated to each bookmark.
  It generates (in a separate named window) a form which allows to
  • change the status of the bookmark
  • and/or change the priority entering it explicitly or just increasing or decreasing it (ticking on the radio buttons without changing the numeric value)
  • and/or editing the subtopics (use a comma separated list, and enter either registered subtopics or any string of your choice)
  • (the above edits apply all together pressing the submit button)
  • or delete the bookmark
  There is no return code. The edit is attempted but may fail if the bookmark URL contains something requiring URL-encoding which is not recognised. In such case use the private servlet, or the mysql line mode client.

• BMDoEdi.cgi
  is the service call invoked by the above form to perform the editing (mysql update table)
• BMDoDel.cgi
  is the service call invoked by the above form to perform the editing (mysql delete)