[ZWeb] Zope Book important to NZO/need help

[Trevor Toenjes]

Is anyone interested in helping add some features to Backtalk, while
maintaining the goal of creating a text-only version with STX?

Chris M pointed out that the Zope Book should be used as often as possible
as the online reference for NZO.  Where NZO is promoting Zope, links to the
book will be helpful.

Since the Zope Book is the only online documentation that allows annotation
and stays current with Zope versions, I think this is a crucial effort that
has been a little overlooked (at least from me.)

example:
He is adding content that explains when to use DTML, p-scripts, ZPT,
external methods, and python products.
Then we don't have to reinvent the wheel for NZO.

This should help the NZO with the frontpage and technical overview pages.

Now for the help part.
The Backtalk software doesn't allow for the easy use of bookmarks.  They do
exist if you read the HTML source.
Someone needs to burn some brain cells trying to figure out how to make
bookmarking sections of a chapter to work and scale as the Zope Book grows.

Here are some thoughts...

For convenience, Backtalk 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.
Currently only the Chapter is referenced and the user has to scroll and try
and find the relevant section.

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

2.  And the placement of the <name> id's need to be before the <h2> headers
so the bookmark doesn't skip the title to display the following paragraph.

3.  Can we put a hot spot near each section headline so a mouseover displays
the URL with the bookmark so people can reference it in Documentation?
Either use CSS to make the whole title an anchor to itself using
a.h2  {text-decoration: none.}

or put some other more obvious object near the headline.

4.  And we need to shorten the URL length.
Documentation/Books/ZopeBook/current kills an email link by wrapping it and
makes the URL unusable.

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

Now, I havent put in full thought of the persistence of these links for
archive references, but I imagine that the bookmarks don't really change and
therefore it is NOT important that the <name>'s make any serialized sense.

But chapters might be moved 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).

So we need someone to architect a Chapter/section function.  Maybe this will
be only for the HTML part of Backtalk and the eventual text-only version
wont have this function?

Did this make sense?

-Trevor