That said, the new style could use some major improvements. For example the menu texts, white or light gray on dark gray isn't very easy to read, and I find the red box informing me that I need javascript rather annoying.

It informs me that "many features" require javascript, but when I turned it on I only got the floating title bar - did I miss something?

I know that it's not your fault, but I find it quite ironic that the one major perl site that had a rather good design got a major style change, while many other sites would have needed it much more.

With JavaScript disabled you won't be able to use the search box (it's client-side, not server-side so that if you've downloaded a local copy of the docs then search will still work), the floating page index, the recently viewed pages list, the static title bar, and the drop-down to select Perl version.

If you're using NoScript you should be able to set an exception to allow scripts from perldoc.perl.org but still block them from other sites.

One major feature I can't get working without JS is the search form.

I'm still debating whether I'll send any emails or not. I'm just so happy that I can finally access the menus that I almost don't care about anything else.

I hovered over moritz's three links and was a bit surprised to not see "ours truly" included. moritz is so polite. ;)

And, before I go any further, I would like to extend my sincere thanks to jj808 for the hard work (on an important site) and for announcing the changes here. I hope he won't mind the ensuing discussion. I'm unlikely to privately communicate critiques of his work since I have the opportunity to do so with much less effort as part of this discussion.

I don't want to discount the visual changes that I'm sure jj808 worked hard on. As you may have suspected from visiting this clunky-looking site that I hack upon, I don't really notice fonts or colors much (except when they make things hard to read). So I'm genuinely sorry that I don't have much praise to offer about "the look". I go to perldoc because I want to read some text and it is often the most convenient way to get to that text in a format that is easy to read. I am truly thankful that jj808 worked hard on the new look and I hope that it is well appreciated by normal people who notice that stuff. :)

I also would like to offer great praise to jj808 for choosing to leave links underlined so that I can find them (and without learning some alternate visual cue).

The Perl documentation (in the new layout) is quite easy to read. The "syntax coloring" on the code snippets is done subtly enough that it is only slightly distracting (the bright red for sub names is an exception in both that it isn't subtle and actually makes the names hard to read).

The highlighted boxes around in-line code snippets make it easy to scan for keywords and bits of syntax while they also don't seem to disrupt my reading nor make the code hard to read. Good job!

But having such an important feature (search) not work w/o javascript is something I would consider unacceptable. I find it even more galling for a Perl site (but we can to be self-righteous, can't we). I know that many people appreciate many of the interface options that become possible with javascript (I do sometimes but I even more often find that I prefer the consistency of an HTML-only interface) but providing a fall-back is just polite.

In this particular case, I'm not upset except in abstract at this point because I don't use perldoc's search feature anyway. I use PerlMonks' to 'search' perldoc, typing (for example) doc://$; into the PerlMonks 'search' box to jump right to the desired documentation (and this still works w/o need of javascript, thankfully). When doing full-text searching of Perl documentation, I tend to use 'grep' against my local perl/pod/*.pod (or equivalents, usually using vi as my doc reader). And now I know to not try the search box so I'll just use google w/ site:perldoc.perl.org when I want to find documents that mention "all of the following words".

So those who miss a useful search due to lack of javascript (perhaps just by choice) have at least two alternatives for searching perldoc.perl.org (use PerlMonks or use google).

So I would like to gently encourage jj808 to allow non-javascript environments to work more smoothly at such an important site (certainly javascript isn't intrinsically required for any previously-available functionality there, such as searching, since it worked w/o javascript before).

I realize that the new search functionality is more than just interface tweaking. And I noticed and appreciate the "this is the best match but you can look at the list of other matches if you want to" feature (a feature I've long wanted to add to PerlMonks). But the site should at least offer a less-smooth search feature in the absense of javascript (IMO, obviously).

I'm sure some will ask "why would you ever not have javascript enabled"? In this particular case, I would go out of my way to disable javascript just to get rid of the "floating" heading bar. There are lots of annoyances inflicted by javascript so I prefer to opt-in to javascript only for sites where they offer features that really require such functionality and where the site does an excellent job of not annoying me (javascript is often used to make particularly annoying advertisements, for example; but I often find javascripters' interface choices annoying enough as well). I'm sure others have other reasons to browse w/o javascript (corporate security policy, their own security choices, their particular environment, etc.).

I also encourage providing a link to set a cookie that turns off the "you don't have javascript" notice (or at least replace it with something much less conspicuous). I understand the desire (and wisdom) of making it very obvious to new visitors the likely reason why the site is behaving "a bit odd". But I also understand visitors refusing or being unable to enable javascript and getting quite annoyed at the visual noise on every screen.

I also encourage providing a way to set a cookie saying that one doesn't want the floating header so those with javascript enabled can get rid of it (some will surely find it useful but it is unusual enough that I'm sure some will just find it an annoyance), perhaps triggered from an 'x' element on the bar.

Finally, I will once again tilt against the windmill of webpages that don't know how to resize. I'm certain that your new design would be nearly unusable if I visited from my zaurus (or other small-format browsers I've been known to use). I can adjust the width of my browser window as much as I want to and your new layout resolutely refuses to acknowledge my choice (or limitations). If I want to get a larger section of documentation showing on one part of my screen as a reference while I'm doing work based on it in another window, you have greatly limited my choices.

I realize that there is a resolute meme that CSS is king and tables (for layout) are evil and even bow to the strong motivation for "pixel-perfect" web layout in the face of many web advertisement schemes. And I love CSS for much styling. But CSS is fundamentally broken when it comes to doing layout (as can be seen by people spending days trying to do simple things with it and the fact that almost nobody is cabaple of producing a layout with CSS that is capable of resizing well). So I'll just challenge you to prove me wrong (as I always do) and get your CSS-based layout to resize to still be readable when given a quite narrow window and to use more horizontal space when it is offered to it.

Thanks again for your hard work, jj808! I hope you find my critique and criticism useful.

- tye        

I find it quite ironic that the one major perl site that had a rather good design got a major style change, while many other sites would have needed it much more.

I despise with much passion the fascist and ultra-moron practice of fixed width, so of the first one I just think, "Phew, still not a zombie!" and of the last two, yeah, someone should contribute a brain.

I do wish there was a way to turn off the 'floating' top bar: I'm sure it's nice for most, but it completely kills my work desktop. (Ok, so a lot of things kill this desktop, but not being able to scroll through documentation is going to annoy me.)

It's also slowing down scrolling ("unsmoothing", kind of stumbling) ... I'd really love to have a setting stored in the cookie to disable/manipulate the floating bar.

Another (private) approach would be using GreaseMonkey (or the equivalent of other Browsers) to manipulate the CSS...

Beside of this it's really nice to navigate through the new site! 8-)

Cheers Rolf

I want to echo the concern about the 'floating' top bar, but from a slightly different angle. I am slightly dyslexic and the floating toolbar aggrevates a problem I already have following the flow of text lines.

To avoid losing my place in the text, I am in the habit of focusing on a particular position within the page and then scrolling to page to see additional lines (rather than reading down the page and then scrolling a whole pageful at a time when I hit the bottom). On the old perldoc site, I was in full control over how much text scrolled into view. This is not so for the new perldoc site layout.

Whether I focus on the top or middle of the page I seem to run into problems. If I focus on the top, the floating top bar has a habit of cutting lines of text in half (rather than moving line by line). If I focus on the middle, I sometimes notice that, from time to time, there is a rectangular region of text on the right (about 10 lines long and half a line wide) that seems to lag behind and momentarily refuse to scroll at that same time as the text to the left. There is little I can do to control this so my eyes have to jump back and forth sometimes skipping forward half a line and sometimes not. (In case this is a browser-specific issue, browser is Firefox: 3.0.11, Javascript enabled)

If there is a way to insure that the floating bar does not cut lines of text in half that might go a long way to making it more comfortable for certain readers. Otherwise, I think one should look at other ways to make "tools" accessible. Floating sidebars, perhaps?

Best, beth

Update:It appears the flicker in the middle is unrelated to the floating header. It also is only visible for certain usages of scrolling. To see it: keep your eye focused on the middle of the page and scroll using slide rather than page down, space or click - there is a box on the right that "wobbles", "flickers" as you scroll.

As for the floating header, if you are using firefox, you can remove it by installing the firefox extension Stylish and the style Pin the Perldoc Header down. Many, many thanks to the monks in the CB and especially hobbs who wrote the style. See perldoc.perl.org -- keep the navigation header out of your way for more information.

I've posted a user CSS snippet to disable the "floaty bar" at userstyles.org; it can be found here.

Hi, I've made some updates and the position of the top bar can now be changed - see http://use.perl.org/~jj/journal/39365 - this should resolve your issue with CPU usage.

Much better: The site is usable again now.

Do count me as one that liked the old design better though: while I appreciate some of the new navigation options (direct links to Perl version docs and module docs are nice), the overall color scheme, and the fixed width, are steps far backward in my opinion. You've gone from a welcoming and cheery site, to an forbidding institutional one.

Another slightly distracting aspect of the fixed floating bar is that it's hindering text searches. The result of a backward search is normally scrolled to the top window border. It's really confusing to know there are hits but not to find them, because they are covered by the bar...

UPDATE: Just set the position to "Standard" in http://perldoc.perl.org/preferences.html, which really works fine! 8)

But testing reveals a strange phenomenon in FF3: While backward searching for "Comma" in perlop the second hit is not visible, because 2 lines at the top are not shown...

I'm completely clueless how to produce this effect. Does anyone else observe it?

Cheers Rolf

Can you please alphabetize the doc lists, like the language reference?

Good idea, thanks!

OK, maybe some will agree, maybe I'll just be shunned for saying it but I think the new look is a horrible step backwards for perldoc.

There seems to be and ugly trend in web design these days where everyone has to use highest contrast settings they can find to make a point. It's like going back to the early days of the web when everyone thought neon colour choices were cool. Granted the new look is not so bad as that, but where as I found the old layout very easy on the eyes and harmonious, I find the new layout harsh and just plain hard to read. It's a disappointing change in my eyes. Grey text in a Dark grey box sitting in a Light grey background? That might look OK... if I tweak the heck out of my monitor contrast/brightness settings first!

I can't recall if the previous layout was fixed width, but that's painfully obvious now (maybe due to the new choice of background colours?). In my browser the 'Perl Version' select box sticks out the side in way that suggests cross-browser compatibility was second (and forgotten) thought. I should be able to expand my browser window to read more of the content that I'm after. Instead all I get is more empty background. The brutal days of fixed format layout are so 2000 and late. If that's how it looked before the layout change, then I guess it just proves how badly the new colour scheme emphasizes this now.

When I have to code PHP I usually have www.php.net/docs.php open in a tab. I don't spend enough time with PHP to make it worth my while to stock the book shelf and keep a reference handy. But I don't have to. The PHP doc site is easy on the eyes, it flows to what ever size I make the browser window, and the search WORKS for Pete's sake. In short it's an invaluable coding resource and the user contributed comments are pure gold.

I've tried to use perldoc.perl.org for my equivalent online Perl reference. It 'used' to be as easy on the eyes as the PHP site. In fact I'd say it even looked better. But I've been burned so many times now trying do a quick look up that I've stopped wasting my time there. Try searching for 'while' or 'foreach' and don't even get me going on what you get for 'if'. What does that say about our Perl language when the official documentation site can't even find the most language statements? Honestly, if I have to jump out to Google to search for Perl documentation, then I'm going to start there in the first place and skip the perldoc middle man. It's so painful to use that I've stopped trying to use it, and instead I keep the camel book next to the mouse. I could never recommend perldoc to anyone learning Perl.

The PHP documentation site is useful because (a) is uses a sane web page layout, (b) it actually has a working and complete search tool, and (c) it contains valuable user contributed comments for every function with practical examples and pitfalls. The Perldoc site has none of these (especially now).

Instead of wasting time 're-skinning' perldoc we should have spent the time making it a better perl resource. The old layout was already timeless and professional. It's the functionality that's sorely lacking.

In my browser the 'Perl Version' select box sticks out the side in way that suggests cross-browser compatibility was second (and forgotten) thought.

Can you let me know what browser (and version) you're using and I'll check that out. Thank you for letting me know - I test the site on quite a few different platforms and browsers, but obviously cannot replicate every combination.

Instead of wasting time 're-skinning' perldoc we should have spent the time making it a better perl resource.

When you say "we", what did you contribute exactly? If you had issues with the search functionality I would have been very grateful to receive suggestions and bug reports from you, or even (dare I say it) a patch.

I'm aware that the search tool does have some limitations, and of course would be very appreciative of any help to make it better. Part of the problem you describe is because perlfunc is separated into sections, making it easy to split up into separate pages for each function name, whereas perlsyn (containing while, foreach, etc) is not, so it is more difficult to reference a specific point to document the 'while' keyword. Maybe you could contribute a page similar to perlfunc but documenting all the loop control keywords, then I could build it into the search engine?

Firefox 2.0. Admittedly this is an older version and I don't expect full (any for that matter) support for it. Then again this is the FIRST website I've come across where the Firefox version has been an issue. But as I look at the page now, I see that you (or your predecessor) included javascript to (choke) 'document.write' the html for the perl version selector? Since when did it become cool to replace plain old html with a javascript include to write plain old html? It doesn't add a single scrap of add functionality that wasn't already available with standard html. No wonder my older browser chokes on it. Good luck when the next browser release optimization takes a different approach to what order it renders page parts/javascript and you find your select box hanging out the end again.

Sorry if I sound harsh (and I know I do), but it's not my lot in life to fix, or assist in fixing, perldoc (my time is already filled contributing to other projects no less important than perldoc). Since you've taken on the task of spicing up the layout, it's now your lot in life to fix it. As a perldoc user, I'm telling you there are usability issues with perldoc, none of which were addressed by your update. If anything your update put new usability issues onto the site and made existing issues more obvious.

OK, maybe some will agree, maybe I'll just be shunned for saying it but I think the new look is a horrible step backwards for perldoc.

I wouldn't be that harsh, but I definitely preferred the previous version. It was uncluttered, it was resizeable, readability was better. The top bar is quite annoying to me (if I want to go back to top I have a "Home" key) because it makes scrolling stutter. It sure looks better in a way, like Eclipse looks better than Emacs, or Microsoft Word looks better than Vi :)

My suggestions :

• instead of a large top bar, a floating toolbar on the right side would be better, as it wouldn't overlay text but the useless light grey side, it wouldn't obstruct reading and probably cause less stuttering. And as we're at it, put the search box in it so it can be more useful.
• Really, fixed central column width? It's a step backward! Just when almost all corporate websites finally got rid of it...
• I'd prefer a lighter and less colourful theme overall, but that's just me.
• The perl version select box protrudes out of its box for me too : Linux, Firefox 3.5.1 as well as Konqueror 3.5.10
• By the way, the top bar doesn't float at all in Konqueror. That only confirms that I like it better when it keeps at rest :)

Anyway, I want to thank you very much for the hard work and the nice website. As the say goes, quid bene amat bene castigat.

This

        
              <script language="JavaScript">
function selectPerlVersion(element) {
  if (element.value.substring(0,1) == '/') {
    location.href = element.value;
  }
}
</script>
            <div class="side_panel tools_panel">
              <p>Perl version</p>
              <form id="perl_version" name="perl_version">
<select name="version-chooser" onChange="selectPerlVersion(this)">
  <option selected>Select...
  <option>Perl 5 version 10
    <option value="/index.html">&nbsp;&nbsp;&bull;&nbsp;Perl 5.10.0
  <option>

  <option>Perl 5 version 8
    <option value="/5.8.9/index.html">&nbsp;&nbsp;&bull;&nbsp;Perl 5.8
+.9
    <option value="/5.8.8/index.html">&nbsp;&nbsp;&bull;&nbsp;Perl 5.8
+.8
    <option value="/5.8.7/index.html">&nbsp;&nbsp;&bull;&nbsp;Perl 5.8
+.7
</select>
</form>
            </div>
[download]

<div class="side_panel tools_panel">
<p>Perl version</p>.
  Perl 5 version 10<p>
    <a href="/index.html"> Perl 5.10.0
  
</p><p>
  
    <a href="/5.8.9/index.html"> Perl 5.8.9 </a><br />
    <a href="/5.8.8/index.html"> Perl 5.8.8 </a><br />
    <a href="/5.8.7/index.html"> Perl 5.8.7 </a></p>
</div>
[download]

I want to say that I already mailed JJ a while back for the use of CSS and JS to hide the sidebars on the old version of perldoc (which, design-wise, I also thought looked nice, or at least, was not a bad visual design). So I think all that's needed is, anyone with better ideas can send them to him. He is the one doing the hard work of maintaining this site after all (and I am very happy that there IS a site). Since Perldoc is pretty much nothing more than a collection of text documents, one should be able to have any combination of "extras" (JS, CSS, colour, certain screen sizes, being a sighted person!, anything) and have access to everything (I understand now about the search, though there's also an error there).

The only thing one can guarantee ANY user agent supports is HTML. With the proliferation of mobile devices this is even moreso, and even though battery technology is always improving, scripts still shorten the lives of mobile devices. This can make internet surfing last a few minutes! Yes, it's that bad. There are also still plenty of mobiles who don't support scripts at all, as well as other things like zooming or Flash.

I've run into the selects/inputs being too long problem (though I actually don't see it currently on the perldoc site) and it turned out that if you didn't actually specify a width on those, the Windowing system (not the browser so much, though I always saw this problem with FF specifically) would change the widths of those. For instance, a form without set widths on inputs would never fit right on my FF on Ubuntu (the problem was Gnome, not FF, though Opera was ok cross-OS). So setting a width for dropdown selects and inputs in the CSS in em's or some flexible unit would help cross-OS and cross-browser with these sorts of things. I have found Epiphany (with the Gecko engine, not the webkit version) can't seem to get the sizes of anything correct, at least not any site using em's as a sizing unit.

The problem of the site not being a flex-width could be solved a few ways: so long as the source was content-first (which can be nicely done Layout-Gala style for post-content sidebars), one could have the layout have a max-width and no min-width and so could shrink as needed for smaller windows (a mobile-specific css sheet might be better though than just letting the screen shrink indefinitely), letting the sidebars drop down underneath the content.

Another solution is to write an alternate CSS sheet and let those who want, say, the old design back or something else, choose that. However whether this is done via JS or the server, some sort of session would be needed to keep the chosen stylesheet consistent as the user goes from page to page. I mean, you can select your desired stylesheet without JS or a cookie (except in IE6 blah blah) but you'd have to select it for every page you go to without a session.

A final solution could be, someone makes a stylesheet that mimics the old style (or something else that's pretty basic), and let anyone download and use it as a "User Style Sheet" which should always be able to override the author's styles (unless the author unwisely used !important). People can make their personal stylsheets however they want, whatever fonts and colours and contrast etc, and it's selectable via the browser, no Greasemonkey necessary if one doesn't want to have to spend time scripting against a site.

Edit: btw Opera can be added the the list as a "modern browser" : ) Poor thing, everyone forgets it! Pretty popular on mobiles though (OperaMini).