Redesigned GNU C Library manual | Hacker News Reader

Redesigned GNU C Library manual

elmerland.com

104 pointselmerland61 comments

It really doesn't work for me. Here is why:

A big part of manuals is being able to read or scroll fluidly into the next or previous section - very often one doesn't know whether what they are looking for is mentioned in 1.3.1 or 1.3.2 - having to manually click each section is completely atrocious for usability. Not to mention you just broke search.

If you want a responsive design that's actually useful as opposed to counterproductive, leave the sidebar for navigation (down-scale it to 50% it's huge and distracting) and restore the document to a contiguous form. There is a reason manuals have been written the way they are for dozens of years, hip and flashy design elements might sell products - but they do not help with productivity.

This, it is often split in sections smaller than the screen so you have to uncollapse way to many items. Make the navigation jump to the right section in the document, maybe allow to collapse sections, but have it all visible by default.

    $ links https://www.gnu.org/software/libc/manual/html_mono/libc.html
       Link: [start: Top]
       Link: [index: Concept Index]
       Link: [contents: Table of Contents]
       Link: [up: (dir)]
    
                                   The GNU C Library
    
    Short Table of Contents
    
         * [1 Introduction]
         * [2 Error Reporting]
         * [3 Virtual Memory Allocation And Paging]
         * [4 Character Handling]
         * [5 String and Array Utilities]
         * [6 Character Set Handling]
         * [7 Locales and Internationalization]
         * [8 Message Translation]
         * [9 Searching and Sorting]
         * [10 Pattern Matching]
    ^C
    $ links http://elmerland.com/gnu_manual.html
                                   The GNU C Library
    
       [About] [By: Elmer Landaverde]

Edit: Added [] to show selectable links (note that [] are not actually displayed in links' output)

This is the most graceful CSS-degradation I've ever seen. The world needs to learn from this manual in how to do HTML right.

If you haven't tried it yourself you're missing out. It's truly art.

And yet the whole thing doesn't load if you block javascript. No content at all.

That's right, this was intentional. The content is loaded dynamically. I thought this would help with mobile users, to reduce the amount of data used.

But you broke the back button. Perhaps using frames might be better?

Ahhh, thats a good point. I will fix that! I tried using iframes at first. But they are a pain to deal with. I think I can solve the back button problem without them though. Thanks for pointing that out!

People who rely on screen readers probably don't like this.

I applaud your effort to apply some styling to the manual, but this is, frankly, ridiculous.

To whit:

    # Debian Jessie
    $ du -hs /usr/share/doc/glibc-doc-reference/html/
    9.0M    /usr/share/doc/glibc-doc-reference/html/
    $ cat /usr/share/doc/glibc-doc-reference/html/* > all.html
    $ wget https://www.gnu.org/software/libc/manual/html_mono/libc.html
    $ gzip -9 -k *.html
    $ du -hs *
    7.5M    all.html     # Local html
    1.1M    all.html.gz  # -"- gzip'ed
    4.9M    libc.html    # single-file version, from wget above
    900K    libc.html.gz # -"- gzip'ed

So, under a mb of data, for the whole thing -- and that's not even working with the various sections. It might have made sense on dial-up, but not really for mobile clients. The fact that you've completely broken the whole thing (eg: no mirroring with wget) doesn't make up for the savings. Also, if you'd kept the/a single html-file -- that file would've been cached, so doing some js-magic with hide/show should be instant, after the thing is downloaded. That's the old Dreamweaver way of pre-loading content (set sections/div/whatever as display:none, and toggle on mouseover link/clicks etc).

So this is not degrading css, this is just broken html for no good reason. If you want to load "partials", keep the traditional structure, and do your magic "upgrading" in js -- load the content asynchronously into a div or what-not -- and leave the links working for browsers without javascript/wget/etc.

All that said, the work you've done with the CSS is very nice. I'd probably add a media-query to collapse the sidebar -- it takes up quite a lot of space on mobile (especially in portrait mode). I'm also no fan of typekit -- if possible I'd prefer to use locally hosted (freely licensed, of course!) fonts.

As for search, maybe have a look at http://lunrjs.com/ .

And just as a reminder, on the off-chance that there might be some readers that are unaware: CSS Zen garden is still a good example of how html and css can go together in creative and gracefully degrading manner: http://www.mezzoblue.com/zengarden/

A final note on links/urls. With eg. vimperator, "gu" (go up) works for going from example.com/some/where to example.com/some/ -- so while most browsers have gotten rid of "forward" and "up" navigation arrows, they still do work.

I am actually on mobile, and the biggest problem on mobile is spotty coverage. I click stuff and there is a slight animation but no more data shows.

I have no idea if that was because a TCP connection broke, or if this is just a design concept and the actual data is missing. I have to reload the whole page, then click down to the sub-heading I just opened and try again to know.

I haven't looked, but I get the impression you don't have any error handlers (or maybe there are crazy high timeouts?). You should always, especially if your users are on mobile networks, to put up some sort of spinner when loading data and make a serious effort of handling the errors that inevitably happens.

So goodbye to accessibility.

how does this reduce accessibility? javascript interpreters are not hard to find nowadays.

There are in fact a huge number of both usability and accesability issues with this that do not exist with the original:

http://www.gnu.org/software/gnu-c-manual/gnu-c-manual.html

does javascript reduce "accessibility" as in: does it keep average users and handicapped users from accessing the pages?

The usual texinfo output is probably more accessible from a technical standpoint, but from a usage perspective it is not.

Markup formats like ReST/Sphinx are much more semantic and improve accessibility for the impaired as well. Simple JS is not the problem here.

> The usual texinfo output is probably more accessible from a technical standpoint, but from a usage perspective it is not.

Can't possibly agree with that. Slap a fancy clean font on it and it prob solves half the issues people have with it.

From a usage perspective this page is crippled compared with the original.

> does it keep average users and handicapped users from accessing the pages?

If the third part tools they need to navigate and consume the content stop working, then yes, yes it does.

Bullshit. Modern screenreaders in browsers directly look at the visible parts of the DOM.

Wilfully turning off Javascript in the browser is not an accessibility issue.

Well the content is loaded dynamically so that is going to screw a lot of utilities up.

Thanks! I honestly hadn't even tried it. Just following best practices and doing the least amount of styling to achieve the desired look.

I didn't know about this tool. Thanks for pointing that out, I will improve the link layout.

In case the name is not clear: It's not a link-finding tool, it's a text-mode web browser, a cousin of lynx.

See also: w3m.

Links is certainly an interesting tool, but you certainly shouldn't look at it as the only "niche" way in which people might read your website.

This is Windows 7, with the latest version of Chrome - the only difference from "normal" being the installation of ScriptSafe blocking JavaScript:

http://i.imgur.com/vH4MTdV.png

I use w3m every day for a couple of reasons. May be the minority but the only reason w3m would stop working well with most sites is that we have forsaken our semantic heritage that the web was built on.

In lynx, the table of contents appears but the links are all 404s. Similar behavior occurs when disabling CSS in Firefox...

Though I suppose I should ask why a command line user would not just use GNU info or another program to access the info files.

I just checked disabling CSS with firefox. I can still see and interact with all of the content. What type of errors are you referring to?

Ohh, reminds me of Gopher days!

I have a big problem with this. The header says "The GNU C Library" and then in big letters "By: Elmer Landaverde".

You did not write either glibc or the manual. The original authors did not credit themselves, yet you've appropriated credit for what is essentially restyling the HTML output of texinfo into a less usable, unscrollable, unsearchable form.

If you insist on the huge attribution, change it to something accurate like "Style template by:"

That's fair.

These types of comment are now officially off-topic so I wouldn't normally make them but, since this submission is about the design of the webpage:

http://imgur.com/NNmmxdx

http://imgur.com/qv6BPj4

This is latest Chrome on iOS. That header banner is fixed (that's sub-optimal) and all the content is in that little box.

Yeah I agree with your comments. Initially I only tested as far down as tablets, because I figured that the target audience are programmers on their laptops or desktops. I will be fixing this issue on the next iteration.

As someone who often makes these comments, were they declared offtopic somewhere official?

Here's a comment from dang. Someone made a good, technical, submission. For a while the highest comment was about the design of the blog.

https://news.ycombinator.com/item?id=9238739

> A reader emailed to complain about how this and other HN discussions often become derailed by off-topic carping about blog design. I agree completely. Could there be a more classic form of bikeshedding? It would seem parodic if it weren't sadly real. This has become more of a thing on HN lately. It needs to become less of a thing.

> I don't mean to pick on you personally, or just on this one comment. (Your second sentence alone, by the way, would have been a helpful contribution.) The problem is the tedious stampedes such comments spawn.

This submission is a bit different because the design of the page is the thing being submitted, but I'm aware that I too easily make comments about the design of the page rather than the content of the page.

Some design choices are weird and prevent people from being able read the content and I wish there was a way to provide that feedback without derailing a thread.

Aye, that was my comment. :) I hope HN will come up with a nice solution to allow these kinds of comments but have them be less distracting.

Arguably, a threaded forum by design encourages tangential discussions which deviate from the topic the deeper you go. The problem in HN's case is all the threads are open and entirely visible - which is one of the cases where its minimalist layout works against readability.

I think the best solution would be thread folding (which I know is being worked on anyway) where the default is that all threads are collapsed. Then, off topic discussion wouldn't take up any more than a single post's worth of space by default. Having it be a conscious choice to move deeper into a thread also ensures that no one has to scroll past much content they don't care about.

That would be incredibly annoying on touch interfaces and generally not allow quick scanning of comments anymore. It would take a lot more time.

I suppose open threads by default would be more friendly, or maybe defaulting to open for mobile layouts.

But it taking more time would kind of be the point - opting in to participate rather than opting out by scrolling past content means fewer sarcastic comments about how a thread is off topic and irrelevant.

"Bikeshedding" has become yet another empty dismissal. The colour of a bikeshed is irrelevant when designing a nuclear reactor. But the "bikeshed" of a webpage has to do with usability, which is a critical component of any webpage.

Yes, when someone submits a webpage the design of that page is up for discussion.

Whe someone writes an interesting technical post about Cache Line Aliasing it's a shame when the most visible commet is a complaint about the blog platform.

I want more articles like that on HN so I'm going to stop leaving empty comments about page design on HN unless, like this example, the design is an intrinsic part of the submission.

And even here I could have worded my post much better.

Having said all that: a lot of the stuff submitted here is not accessible and that's a shame. It feels like we've gone backwards. Where you used to have a web page that had keyboard navigable elements that would announce themselves to the assistive technology it feels like we now have apps that abandoned usability and started making it up as they go along. What happens when you press and hold and image? What happens when you put your phone into landscape? Who knows, everyone does things differently.

You make some good points and you are correct that my redesign of the manual is far from ideal in terms of accessibility. I will definitely take these things into consideration and improve upon them. This is not an area I'm familiar with, which is the perfect excuse to go a learn about it!

In regards to the 'experimentation' done by websites. I would say that this 'experimentation' is something that should happen. How else are we supposed to discover new and better ways of doing things than by trying something different. Not all new things are better, and most of them fail. This trial and error, however eventually leads to better design and better 'standard' ways of doing things.

It is unfortunate that today accessibility has fallen down the priority list. Likely, a side effect of all the new ways we can interact with our electronics. So above all let me say thank you! We need people like you who remind developers to keep accessibility a top priority.

Oh no! I wasn't talking a out your site in my post! I'm sorry, I should have been much clearer.

On a semi-related note: Man Pages in HTML that do not look ugly: http://linux.bar/man1/memusage.1.html

This is a really great resource - so great, I'd love to have an offline copy for reference. However it doesn't look like its set up for easy mirroring with wget .. does anyone else have an idea how it could be mirrored locally for offline use, or shall I just contact the author?

You can mirror with wget the original, it has the same contents AFAICT, just different CSS: https://news.ycombinator.com/item?id=9245753

Could you get the sections to start out expanded by default?

Agreed on this.

An Expand All/Collapse All button would also be nice (but not instead of expanding by default-- the whole reason I'd be reading those documents is to read the stuff in the collapsed sections).

Agreed that the expandable sections feel a little unusual for this type of documentation. They're great for drilling down to particular information, but not so much for skimming or reading straight through.

I might even suggest putting the sub-section navigation in the sidebar a la readthedocs.

Yeah I could definitely do this.

If I were to add a collapse/expand all button would you still prefer for all the sub-sections to be expanded by default?

Yes I think so, the pane on the left already allows the user to control which section they are reading. I would assume that once a reader is in a section they would likely want to read/scan all of it. Excellent work by the way!

Agreed, it's tedious to click on each item to expand the page. Either expand it by default or provide a global switch for that expandability.

Unless I've missed something, this isn't a redesign of the library, it's a restyling of the manual as a website.

You are correct, this is just a restyling of the manual. Just curious, what did you think 'redesign' meant? I have mostly a front end background and I thought I was using the word correctly. But I might have been wrong.

Redesigning the GNU C Library would be, well, redesigning the GNU C Library.

What you've done is redesign the GNU C Library manual, HTML edition. Which you have done well, IMHO. It doesn't seem to involve refactoring C code.

from the phrasing i would have expected the code itself had been changed.

That makes sense, I have changed the title. Thanks for pointing it out!

> Redesigned GNU C Library manual

Its still readable as "manual for a redesigned GNU C library" in addition to the presumably intended "redesigned manual for the GNU C library".

Doesn't work without javascript

It looks great!

I haven't inspected how you did it but I guess it shouldn't be hard to apply it to other GNU manuals also, as all are very similar in the sense that they all are produced using the same tools.

Another idea: local search function similar to Sphinx's would be really nice.

Thats a great idea! This project was somewhat of a proof of concept. Maybe I will refine and apply it to other manual. Thanks!

PS: I couldn't find the local search function that you mentioned. Can you put a link so that I can see how it works?

Sure. Python documentation in https://docs.python.org/3/archives/python-3.4.3-docs-html.zi... is a good example. You can extract it anywhere and search just works without needing any server side components.

why is this comment downvoted?

Reply on news.ycombinator.com