navigation menu for documents

Hi,

Le 14 juil. 09 à 22:17, Andrew Dunstan a écrit :

For a very long time I have thought that it would be useful to have
some sort of navigation menu for the docs

Oh yes, pretty please :)

Navigating the docs requires far too much use of the back button and
up links, IMNSHO. A menu frame would make them far more usable.

No, please, no frame! Really...

What I'm thinking about is to extend current "breadcumb" at the top of
the page to include chapter, section, subsection. So that for exemple
the following page:
http://www.postgresql.org/docs/8.3/interactive/datatype-geometric.html#AEN5480

Would have at its top:
Home → Documentation → Manuals → PostgreSQL 8.3 → Data Types
→ Geometric Types → Points

Well the last entry, Points, I'm not so sure about. But I think you
get the idea.

Regards,
--
dim

Dimitri Fontaine wrote:

Hi,

Le 14 juil. 09 à 22:17, Andrew Dunstan a écrit :

For a very long time I have thought that it would be useful to have
some sort of navigation menu for the docs

Oh yes, pretty please :)

Navigating the docs requires far too much use of the back button and
up links, IMNSHO. A menu frame would make them far more usable.

No, please, no frame! Really...

Yes, really. What you suggest here is just not adequate, IMNSHO. I don't
want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where I
want directly.

I know some people have a violent aversion to frames, but I don't. They
have legitimate uses.

What I'm thinking about is to extend current "breadcumb" at the top of
the page to include chapter, section, subsection. So that for exemple
the following page:

http://www.postgresql.org/docs/8.3/interactive/datatype-geometric.html#AEN5480

Would have at its top:
Home → Documentation → Manuals → PostgreSQL 8.3 → Data Types →
Geometric Types → Points

Well the last entry, Points, I'm not so sure about. But I think you
get the idea.

Compared with what things like doxygen or webhelp give you it's not
remotely what I want.

cheers

andrew

Le 15 juil. 09 à 00:21, Andrew Dunstan a écrit :

Yes, really. What you suggest here is just not adequate, IMNSHO. I
don't want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where
I want directly.

Ok we don't share the same needs here, and I get what you're after.

I know some people have a violent aversion to frames, but I don't.
They have legitimate uses.

Agreed, but even when they do, I find I'm not shortening the time
needed to find my link. Here the navigation frame will either contain
too much entries to be useful (you'll need to scroll around), or will
have some expand/collapse tree that will make you click way to much to
be proficient in your search. IMO.

Compared with what things like doxygen or webhelp give you it's not
remotely what I want.

Ok.

Regards,
--
dim

Andrew Dunstan wrote:

Yes, really. What you suggest here is just not adequate, IMNSHO. I don't
want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where I
want directly.

Are you talking about the online manuals, or something else here?

--
Richard Huxton
Archonet Ltd

Richard Huxton wrote:

Andrew Dunstan wrote:

Yes, really. What you suggest here is just not adequate, IMNSHO. I
don't want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where
I want directly.

Are you talking about the online manuals, or something else here?

I don't care if we don't provide this for the online manuals on
postgresql.org - I'm quite happy to install it on my own server if
necessary. But I am talking about the HTML docs that come from our /doc
directory. And I bet if we had the option of better navigation, our
online users would want us to provide it.

cheers

andrew

Andrew Dunstan wrote:

Richard Huxton wrote:

Andrew Dunstan wrote:

Yes, really. What you suggest here is just not adequate, IMNSHO. I
don't want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where
I want directly.

Are you talking about the online manuals, or something else here?

I don't care if we don't provide this for the online manuals on
postgresql.org - I'm quite happy to install it on my own server if
necessary. But I am talking about the HTML docs that come from our /doc
directory. And I bet if we had the option of better navigation, our
online users would want us to provide it.

Shouldn't be too hard to come up with something reasonable with a little
css. Something only activated if javascript is turned on or some such.
Give me 48 hours and I'll have a play.

--
Richard Huxton
Archonet Ltd

2009/7/15 Andrew Dunstan <andrew@dunslane.net>:

Dimitri Fontaine wrote:

What I'm thinking about is to extend current "breadcumb" at the top of the
page to include chapter, section, subsection. So that for exemple the
following page:

 http://www.postgresql.org/docs/8.3/interactive/datatype-geometric.html#AEN5480

Would have at its top:
 Home → Documentation → Manuals → PostgreSQL 8.3 → Data Types → Geometric
Types → Points

Yes, really. What you suggest here is just not adequate, IMNSHO. I don't
want to have to scroll to the top or bottom of the page to get navigation,
and I want to be able to see the navigation and go where I want directly.

Even if we are going to have some kind of tree-based navigation
sidebar beastie, I would be a hearty +1 in favour of doing Dmitri's
breadcrumb suggestion anyway.

I think we can agree that a full breadcrumb/ancestry trail is superior
to "Up/Home", and unlike the sidebar nav idea doesn't require any
fancy scripting shenanigans or possible browser compatibility strife.

Compared with what things like doxygen or webhelp give you it's not remotely
what I want.

So let's have both.

Cheers,
BJ

Brendan Jurd escribió:

2009/7/15 Andrew Dunstan <andrew@dunslane.net>:

Dimitri Fontaine wrote:

Would have at its top:
 Home → Documentation → Manuals → PostgreSQL 8.3 → Data Types → Geometric
Types → Points

Yes, really. What you suggest here is just not adequate, IMNSHO. I don't
want to have to scroll to the top or bottom of the page to get navigation,
and I want to be able to see the navigation and go where I want directly.

Even if we are going to have some kind of tree-based navigation
sidebar beastie, I would be a hearty +1 in favour of doing Dmitri's
breadcrumb suggestion anyway.

I would agree that the breadcrumbs are a good idea, except that I'm
confused about it including the complete website navigation (instead of
just the docs). IMO the list should be
Home → Data Types → Geometric → Types → Points
(where "Home" points to the top of 8.3 docs).

What happened to the contest for a website redesign anyway?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On Wednesday 15 July 2009 02:27:32 Richard Huxton wrote:

Andrew Dunstan wrote:

Richard Huxton wrote:

Andrew Dunstan wrote:

Yes, really. What you suggest here is just not adequate, IMNSHO. I
don't want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where
I want directly.

Are you talking about the online manuals, or something else here?

I don't care if we don't provide this for the online manuals on
postgresql.org - I'm quite happy to install it on my own server if
necessary. But I am talking about the HTML docs that come from our /doc
directory. And I bet if we had the option of better navigation, our
online users would want us to provide it.

Shouldn't be too hard to come up with something reasonable with a little
css. Something only activated if javascript is turned on or some such.
Give me 48 hours and I'll have a play.

You just have to generate the full ToC on every HTML page and then use the
right CSS to make it float where you want it. I suspect that that method
might make the build very slow, though.

All,

For a very long time I have thought that it would be useful to have some
sort of navigation menu for the docs

Oh yes, pretty please :)

Navigating the docs requires far too much use of the back button and up
links, IMNSHO. A menu frame would make them far more usable.

No, please, no frame! Really...

Yes, really. What you suggest here is just not adequate, IMNSHO. I don't
want to have to scroll to the top or bottom of the page to get navigation,
and I want to be able to see the navigation and go where I want directly.

I know some people have a violent aversion to frames, but I don't. They have
legitimate uses.

Frames are (imho) very difficult to maintain. An easy alternative is
use of floating divs, possibly combined with javascript to make it fit
nicely to the window size. That way, 'breadcrumb' is always visible.
And I believe it is a lot easier to set up and maintain (generate)

Just my 2ct

HTH

Regards,

Serge Fonville

On Jul 14, 2009, at 3:21 PM, Andrew Dunstan wrote:

Yes, really. What you suggest here is just not adequate, IMNSHO. I
don't want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where
I want directly.

Hey Andrew,

Check out what I've done for the Bricolage documentation:

http://www.bricolagecms.org/docs/devel/api/

I'm using jQuery to pull the proper doc into a div. I'm still noodling
with it, trying to fix encoding issues on Windows, but it's pretty
close to done.

Best,

David

David E. Wheeler wrote:

On Jul 14, 2009, at 3:21 PM, Andrew Dunstan wrote:

Yes, really. What you suggest here is just not adequate, IMNSHO. I
don't want to have to scroll to the top or bottom of the page to get
navigation, and I want to be able to see the navigation and go where
I want directly.

Hey Andrew,

Check out what I've done for the Bricolage documentation:

http://www.bricolagecms.org/docs/devel/api/

I'm using jQuery to pull the proper doc into a div. I'm still noodling
with it, trying to fix encoding issues on Windows, but it's pretty
close to done.

Yes, that's nice, it's just the sort of thing I had in mind - if you can
do it with a div instead of frames I'm fine with that.

cheers

andrew

On Jul 16, 2009, at 12:49 PM, Andrew Dunstan wrote:

I'm using jQuery to pull the proper doc into a div. I'm still
noodling with it, trying to fix encoding issues on Windows, but
it's pretty close to done.

Yes, that's nice, it's just the sort of thing I had in mind - if you
can do it with a div instead of frames I'm fine with that.

Yep. If I can solve the bloody encoding issue with Windows, it'll be
good to go with Pod docs, and easily portable to any HTML-based docs.

Best,

David

OK, if you untar the attached in the docs dir there are a three separate
sets of changes in it. It all functions, but consider it a discussion
point rather than a patch. Presumably we'd need to discuss a patch over
on the docs mailing-list.

1. Fixed navigation
Copy STYLING/stylesheet.css over the existing one and you will have
static navigation links top and bottom of the page.

2. Titles on navigation links.
Run ./STYLING/title_links.pl and it should add title attributes to the
navigation links. This means hovering over the top links gives the title
of the page they will go to. Presumably we could do this directly from
the sgml source, and I think it's probably worthwhile.

With 1+2 I think there's an argument in favour of removing the bottom
navigation - it's only useful if you can't see the top links.

3. Javascript popup menu.
This uses jquery, but that's just for convenience during discussion. You
could rework this without it.
Copy STYLING/*.js and STYLING/menu.inc to the docs dir and then run
./STYLING/include_javascript.pl to include the popup script.
The central "chapter heading" section of the top navigation area should
now be a link that toggles the menu on/off.
The menu could be as simple/complex as you like - this is just what I
hacked together by parsing the TOC on index.html

I've tested it on Firefox, Opera, IE7 and Safari. Realistically, the
only real problem platforms will be IE6 and perhaps iphones.

--
Richard Huxton
Archonet Ltd

On Friday 17 July 2009 15:58:27 Richard Huxton wrote:

1. Fixed navigation
Copy STYLING/stylesheet.css over the existing one and you will have
static navigation links top and bottom of the page.

Looks good.

2. Titles on navigation links.
Run ./STYLING/title_links.pl and it should add title attributes to the
navigation links. This means hovering over the top links gives the title
of the page they will go to. Presumably we could do this directly from
the sgml source, and I think it's probably worthwhile.

Yes, the DSSSL stylesheet could do that.

3. Javascript popup menu.
This uses jquery, but that's just for convenience during discussion. You
could rework this without it.
Copy STYLING/*.js and STYLING/menu.inc to the docs dir and then run
./STYLING/include_javascript.pl to include the popup script.
The central "chapter heading" section of the top navigation area should
now be a link that toggles the menu on/off.
The menu could be as simple/complex as you like - this is just what I
hacked together by parsing the TOC on index.html

This looks very cool, but should probably be implemented via a stylesheet
change instead of some Perl parsing some HTML. :-) I'm not sure if this
actually addresses Andrew's original concern, though.

Peter Eisentraut wrote:

This looks very cool, but should probably be implemented via a stylesheet
change instead of some Perl parsing some HTML. :-) I'm not sure if this
actually addresses Andrew's original concern, though.

No, it doesn't. David Wheeler's navigation (see upthread) that he uses
for the Bricolage docs does, however.

cheers

andrew

Andrew Dunstan wrote:

Peter Eisentraut wrote:

This looks very cool, but should probably be implemented via a
stylesheet change instead of some Perl parsing some HTML. :-) I'm not
sure if this actually addresses Andrew's original concern, though.

No, it doesn't. David Wheeler's navigation (see upthread) that he uses
for the Bricolage docs does, however.

Ah, if you can change the overall layout then the world is your
shellfish of choice. Would it be possible to include jquery? It's
GPL/MIT dual-licence.

--
Richard Huxton
Archonet Ltd

On Jul 18, 2009, at 9:54 AM, Richard Huxton wrote:

No, it doesn't. David Wheeler's navigation (see upthread) that he
uses for the Bricolage docs does, however.

Ah, if you can change the overall layout then the world is your
shellfish of choice. Would it be possible to include jquery? It's
GPL/MIT dual-licence.

That's what I used for the Bricolage stuff. I still need to fix the
encoding issues on Windows, though…

Best,

David

Peter Eisentraut wrote:

On Friday 17 July 2009 15:58:27 Richard Huxton wrote:

1. Fixed navigation

2. Titles on navigation links.

Yes, the DSSSL stylesheet could do that.

Since it seems we can get both of these without interfering with
anything else I vote +1 on getting them it.

3. Javascript popup menu.
This uses jquery, but that's just for convenience during discussion. You
could rework this without it.

This one looks very good to me too -- I like it better than David
Wheeler's, because you just wave it away when you don't need it, saving
screen estate. The only change I'd make it is that the righthand menu
should have only the entries for the current chapter, not all chapters.
But maybe that's just me.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support