[Zope] Zope Documentation

[Chris McDonough]

> For convenience, Talkback really needs to make the use of
bookmarks in each
> chapter easier.  It is not even obvious that it has bookmarks.
And
> therefore no one can really reference sections of the Zope Book.
>
> 1. It should be obvious that "Using Object Properties" location is
>
http://www.zope.org/Documentation/Books/ZopeBook/current/BasicObject
.stx#2-4
> 3
> without reading the HTML source.

Unfortunately, these numbers change as paragraphs are added and
removed from the document, so they're not reliable as permanent
links (unless the document doesn't change, which it does as the
result of comments).  I think we're going to have to punt here and
say "see chapter foo, search for bar", because I'm not going to be
able to create permanent link targets for each paragraph any time
soon.  It's a two-step process... make link targeting work in
BackTalk then (perhaps manually) edit all the chapters to include
permanent link targets.  It's just not possible for me to do this
right now (time-wise).  If someone else wanted to take it on, I'd
say yay and urge them on fervently from the sidelines. ;-)

> How about having the <h2> titles in a table at the top of every
Chapter with
> their respective <a>nchors?

This might work but note that the Book is composed entirely in
structured text, so it's not just a matter of including HTML, it
needs to be written into the framework.  "Punting" and using HTML in
the book source would be might be OK, but I'd feel dirty afterwards,
and it would be confusing to folks reading the
(as-yet-nonexistent-but-promised) text-only version. ;-)

> Can we just make the location www.zope.org/ZopeBook and this will
be the
> location for the current version.

Err, not really, unfortunately.  The containment structure (and thus
the URL) is necessary for versioning the book and BackTalk generates
absolute URLs for chapters (by design).  Note that you *can* get to
any Zope Book chapter as well right now via links like
http://www.zope.org/Documentation/ZopeBook/ChapterName.stx as well,
but it will just redirect you to the longer URL for the chapter.
How about http://makeashorterlink.com ?  I agree this is annoying
but it's not high on my "must fix" list. ;-)

> But I have noticed you are moving chapters around which does
affect the URL.
> So maybe we need some error handling.  But non-existent bookmarks
don't
> produce a 404.  So it would be convenient if you could inspect the
> QUERY_STRING to capture the "#foo" name request and try and
resolve it with
> a redirect if it doesn't exist in the requested page.
> So any URL request with a bookmark has a chance to resolve to the
intended
> location, even if the URL is incorrect (mostly to make room for a
new
> chapter).

I actually have been very careful to not remove any chapters but
this is something that will need to be addressed soon, you're right.
But not now. ;-)

I dont mean for this to sound negative at all, I really really
appreciate all of the input... I'm just incredibly time-strapped at
the moment, so I can't in good faith promise anything beyond what
already exists.  If anyone wanted to spelunk BackTalk
(http://backtalk.sourceforge.net) to add these features, I'd love to
see them.

- C