search

becarpenter / book6

A collaborative IPv6 book
Other
228 stars 23 forks source link

Topic/dopheide/rfc link style fixer #89

Closed dopheide-esnet closed 6 months ago

dopheide-esnet commented 6 months ago

I noticed a few inconsistencies in how the RFC links were formatted, asked Nick what he preferred, then went down a rabbit hole and this is the result.

becarpenter commented 6 months ago

This may need some discussion. I would have to check in detail, because some of these cases may deviate from what I'm about to write. The RFC Editor's preferred style draws a clear distinction between "RFC 1234" used as a noun (with a blank space) and "[RFC1234]" used as a citation (with no blank space). Using a citation as a noun is considered bad style by many people. Personally I'd prefer to follow the RFC Editor's style if we can.

So you'd write (in plain text) RFC 1234 specifies the whatnot. or The whatnot [RFC1234] consists of..... This gets a bit messy when you want both forms to have hyperlinks to the RFC, because for the noun case you want [RFC 1234](url) and for the citation case you want\[[RFC1234](url)\]. You need those extra brackets for the citation.

Add to that my kramdown-derived trickery and a random collection of authors, and I think we have a recipe for inconsistency.

So, first question, is it OK to follow the RFC Editor's preferred style?

dopheide-esnet commented 6 months ago

Oh, following the RFC Editor's style makes perfect sense. Is there anything you'd like me to automatically fix across the board? If not we can close this and I'll just try to pick up things manually as I read through. (I should have another set of small fixes coming later today.)

becarpenter commented 6 months ago

Please do let me know of anything you spot. If it's a general problem, I could possibly fix it by having makeBook apply a fix across the whole book. And I will go through the ones in your PR because I am sure that there are some deviations from style.

One other thing I forgot in my previous comment. As I said, the RFC Editor likes a blank space when using RFC 1234 as a noun. At the moment makeBook does not insert that space when a user writes {{{RFC1234}}}. I'm not sure whether to implement that or not. Opinions welcome.

dopheide-esnet commented 6 months ago

I kinda had a similar question about the {{{RFC1234}}} format. Right now, there are some sections where you actually have a list of references that are displayed as [RFC1234, RFC5678, RFC7890]. I feel like that looks better than [RFC1234], [RFC5678], [RFC7890], but I don't know how the {{{'s will handle it.

becarpenter commented 6 months ago
  1. I just went through all your fixes and applied most of them manually to main. It's such a pain that Git doesn't allow me to pick and choose within a PR. So don't be offended but I'll close the PR.
  2. I grabbed a copy of RFClinkstyle. Looks good (although I'm personally allergic to regular expressions; my brain doesn't work that way for some reason). I'll think about blending it into makeBook, when I have time. That would put it under a BSD license, is that OK?
  3. Fully agree about [RFC1234],[RFC1235]. I think I can figure out a fix when I see }},{{ in the input stream. Again, when I have time.
dopheide-esnet commented 6 months ago

Yes, take whatever you want under the BSD license. No problem.

becarpenter commented 5 months ago

I finally got around to fixing all the RFC citations to match the RFC Editor's style - but I still haven't forced myself to use REs, I don't know why I am so allergic to them. Commit f02a351 if you're interested, one-off code at utilities/fixCites.py