[Zope] Zope Documentation

[Trevor Toenjes]

OK.  I have one final request before we really solidify the Zope Book as an
integral part of the NZO project.

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.

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 change.  My guess
is you only add to them.  And I don't think it is important that the
<name>'s make any serialized sense.

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).

Did this make sense?

-Trevor



> -----Original Message-----
> From: Chris McDonough [mailto:chrism@zope.com]
> Sent: Monday, August 12, 2002 4:42 PM
> To: Trevor Toenjes; Breuer, Yvon; Dieter Maurer; Sidnei@X3ng. Com. Br
> Cc: zope@zope.org; douwe@oberon.nl; zope@toenjes.com; jprice22@wvu.edu
> Subject: Re: [Zope] Zope Documentation
>
>
> > DAMN BOY!!
> > You are on top of things.  I will crawl back in my hole.  ;)
>
> Please dont! ;-)
>
> > You are doing some good things with the Zope Book.  Releasing 2.6
> docs
> > before the final 2.6.1 is VERY impressive.  lol.  is there going
> to be one?
>
> Well, luckily the book isn't finished either. ;-)
>
> > And you have a point, that the online Zope Book could be the place
> to
> > reference in many of the NZO requirement areas.  And if the ZBook
> has the
> > answer then we should  utilize it rather than recreating the
> wheel.
>
> Yup...
>
> > The proposed Software Product GUI goes a long way toward
> organizing
> > community released products and organizes product specific how-tos
> in that
> > area.
> > hmmm, now you have me thinking that how-tos should be categorized
> as Zope,
> > non-specific scripts, and Product specific.
>
> Coming up with a howto taxonomy is not easy... but I think you
> should just go for it! ;-)
>
>