Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Pretty RFC

pretty-rfc.herokuapp.com

Post reply on HN
Print view View original

11–20 of 76 posts

Re: Pretty RFC

#11

Post by jrockway »

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...)

Re: Pretty RFC

#13

Post by autarch »

jrockway wrote: post #11

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.…

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.

Re: Pretty RFC

#14

Post by mislav »

zwp wrote: post #4

Cute, I like the way ASCII art is preserved. Small bug: RFCs 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.c…

Thanks for the report. Fixed.

Re: Pretty RFC

#15

Post by mislav »

kijeda wrote: post #3

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.

Re: Pretty RFC

#16

Post by urschrei »

jrockway wrote: post #11

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.…

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".

Re: Pretty RFC

#18

Post by pcl »

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?

Re: Pretty RFC

#19

Post by mislav »

postfuturist wrote: post #17

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.

Re: Pretty RFC

#20

Post by bitops »

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.
Post reply on HN