markd@macports.org wrote:

Well I agree it is really too big, but on the other hand we hated to split it and have cumbersome "forward" and "back" buttons. Also it makes searching easier in one page, but then I suppose indexing might solve that. But then maybe a page for each chapter wouldn't be too bad. I guess we should experiment and see how it looks and drives.

It would be nice to have at least the chapters on seperate pages. Also, many other projects offer both versions. A single page HTML version and multiple pages HTML version. Wouldn't be much work, just generating them both with different stylesheets would take longer... But as we are talking about the guide, I might also bring up another issue with the current presentation. I find it difficult to link to specific headlines. Could the headlines made clickable with a link target on themself? Or maybe some marker item on mouse-move like trac does? At the moment I always look into the source to find out how the anchor was named which is a little bit annoying. Consider this as a nice-to-have issue ;-) I already looked into the generation scripts for this, but it seems to use a xslt stylesheet provided completely by docbook, so I don't know if I would have to file my request there... Rainer

Hi, great work Simon! For doing this automatically (e.g. every night), we could need some kind of shell (bash) script doing this. Do you think thats possible for fully automation? Kind regards Thomas Simon Ruderich wrote: [...]

Hi all, sorry for the late reply.

I just created a chunked version of the guide and uploaded it on my homepage: http://ruderich.com/macports/chunked/

Please tell me what you think and if I should change anything.

Hi Simon, Simon Ruderich wrote:

I just created a chunked version of the guide and uploaded it on my homepage: http://ruderich.com/macports/chunked/

Looks good so far. But I would like the TOC to be on each page for easier switching of chapters. Could the current chapter be marked inside the list then? Also, as said before, Back/Next/Up links would be nice-to-have. I think you just used the chunked docbook XSL? Do you have any experience with XSL and are you able to improve that? :-) Rainer

On Mar 5, 2008, at 2:45 AM, Thomas Reifferscheid wrote:

Hi, great work Simon!

For doing this automatically (e.g. every night), we could need some kind of shell (bash) script doing this. Do you think thats possible for fully automation?

Kind regards Thomas

Guide regen is already automated in the base/portmgr/jobs/ GuideRegen.sh script, which runs as an svn post-commit hook on our subversion repo to keep guide.macports.org always up-to-date. What Simon is providing us here with is a view of the guide as a chapter per page alternative, per a request of mine. Simon, I like it and I still think the entire thing in a single page is a bit too much, but I would like to go over what Mark originally replied 'cause he did raise some valid points there (and it's been a while and I don't remember them at the moment ;-). One thing I would comment about your alternative, however, is with respect to the sidebar. Is is possible to keep it with us in every single chapter- page? At the moment we see it if we're on the front page, but as soon as we move to any chapter it disappears, and that's not incredibly friendly. Thanks for the initiative! Regards,... -jmpp

Simon Ruderich wrote:

[...]

...

Hi all, sorry for the late reply.

I just created a chunked version of the guide and uploaded it on my homepage: http://ruderich.com/macports/chunked/

Please tell me what you think and if I should change anything.

_______________________________________________ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev

Simon Ruderich wrote:

This shouldn't be a problem. I already modified my local Makefile for the documentation generation. The question is how we should provide these two versions (maybe also a third: a downloadable version of the guide). Maybe http://guide.macports.org/ should display a selection so the user can choose a version.

A selection page would be good, yes.

I don't know enough about the server structure. Juan, or anybody who knows this. What's the best way to add this selection (or something similar) and what changes needs the Makefile?

I think currently the guide/html/ directory is made available on http://guide.macports.org. I am CC'ing Bill to confirm that :-) So we could add like * guide/html/one-page/ * guide/html/multipage/ With guide/html/index.html being some static selection page. Rainer

On Wed, Mar 05, 2008 at 06:14:46PM +0100, Rainer Müller wrote:

Hi Simon,

Simon Ruderich wrote:

...

I just created a chunked version of the guide and uploaded it on my homepage: http://ruderich.com/macports/chunked/

Looks good so far. But I would like the TOC to be on each page for easier switching of chapters. Could the current chapter be marked inside the list then? Also, as said before, Back/Next/Up links would be nice-to-have.

See my mail to Juan about the table of contents.

I think you just used the chunked docbook XSL? Do you have any experience with XSL and are you able to improve that? :-)

Rainer

Yes, I used the chunked version. But my experience with XSL is basic at best. I did some minor changes for the man pages but that is all. If someone can help me with the XSL for the guide I would be very happy. Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229

On Wed, Mar 05, 2008 at 12:52:46PM -0430, Juan Manuel Palacios wrote:

[snip]

Simon, I like it and I still think the entire thing in a single page is a bit too much, but I would like to go over what Mark originally replied 'cause he did raise some valid points there (and it's been a while and I don't remember them at the moment ;-). One thing I would comment about your alternative, however, is with respect to the sidebar. Is is possible to keep it with us in every single chapter-page? At the moment we see it if we're on the front page, but as soon as we move to any chapter it disappears, and that's not incredibly friendly.

Thanks for the initiative! Regards,...

-jmpp

Hi Juan, I tried to add the sidebar on every page but it didn't work. If anybody knows how this is done with DocBook please tell me. Thanks. What I could do is to modify the html with a simple script (sed or tcl) to add the sidebar on every chunk. What do you think? My main concern with an only chunked version is that searching doesn't work. So I think we should keep a big version and add a chunked version if someone just wants to read some sections. Thanks, Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229

On Wed, Mar 05, 2008 at 12:53:40PM -0800, William Siegrist wrote:

Its handled via the Makefile. The post-commit job performs 1 copy when make is done:

cp doc-new/guide/html/* <docroot of guide.macports.org>

So if you make subdirectories, I'll add a -R, otherwise it should work.

-Bill

Hi Bill, thanks for your quick response. It would be perfect if you could make this change (-R) so we can decide which method we use and then just modify the html directory in the guide. Thanks for your help, Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229