Re: Splitting the guide
On Thu, Mar 06, 2008 at 02:04:48PM +0100, Rainer Müller wrote: [EMAIL PROTECTED] wrote: I just tried this using DocBook but it didn't work for me. So I used a simple sed replacement to get this working. I created two examples: http://ruderich.com/macports/guide-link.html I like this one with the links. It makes it easy to get the URL which links exactly to this section. Good work! [snip] Rainer Hi Rainer, sorry for the late reply. I'm glad you like it. I just [1] committed the change and now the guide makes it easy to link to subsections. Thanks for the suggestion. Simon [1]: http://trac.macports.org/projects/macports/changeset/35199 -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 pgpUYffe3zxDu.pgp Description: PGP signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
Done. -Bill On Mar 8, 2008, at 1:59 PM, Simon Ruderich wrote: 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 William Siegrist Software Support Engineer Mac OS Forge http://macosforge.org/ [EMAIL PROTECTED] 408 862 7337 smime.p7s Description: S/MIME cryptographic signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
[EMAIL PROTECTED] wrote: I just tried this using DocBook but it didn't work for me. So I used a simple sed replacement to get this working. I created two examples: http://ruderich.com/macports/guide-link.html I like this one with the links. It makes it easy to get the URL which links exactly to this section. Good work! http://ruderich.com/macports/guide-title.html The first one wraps the sections (h1-h9) in links so you can click on them to see the anchor. The second one adds a title attribute which should display the anchor when you mouse over it for some time. Please tell me which you like more and I will add it to the documentation Makefile to add it to the guide. Thanks a lot, I think this is a real good improvement for the guide. [EMAIL PROTECTED] wrote: I don't understand. The TOC entries are all linkable, and the TOC entries correspond to the titles. What is it that is missing? If I want to link to a specific section, it is not easy to find out which anchor it has. By making the headlines links, you can just click on them and copy the URL from the browser. Rainer ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
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 ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
Thomas Reifferscheid wrote: 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? I think finally this should go on guide.macports.org, there the guide is already built automatically. We would need to decide if we want to keep both versions with some intro page to choose or if we want to eliminate the all-on-one-page guide. Rainer ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
On Wed, Mar 05, 2008 at 08:15:52AM +0100, Thomas Reifferscheid wrote: Hi, great work Simon! Hi, I'm glad you like it. 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? 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. 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? Kind regards Thomas Thanks, Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 pgpJruTejuFFo.pgp Description: PGP signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
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 ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
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. I didn't really have any special ideas at the time. But I do think the TOC should be easily accessible from any section as already mentioned. Would it be possible to have the TOC float at the side within the chapters? Actually, I'm not sure that is desirable and I've have to see it, but it does seem like switching from the main page to a chapter you get an entirely different look and feel and I think that distracts. Mark ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
On Sun, Feb 17, 2008 at 01:32:09AM +0100, Rainer Müller wrote: 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 Rainer, I just tried this using DocBook but it didn't work for me. So I used a simple sed replacement to get this working. I created two examples: http://ruderich.com/macports/guide-link.html http://ruderich.com/macports/guide-title.html The first one wraps the sections (h1-h9) in links so you can click on them to see the anchor. The second one adds a title attribute which should display the anchor when you mouse over it for some time. Please tell me which you like more and I will add it to the documentation Makefile to add it to the guide. Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 pgpPuCFL52umq.pgp Description: PGP signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
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 pgpC8C3x642Y5.pgp Description: PGP signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
On Wed, Mar 05, 2008 at 09:49:37AM +0100, Lutz Horn wrote: Hi Simon, Nice! Could you add Up links at the top and the bottom of the page? This would allow the user not only to navigate to the next and previous page but also back to the TOC. Lutz There is a Home link at the bottom of the page. I'm not sure how to add an Home/Up link with DocBook (if somebody does, please tell me), but if we succeed adding the sidebar (table of contents) to every page/chunk this shouldn't be a problem. Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 pgplGypqUKKQR.pgp Description: PGP signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
Re: Splitting the guide
On Sat, Feb 16, 2008 at 02:46:33PM -0800, [EMAIL PROTECTED] wrote: Hey guys! The guide is advancing so nicely that I'm afraid we've hit the point when it's maybe becoming a tad too large for a single page, wouldn't y'all think? Every time I have to load a section of the guide a have a moment of hesitation in fear of loading such a large document! At this point in time, wouldn't it be better to have a single html page per chapter? Just my thoughts,... -jmpp Juan, 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. Mark 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. Thanks, Simon -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 pgpCmXJp35YNK.pgp Description: PGP signature ___ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
