<!DOCTYPE Rambledocs SYSTEM  "~/dtd/rambledocs-3.dtd" >
<Rambledocs>
  <General-comments>
    <Node Title="Supporting multiple browsers.">
      <Text-Node>
	For now, the worker functions only support Netscape.  Later,
	it will be more general.  It will use buffer-local
	variables.  Where will they be set up?
      </Text-Node>
      <Text-Node>
	The style variables could be at one of several levels:
	Independent variables or a single variable accessing a style
	structure.  I've chosen to put them all in a style structure,
	which is more robust.
      </Text-Node>
      <Text-Node>
	Completing-read poses a problem with the structure, so we'll
	just make it a list starting with its name.
      </Text-Node>
    </Node>
    <Node Title="Testing">
      <Text-Node>
	We need to test:

	The bookmark-holder builder(s), at least that we can find stuff
	in them the way they're built.

	That new files are built while old files are not.

	That a buffer given to hbmk-make-insertion-target twice appears
	only once. 
      </Text-Node>
    </Node>
    <Text-Node>
      It would be nice to have a user-controlled default-directory for
      make-file etc, that defaulted to where it was last called.

      (let* 
      ((default-directory "~/.netscape/bookmarks/"))
      (call-interactively #'hbmk-make-file))

      ...will do it, but we need a configurable variable for that.
      Ideally that variable should retain what it was set to in
      hbmk-make-file, but even configurableness helps a lot.

    </Text-Node>
    <Node Title="Parameterizing targets">
      <Text-Node>
	These 3 variables may be merged into hbmk-style.

	However, that would require some extra work: Every opened file
	must be given the write-style, known by assoc.  Then each call
	must look that style up, and *in the proper buffer*.  Can't
	afford any mistake here.

	hbmk-sgml-path-to-bookmarks is used once, just after the style
	is set.

	hbmk-write-bookmark-f is called in 2 places, once in source,
	once in target, so it really needs separate styles.  It has
	the proper current buffer each time.

	hbmk-build-bookmark-holder-f is used when the buffer isn't set
	up yet.  It needs careful handling.

	hbmk-make-insertion-target could possibly take a style parm,
	given in hbmk-add-destination-file and hbmk-make-file, but
	that only solves the thing that wasn't a problem.  Would be
	smoother, tho.

	hbmk-make-file could find a style parm, presumably with assoc,
	which it would both use and pass to
	hbmk-make-insertion-target.  hbmk-add-destination-file would
	also create it and pass it to hbmk-make-insertion-target, in
	the future possibly learning it from the file itself.  And
	that would solve the "where does the target style come from?"
	problem.

	But shall I actually do it?  It works now, and I don't see a
	great need for other targets, so no.

      </Text-Node>
    </Node>
  </General-comments>
  <Component Name="hbmk-process-next-bookmark">
    It would be nice to be able to put a bookmark into several
    different files, ie, to return a list.  But simply yanking it
    (C-y) every time will work.  Perhaps an optional arg would say,
    "don't kill the region"

    It would be nice to process multiple ones in a row until aborted.
    We'd simply enclose this in another command.
    
    It would be nice for the hbmk-pick-destination prompt to show a
    truncated description of the url, but that can wait.

    Problematic in Lynx-style: List elements appear to include
    everything after them.  We must somehow prevent it from eating the
    remaining entries.  Find the real end of the Lynx elements.  Just
    find the first child that is itself a LI, and consider that the
    end tag.

    So we'll have a different cut function for each style.

  </Component>
  <Component Name="hbmk-get-bookmark-element">
    If we don't find an element, we could possibly climb parents until
    we do.  I'm not sure that behavior would be useful, but I'll add
    it if needed

  </Component>
  <Component Name="hbmk-sgml-next-el">
    When cursor is within the initial element's text content, the
    behavior of returning no element doesn't seem sensible.  Instead,
    if it's unambiguous we should return that element.  

    It's unambiguous if that element has no children, ie if (null
    (sgml-element-content parent)).  We'll see whether that behavior
    proves useful.  It seems useless, because if the thing is a leaf
    it's not a bookmark.  Perhaps it would be controlled by a parm, eg

'(if
   (and 
     use-if-in-text
     (null (sgml-element-content parent)))
   parent
   ------------a ;;Do as we have been doing
   )

    Renamed to tehom-sgml-next-el

  </Component>
  <Component Name="hbmk-setup-buffer">
    Later it may make sense to permanently remember what style files
    are, because the names rarely change.

    We may call this at the beginning of every function that alters
    the data, so we're guaranteed to be set up.

  </Component>
  <Component Name="hbmk-pick-destination">
    If hbmk-destination-alist is empty, create or add a file.  Would
    be nice to be able to create or load a file at this time.
    hbmk-make-file does all that, given a filename.
    
    One potential method is to have pseudo-file choices, which are
    recognized when they come back here.  Which an empty
    destination-alist would force.  So we'd start off with a
    destination-alist that contained only the element "*New file*" nil?

    Then it's harder to recognize the empty list.  But for the user,
    seeing all the choices in one place is better, since they're
    homogeneous except for "*New file*

    And it could be friendly to have a persisting list of
    target-files, perhaps an entire directories' contents.  That could
    be customizable, or a precursor that understood directory-trees
    could be.

    But the real issue here is just user-friendlyness.  

    If we ever want to handle more diverse instructions than just
    "*Add a destination*", we will change the loop to
    (while (not (markerp destination)) ... )
    and the switch from `unless' to 
    (cond 
    ((markerp destination))
    ;;Handle the others as symbols.
    )
    

  </Component>
  <Component Name="hbmk-add-reference">
    It must somehow be prevented in Netscape-style bookmark files.
    Perhaps such files will be treated as read-only except for
    purposes of this.  Perhaps we'll do something with
    hbmk-add-html-reference that prevents it from writing in such
    files.

    Add (when (string= (-name) "Lynx")) around the code here, or else
    in hbmk-add-html-reference?  Which should have some more
    protection against running aground in non-Lynx-style files.  Or
    check something more meaningful, perhaps the presence of the
    builder & writer?  For now, we just check that it's not Netscape.

    This could be smarter, finding a good position if point isn't in
    a writeable position.
  </Component>
  <Component Name="hbmk-build-bookmark-holder">
    This may stop being variable, or it may include
    hbmk-add-html-reference in the variability.

    tehom-psgml-add-element-to-element should make inserting the
    document much easier ... do away with sub-nodes and sometimes with
    case-sensitivity.  And be able to force the inclusion of some
    nodes (meta will not let itself get included)
    
    And tehom-psgml-add-element-to-element should use linebreaks even
    when inserting a succession of start elements.

    Meta doesn't work yet, I'm not sure why, but somehow it doesn't
    find itself a valid position.  It's not because it's optional:
    BASE and ISINDEX fire fine.  It has the same problem if it's
    lower-case, "meta".

    Could also add:
    '("META"
     ("http-equiv" . "content-type")
     ("content" . "text/html;charset=iso-8859-1"))


  </Component>
  <Component Name="hbmk-make-file">
    Does this always return the destination if any?
  </Component>
  <Component Name="hbmk-add-html-reference">
    Destinations are assumed to always be ordered-list style, close to
    Lynx style but not exact.
  </Component>
  <Component Name="hbmk-destination-alist-init-data">
    Eventually this will specify files and directories to auto-add to
    hbmk-destination-alist.  For now it just specifies the "*Add a
    destination*" element.  But that element could even be
    specifically added later.

  </Component>
  <Component Name="hbmk-netscape-get-data">
  </Component>
  <Component Name="hbmk-make-insertion-target">
    Would be nice to return the marker if it already exists.

    ;;Set the style.
    ;;Make style buffer-local
    '(make-variable-buffer-local 'hbmk-style)
    '(setq hbmk-style (assoc hbmk-write-style hbmk-style-alist))

  </Component>
  <Component Name="(hbmk-style (:type list))">
    Possibly add more components to say how to create and write
    bookmarks into such files. 
  </Component>
  <Component Name="hbmk-style-alist">
    
    But the destination files are *not* Lynx style, they are hbmk
    style, proper HTML.  So I added another style, "hbmk".

  </Component>
  <Component Name="hbmk-sgml-path-to-bookmarks">

  </Component>
  <Component Name="hbmk-bookmark-url-at-point">
    This could be part of a text-style, in parallel to the other
    styles.  But that doesn't seem correct, since text modes aren't
    specific about markup like that, and since occasionally it could
    be used in HTML that simply didn't use the url as an anchor.
  </Component>
</Rambledocs>
