Pretty RFC | Hacker News Reader

Pretty RFC

pretty-rfc.herokuapp.com

453 pointsknowtheory72 comments

As it feels relevant, here's a site of mine that includes all the HTTP Status Codes in an easy referenceable format: http://httpstatus.es/

http://httpcats.heroku.com/

While httpstatus.es seems much more functional (the short descriptions on the index are a really nice touch), this one just made my day. Thanks!

Thanks for sharing! Much more convenient than Wikipedia, my usual go-to site for status codes.

your site is helpful for me,thank you for letting me know it

Cute, I like the way ASCII art is preserved.

Small bug: RFCs < 1000 that are not prettifiable have a extraneous zero in the datatracker.ietf.org link.

Eg: http://pretty-rfc.herokuapp.com/RFC123

redirects to: http://pretty-rfc.herokuapp.com/RFC0123 (left padding is probably a mistake here; some day we will have >9999 RFCs)

links to: http://datatracker.ietf.org/doc/rfc0123/ (404)

should link to: http://datatracker.ietf.org/doc/rfc123/

ps. XML format for RFCs that this leans on: http://pretty-rfc.herokuapp.com/RFC2629

Thanks for the report. Fixed.

I prefer the format at http://tools.ietf.org/html/rfc2616. It has links and it also represents the precise original spec. The version here omits several sections and looks too dense. The link pane on the left is good.

Wow, the navigation sidebar definitely increases the usability of the RFCs.

It would have more utility if in the search box you could type the RFC/BCP/STD number, e.g. "1591" or "STD 3".

Unfortunately every RFC I tried, except for the provided examples, returned "Could not prettify this RFC".

Added that you can write the RFC number in the search box. Will do so for BCP/STD in the future.

Yes, "could not prettify this RFC" is a problem I'm having right now because most sources aren't available. I'm working on obtaining those sources.

Same here.

DISCLAIMER: This reply contains a slightly modified implementation of RFC 1097.

Suggestion: change the linked email addresses to a graphical representation. It may not help much but this lowers the barrier a bit too much for some clueless newbie to 'click on the link to email for support'. RFCs have fairly limited visibility and that's why those addresses are on there, if you significantly increase the visibility then you should probably build in a small barrier before the contact info can be used rather than to make it super easy.

Awesome. But I've never heard of the "is now diamonds" meme...

It is a reference to Old Spice's "The Man Your Man Could Smell Like" ads: http://www.youtube.com/watch?v=owGykVbfgUE

There are EPUB and Mobipocket versions of all RFCs already available, by the way. See this thread: http://www.ietf.org/mail-archive/web/79attendees/current/msg....

The link to the mobi versions still works, but not the epub link. After some quick Googling I can't find a working source for them.

Still, it sounds like a great resource. If anyone knows of a working link for the epub, please let us know.

I love this a lot.

Minor formatting issue, perhaps. The braced formed of reference ends up losing something in the current parsing. Seeing something like "reference in RFC 1234 <a>RFC 1234</a>" jars me out of reading the document. It would be pretty neat in those cases to collapse the string so it was simply "reference in <a>RFC 1234</a>". In the cases where you can't collapse the string, to preserve reading flow, it might make sense to leave the braces surrounding the link.

Nice stuff. I'd love to see line-number ranges on hover over paragraphs / sentences, too, to support line-number-based conversations.

What's this using as a data source?

Very close layout to http://documentup.com/ Which is nice =D Kudos to the effort, great app.

Awesome! Small, but important bug is that internal links are broken:

correct link : http://pretty-rfc.herokuapp.com/RFC2616#character.sets

link in text : http://pretty-rfc.herokuapp.com/RFC2616#character-sets

Thanks for reporting! I really need to improve internal linking.

When I search for "1483", my only result is 2684, which supersedes it. But when I try to view it, I'm told "The source XML for this RFC isn't available, therefore it can't be reformatted." Did the IETF shut you down?

I don't think the original documents on the IETF datatracker site are that bad- it seems pretty clean and easy to read already.

The RFC for IMAP returns the same error regarding the XML source. I had assumed that it was parsing the text files, but apparently it only supports parsing the subset of RFCs that have XML available. :(

This is great. Small complaint: searching for RFC2822 comes up with nothing. 2822 gets what I want. Plz to fix :)

Done :)

High five!

Thank you so much. I've waded through plenty of unformatted RFCs this week, and this is everything I've hoped for.

Would be nice if it converted lists into their <ol> or <ul> equivalents.

Very nice - this will make RFC reading much easier. Would be nice to have DuckDuckGo use it - will submit !bang request.

Any timeframe on finishing RFC coverage? RFC 3514 isn't prettyfied yet.

I might be weird but I find the RFC-editor font easier to read.

awesome project. there is some work in progress for a duckduckhack plugin[1] on this: https://duckduckhack.uservoice.com/forums/5168-plugins/sugge...

dunno, maybe those two efforts can be joined.

[1] http://www.gabrielweinberg.com/blog/2012/05/introducing-duck...

Finally! I've even paid for Word documents of RFCs (hello, SIP) just to have them marked up, without the idiotic headers in the middle of each page, and hyperlinked throughout.

Compared to reading some other specs (like, say, some of the SCSI ones) RFCs are just painful. Especially with the ASCII art diagrams.

Now, if only the IETF could realise that "being liberal in what you accept" is a horrible idea and remove all usages of SHOULD/MAY or "infer", we'd really be rolling.

It would be nice if the errata for each RFC was included somewhere - perhaps in the right margin for the relevant section?

Lame, that sites doesn't even have your standard Cat Response Codes http://www.flickr.com/photos/girliemac/sets/7215762840946712...

Interesting. I thought I wanted something like this, but the problem with RFCs is the archaic writing style. It's hard to understand the details of a low-level network protocol when you also have to remember their redefinitions of words like SHOULD, MUST, MAY, MIGHT, PERHAPS, QUITE POSSIBLY and sort through ASCII art that is split across multiple pages. (The standards are also excessively wordy and poorly organized. And if you think the problem is just me, try finding any piece of software that actually correctly implements any RFC spec :)

So basically, the all text format of RFCs is the least of their problems. But this is a nice attempt.

(I wonder how many people die every year because the National Weather Service issues tornado warnings in ALL CAPS with VROUS ABREVS throughout the text. Computers can do lowercase now, guys...)

This comment has no place at the top of the page.

> the problem with RFCs is the archaic writing style

I'll admit, reading standards is more difficult than reading regular prose, it is nearly impossible to use language precisely without getting too verbose. Languages, and English especially, are full of little ambiguities; even simple words like "or" have more than one meaning! This doesn't quite cut it when it comes to specifications. If the spec is ambiguous then it's possible for two different implementors two come up with incompatible implementations, which kinda ruins the point of a spec. Try to think of RFCs (and standards in general) as the legalese of the software world. They're more verbose than you're used to, but that's necessary.

>have to remember their redefinitions of words like SHOULD, MUST, MAY...

Let's take a look at RFC2119 [1], where these terms are defined. The word "MUST" means you must do something, the word "SHOULD" means you should do it, but you aren't required to, and the word "MAY" means you could if you wanted to, but aren't required to. Well... that's what those words mean in English too! Are you really complaining that you must know English in order to read English?

The only slightly confusing word is SHALL, which is fairly uncommon in modern English. Even SHALL has not been redefined though, in RFCs it means exactly what it means anywhere else.

> And if you think the problem is just me, try finding any piece of software that actually correctly implements any RFC spec :)

Adding a smile to the end of your sentence doesn't make it any less stupid or wrong. Almost everything you touch today when using the internet is defined by an RFC. ARP (RFC826) is dead simple, and has been correctly implemented for decades. TCP (RFC793) admittedly took a few revisions to get right, but if it wasn't correctly implemented we wouldn't be able to have this conversation. Come up with your own examples, there are plenty more. If you think engineers are so stupid they don't know how to understand text which is a slightly more verbose than usual you have a pretty low opinion of humanity.

> So basically, the all text format of RFCs is the least of their problems.

Have you ever tried to read a spec which is actually difficult, like c++ [2]? Specifying a language is at least an order of magnitude more difficult than specifying a protocol or "best practice", and it shows in how dense language specifications are. RFCs are pretty damn readable, I often browse through them for entertainment.

> (I wonder how many people die every year because the National Weather Service issues tornado warnings in ALL CAPS with VROUS ABREVS throughout the text. Computers can do lowercase now, guys...)

Once again, you must have a pretty low opinion of humanity to think we don't know how to read abbreviations or uppercase characters.

1: http://www.ietf.org/rfc/rfc2119.txt 2: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n333...

Let's take a look.

Oxford says "should" implies "used to indicate obligation, duty, or correctness"[0]. That sure does not sound like "aren't required to" to me. Sure enough, if you look into "must" [1] you see that it is defined as "be obliged to; should".

Maybe you shouldn't be chiding people implying how simple English is when you're not so solid on it yourself, especially when you've given a whole treatise in your previous paragraph about how language is full of ambiguities and words can have multiple meanings and such.

[0] http://oxforddictionaries.com/definition/should [1] http://oxforddictionaries.com/definition/must

Edit: Am I wrong? Am I ruder than the parent? Awaiting comments.

Edit2: Okay, so it looks like I'm wrong about "should". I really don't know why the heck "should" is listed as a definition for "must", then. I'd still like to point out that even the dictionary seems confused and maintain my point that it's not as simple and clear as portrayed.

The way words are used in native languages and the connotations they bring up is not easily and fully explained by a 7 word blip in a dictionary... even then, this dictionary claims that must is "should (expressing necessity)": that parenthetical is key to the strength of "must".

In fact, looking at it, you dropped half of the definition you pulled for "should" ("typically when criticizing someone's actions") and I will claim are mischaracterizing what an "obligation" is (just because I am obligated to do something, doesn't mean it is a necessity for me to do it).

Putting this into practice, if you tell someone that they /should/ stop at the kiosk before parking in the lot, normal speakers of English will treat that drastically differently than if you instead say that they /must/ stop at the kiosk before parking in the lot; the former feels subjective while the latter feels objective.

For a rather clear example of this: "you /must/ open the drawer before you [can] take things out of it" would go unquestioned, while "you /should/ open the drawer before you take things out of it" will cause many people to wonder what the alternative to opening the drawer could be.

(edit: I see that chc made a similar complaint about your comment to me 10 minutes earlier, but I didn't see that comment as I was working on mine; I think mine has some value still with the examples, and a slightly different focus, so I will leave it in the thread as a reply.)

Trotting out brief dictionary definitions is rarely useful for precisely nailing down the common meaning of words, as it is hard to express nuance in such a small space. Fortunately, though, Oxford actually does go out of its way to make it clear. Unfortunately, you omitted those extra details. Let's look at the bullet points clarifying the meaning:

"indicating a desirable or expected state"

"used to give … advice or suggestions"

One of the examples it gives is, "by now pupils should be able to read with a large degree of independence." Few native English-speakers would read that sentence as saying that there is no option but for students to read with a large degree of independence. What it means is that such a level of reading is desirable or expected, but not required.

In common usage, should is much weaker than must. Another good example: "I should exercise tonight" vs. "I must exercise tonight." The former almost sounds like the speaker knows it won't happen and feels guilty, whereas the latter sounds like the speaker is bound and determined to exercise. Don't you think?

There relevant definition of these words does not come from the dictionary. Most RFCs say which RFC they pull from, for instance, RFC2119: http://pretty-rfc.herokuapp.com/RFC2119

It's right there in the first couple of sections, usually.

There's a lot of variation in the quality of RFCs, both from a technical standpoint and from a writing standpoint. I've read a number of the email and MIME related RFCs, and they're terrible. They leave out so many details, and the decisions that went into them seem designed to make email as hard to parse as possible.

The HTTP RFCs have been, in my experience, better written. They just seem to be more solid.

The "archaic" style is really just how you write a spec. The all-caps MUST, SHOULD, etc. stuff is about being as specific as possible. That's a good thing for a spec.

> have to remember their redefinitions of words like SHOULD, MUST, MAY, MIGHT, PERHAPS, QUITE POSSIBLY

I find that to be one of the easier parts. They establish a very careful set of vocabulary and then use it consistently and CAPS it to make sure you don't accidentally miss it. The definitions match the standard of the definitions, so it's not hard to remember. They embody the concepts "you have to", "you are not allowed to", "you can if you want", "we encourage you to", and "we don't know for sure but we think so", and a couple others.

They have to be precise, they're trying to write the equivalent of human code. Wiggle room and vagueness is bad.

One problem with RFC quality is that they pull in standards from other areas, so sometimes X was written for one standards body, Y for yet another, but they were both converted to an RFC and thus the styles differ.

Compared to most specifications, RFCs are incredibly clear. While quality varies, they're remarkably approachable documents.

Of all the things to dislike, I find your dislike of SHOULD/MUST/MAY to be incredibly bizarre. The definitions of the words are intuitive, they place the definitions at the top of the document, and they use the words to eliminate all ambiguity when reading the document.

If you don't like RFCs, I'd be very curious to know what specification documents you do like.

I don't think they have redefined any of those words, merely provided more concrete meanings.

It is true that the writing style RFCs is hard to read, but I don't think there's much hope of changing that while maintaining the sort of precision that is necessary in this sort of document. Legal documents are also hard to read.

The ALL CAPS nature of weather alerts is due to the constraints of a very old but extremely widely deployed alert broadcast system. In the US, at least, the NWS is upgrading their alert broadcast systems so that this will no longer be the case, but this will definitely not happen quickly.

Couldn't they write the canonical version in mixed case, and then convert to all caps for distribution via legacy channels? It doesn't seem like it would be that hard to make it so that, even if it's all-caps in some channels, the version distributed via weather.gov is written in some more readable format. Or is there some legal requirement to have exactly one canonical ASCII version of the warning?

First of all, I'm not an insider, I'm just a weather nerd who came across this story awhile back and was really curious about it so I did some research.

That said, my understanding is that they are basically going towards a widespread mixed-mode setup now, but they haven't yet for historical and budgetary reasons.

The system they'll be replacing is largely the result of tragedies like the Andrea Doria and countless less famous weather-related accidents that were caused by faulty communication of important weather bulletins. Because of this there was a pretty significant investment in designing and deploying a really robust system, and it was rolled out extremely widely, including far flung and remote weather stations, and was adopted elsewhere as a standard as well.

Fast forward to today and the aging system does the job but is in a rather precarious state because everyone who designed and built it is long dead, and in the face of shrinking budgets, like the NYC subway system and the national air traffic control systems, for most of its history it was maintained just enough to keep pace but rarely upgraded.

Only relatively recently has there been momentum behind modernization and the big driver behind that has been the increasingly deadly tornado seasons we've been experiencing over the past decade or so. The need to be able to push out more geographically precise bulletins as well as to make them more impactful (they recently started using phrases like "you will die if you do not seek shelter" in select tornado alley locations) in the hope of decreasing casualties has been a major driver behind this change.

> So basically, the all text format of RFCs is the least of their problems.

try reading specs that are from 3gpp, and then you would realize the bastion of clarity that is ietf. and the format of 3gpp specs is ms-word (yes you read that right), there is zero hyper-linking across various specs, finding how something works etc. is a matter of opening up at least 3-5 documents, and have a standards guy next to you to make sense of it all...

I was going to make this exact comment. I've been working on implementing part of the 3GPP diameter protocols, and they are an absolute nightmare in comparison to reading RFCs. So many documents that mostly repeat what other documents say, adding a small piece of information here and there with hundreds of cross-references, in a completely unreadable format.

As for the ms-word-ness, I recommend this site for PDF versions of the documents [1]. Just bask in the ridiculous amount of versions and documents in that list and be happy that RFCs are at least human-readable and in a standardized format...

1: http://quintillion.co.jp/3GPP/Specs/

oh dear lord! diameter is totally insane. other than the base protocol, everything else e.g. the gx, s6 specs are impossible to decipher. with multiple versions etc. things are even more insane, and hunting down for duffs boils down following the cr's for the version. aghhh! I have been using the above site that you mentioned, but it still doesn't take the pain away...

I don't know about 3gpp, but a while back I was working on an OMA-DM implementation and those specs are a nightmare.

I agree, but that's more of an information design problem; adding an explanation of the RFC 2119 key words (or rather, the facility to provide a clear, concise explanation) would be an interesting next step, along with the ability to remove things like ASCII art. Anything beyond that is well into the realm of textual editing, and I suspect that there would be a lot of crying foul, considering that one of the main aims of these RFCs is to avoid ambiguity and the need for interpretation (certainly beyond narrow, well-defined circumstances) – never mind that as you point out, specs are never implemented "correctly".

RFC 2119 all the things. I write all documentation touching any subject, using the definitions for RFC 2119.

Avoids a zillion of misunderstanding, and makes reading easier too.

Have a look at the various other specs if you want something to compare the RFCs to.

I'll take the RFC format (short, to the point and really clear) over others any day.

Most of the times I feel as though those that write specs have received explicit instructions to make things as verbose as possible to justify the insane pricing of standards documents.

Archaic in this case is just another word for continuity and that's not a bad thing. Imagine every RFC hopping on to the latest bandwagon in terms of presentation, powerpoints, pdfs, html animated images and so on. It would be a cacophony, now it is just the minimal amount of information required to implement something. It's great in a minimalist way.

> when you also have to remember their redefinitions of words like SHOULD, MUST, MAY, MIGHT, PERHAPS, QUITE POSSIBLY

So why not generate them with tooltips, i.e. when you hover your mouse over an ALL CAPS word, you'll get a tooltip with RFC2119?

Have you read RFC2616? It is quite approachable, and this is an improvement over the plain text version. Any web developer worth his or her salt should know about it enough to at least look up status codes and headers. It's resolved a number of debates at work when designing REST API's.

But ignoring all of the ways RFCs could be better, this site is significantly better than the alternatives (the ietf site, plain text on some random domain, or that shitty purple one i always seem to end up on...)

How much of that concern could be helped by displaying tooltips over those words? A little dotted line underneath MUST, and a tooltip with the definition.

I notice this is a heroku app. Do you mind sharing what heroku plan you are using, and how well your setup is handling today's traffic? Have you had to do anything significant to handle a spike in traffic today?

The app is running on a single (free) Heroku dyno, PostgreSQL as db & full text index, and fronted with Rack::Cache using 5MB memcache for storage (also free).

It survived being first on HN for hours, no probs.

https://github.com/mislav/rfc/blob/74b4181/app.rb

I'm not the original author but after a quick look at the application code (https://github.com/mislav/rfc/) it seems like mislav's just serving the documents from the database. It also caches the results so the free Heroku plan should be more than enough to support this.

Really nice work! This will come in very handy when referencing information. If there's a way to donate to the development effort, I'd be happy to kick in a few bucks.

Simple pretty hacks are the best hacks.

Very good. But search should include an indicator if the target rfc is prettified or not.

Now you just need to make the HTML5 specs human-parseable.

I like the idea! But... I'm just not a fan of Bootstrap's typography. IMHO, it's too dense and low contrast, especially compared to the Flask Sphinx theme (my measuring stick for beautiful, readable documentation).

"Read it from offical location" just sounds vulgar.

Excellent use of the bootstrap css!

Much easier to read. Thanks.

Doesn't work with 6455 :(

the content page is not looking good,like the featured HTTP 1.1

Reply on news.ycombinator.com