mislav / rfc Goto Github PK

View Code? Open in Web Editor NEW

938.0 37.0 56.0 165 KB

Pretty RFC indexes and reformats RFC documents for easier discovery and viewing.

Home Page: https://pretty-rfc.herokuapp.com

License: Creative Commons Zero v1.0 Universal

Ruby 30.72% JavaScript 55.25% Shell 0.56% CSS 6.05% CoffeeScript 0.02% HTML 7.39%

rfc's Introduction

Pretty RFC

The goal of this projects is to collect and reformat official RFC documents and popular drafts.

RFCs, as published officially, are in unsightly and impractical paged format. What's worse, the official format of most RFCs is plain text, even though they are authored in richer formats such as XML.

Running the app

Dependencies:

git
Ruby 1.9
rake
Bundler
libxml2
PostgreSQL

By default, the app will try to connect to the database named "rfc" on localhost without a username or password. This can be affected with the DATABASE_URL environment variable. If the database doesn't exist, the boostrap script will try to create it.

# initialize dependencies and database
$ script/bootstrap

# start the server
$ bundle exec rackup

# now visit http://localhost:9292/

The RFC index

The index of all RFCs is pulled from FTP: ftp://ftp.rfc-editor.org/in-notes/rfc-index.xml

Then the metadata for each RFC entry is imported to the database. This is done by the "import_index" rake task as part of the bootstrap process.

The search index

Searching is done with PostgreSQL full text searching. The necessary indexes, stored procedures and triggers for this are in Searchable module.

The search results ordering is not perfect, but it is improved by bringing in a popularity score from faqs.org. This is done by the "import_popular" rake task as part of the bootstrap process.

Fetching and rendering RFCs

When an RFC is first requested and it has never been processed, the app tries to look up its source XML document and render it to HTML. The XML lookup goes as follows:

The fetcher tries to find the XML in http://xml.resource.org/public/rfc/xml/ where some RFCs in the 2000–53xx range can be found.
Failing that, it fetches the metadata for the RFC from http://datatracker.ietf.org/doc/
If there is a link to the XML from the datatracker, use that. There probably won't be a link, though.
When there is no XML link, the fetcher looks up the draft name for the RFC and checks if it can at least find the XML for its draft at http://www.ietf.org/id/

Note: This process only discovers XML sources for a small subset of RFCs. This is the biggest problem I have right now. The XML and nroff files in which RFCs were authored are usually not published, but are archived by rfc-editor.org and available by request by email.

I'm investigating is there a way for bulk retrieval of these source files.

If unable to obtain them, I will have to reformat RFCs by parsing the current publications instead of the source XML. This might be a lot of work.

When obtained, the XML is parsed and rendered to HTML by the RFC module. The templates used for generating HTML are in templates/.

rfc's People

Contributors

Stargazers

Watchers

rfc's Issues

Errata

@mislav This is great. Well done for putting this up.

Many RFCs have important errata. The official source never folds the errata back into the canonical text so most people miss it. You have an opportunity to do the internet a big favour by putting the errata into the published text!

Here's an example: http://www.rfc-editor.org/errata_search.php?rfc=3696

How to collaborate formating other RFCs?

There are only 4 RFCs at http://pretty-rfc.herokuapp.com/

Can I add others? How to collaborate here to enhance the database (not the software).

Example: I need to format rfc8141, how to start?

RuntimeError: no node at "/rfc"

Drafts seem broken, e.g. http://pretty-rfc.herokuapp.com/draft-kelly-json-hal

Request: increase readability

This is awesome!

I have a few requests that I think would increase readability:

bigger font-size
increase line-height
make lines 50-80 chars long. 72 seems to be the RFC-standard.

OAuth Draft no longer working

The link to the OAuth draft gives:

RuntimeError: no node at "/rfc"

This project was abandoned?

It is 5 or 6 years ago... And, in nowadays, we can find RFC 7990 as a reference specification for this repo...

And there are a community working to new tools (hum.. it is Python), see results at https://www.greenbytes.de/tech/webdav/rfc7990.html
, the tool at https://xml2rfc.tools.ietf.org/
or the install at https://pypi.python.org/pypi/xml2rfc

Add support for RFC7230-RFC-7235

I read briefly through how the app fetches the RFCs but didn't have time to fully investigate it. Going to create this stub for now.

https://www.mnot.net/blog/2014/06/07/rfc2616_is_dead

http://tools.ietf.org/html/rfc7230
http://tools.ietf.org/html/rfc7231
http://tools.ietf.org/html/rfc7232
http://tools.ietf.org/html/rfc7233
http://tools.ietf.org/html/rfc7234
http://tools.ietf.org/html/rfc7235

Bookmarklet link gives "Not found"

I tried clicking the "Bookmarklet: Prettify RFC" link on the front page, but it gives a

Not found

Resource is not present in the app.
← Home

response.

rfc2109 ： no such file

BOOM! Something exploded.
The error message was:
Errno::ENOENT: No such file or directory - /app/tmp/xml/rfc2109.xml

Please report bugs here.

← Home

Mobile UI legibility improvements

On mobile size, you can increase body left-right paddings, font size and line heights just a little bit to improve legibility. It is not even possible to keep reading on mobile/tablet this way. (probably this is not something designed for that purpose, but here are my 2¢).

Comments

Not 100% sure about this myself, but perhaps it would be good to allow comments and conversation about the RFCs?

In theory there's nothing stopping interested parties getting involved with the IETF directly, but in practice it's a pretty forbidding clique.

Allowing comments might actually tempt people with an opinion but little spare time to have their say about these important documents.

Command-Line

It'd be great to be able to feed a command the XML and get the pretty HTML on STDOUT; I have a feeling it'd be incorporated into a lot of toolchains if you did.

Adding a bibtex

Hello,

I think it would be nice to add support for exporting all metadata about an RFC as a bibtex.

http://tools.ietf.org/html/draft-carpenter-rfc-citation-recs-01#section-5.2

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

Copyright statements

Nice project.

However, AFAICT you're re-publishing without the copyright statements.

Ignoring the legal consequences (if you can), doing so is pretty anti-social.

See section 3(c) of http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf. Note that that doesn't explicitly cover older documents, but they generally contain language that allows you to re-present the document -- provided that you include the copyright statement.