Improve Roff support / Add RUNOFF to recognised languages #3126

Alhadis · 2016-07-21T00:58:18Z

This PR's doing quite a few things, so I'll try to keep my explanations terse for readability.

Roff

Improved syntax highlighting

Currently, the site uses an absurdly-limited grammar to highlight roff files:

rustdoc.1: Before → After
aha.1: Before → After
node.1: Before → After (lol, noticed they got their syntax wrong. I let 'em know)
pdffonts.1 Before → After

You can probably see what I mean.

Extra extensions

I've added a few extra file extensions for Roff:

.tmac: Troff macros. Refers to the standard macro bundles distributed with Groff and Troff.
mmn, mmt: Nroff and Troff macros, respectively.
Mostly distributed with the Plan 9 OS, but possibly in other distros too.

Sample licenses

The .tmac sample is from GNU Groff, but it's not GPL-licensed.
To quote groff_man(7):

It is written in classic troff, and released for free re-use, and not copylefted; manual page authors concerned about portability to legacy Unix systems are encouraged to copy these definitions into their pages, and maintainers of troff or its workalikes are encouraged to re-use them.

I'm not sure about the license of Plan 9, but I'm assuming that is copylefted. Hence the reason I didn't include sample files for mmn and mmt (unless their contents don't count?)

RUNOFF

The grandfather of roff, and indeed of all modern typesetting. I've added it primarily to help disambiguate the .rno extension, which is also used by some manpages.

Considering the antiquity of RUNOFF, it's not surprising the language doesn't command a widespread presence on GitHub. You're looking at something developed in the early 1960s... that's even older than the moon landing. However, at least two extensions see modest (albeit limited) distribution:

.rno (980 results)
.rnh (574 results)

RUNOFF used several other file extensions too, especially .run. I've left those out, for obvious reasons. My main motivation is to separate RUNOFF's classification from Roff's. The two languages are only superficially similar.

Colour choice

I chose a rusty brown to represent the language, the colour of a bronze typewriter.

Sample licenses / Highlighting preview

VMS_ZIP.RNH: This describes Zip documentation for VMS systems. I believe the license is okay, but I'd prefer somebody better versed in legelese to check.
mcp_help.rnh: Is this license okay?? Not sure.
longlib.rno: Taken from a NASA COSMIC project, which was released into the public domain. Not sure why the old Google site says "GPL v2", though.
contributing.rnh: Painstakingly written by yours truly, using this repo's contribution notes, Saltzer's original publications as reference, and a cheatsheat.

larsbrinkhoff · 2016-07-21T05:56:53Z

Good stuff!

Suggestion: Also add a new Roff langauge, and make Groff group under that. This would ease a possible future rename as mentioned in #2382.

Alhadis · 2016-07-21T06:01:09Z

Well... no. See, Groff IS Roff, it's just misnamed.

"Groff" is an abbreviation of "GNU Troff", referring to the GPL-licensed implementation of the proprietary AT&T Troff. The name "Troff" is often used interchangeably with "roff" too, which does nothing to ameliorate confusion.

"Troff" means "Typesetter Roff". It's the program used at Bell Labs to produce high-quality printed output for manuals and documents. There was a dumbed down version of the interpreter called "Nroff", which was designed to display a limited subset of roff commands suitable for terminal display.

Groff tackles both tasks simultaneously, so most users don't even know about the distinction.

Alhadis · 2016-07-21T06:06:22Z

Sorry about the history lesson, but you don't spend four months researching an ancient typesetting language without feeling like a nerd... heh.

The only "correct" approach would be to rename Groff to Roff in Linguist, but I'm well aware of the technical limitations imposed by GitHub's indexing system and whatnot. Heck, you know that as well as I do. :D

larsbrinkhoff · 2016-07-21T06:06:44Z

Groff being Roff was exactly my point. Since we can't rename Groff to Roff (yet), the next best thing may be to add Roff and make Groff group under it. This would have the effect that the language bar displays "Roff" instead of "Groff"

Alhadis · 2016-07-21T06:11:15Z

Hrm, that might actually work... have we done such a thing before? If so, it might explain the presence of MiniD and Parrot in the languages listing. Both of which are marked as "dummy" languages.

Would definitely like to hear more thoughts on this. =)

/cc @arfon @pchaigno

larsbrinkhoff · 2016-07-21T06:19:28Z

Would definitely like to hear more thoughts on this.

Yes, me too! I'm not sure if it's a good idea. I don't think there's any precedent.

larsbrinkhoff · 2016-07-21T06:50:52Z

I did some forensics to find the origin of those dummy file extension.

It seems Parrot only exists to group its two brethren languages together. On the other hand, MiniD was added some time in the stone age without a file extension, supposedly for some legacy reason. Some time later, a requirement was added that all languages must have a primary extension, thus a dummy extension was introduced.

It has also been suggested that languages could be added for the sole purpose of being used in a .gitattributes override. But as far as I know, it hasn't been done yet.

Uses better troff formatting. Removes v8 options from the man page. Also edits `node -h` in node.cc slightly. PR-URL: #5497 Reviewed-By: James Snell <jasnell@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

pchaigno · 2016-07-22T07:21:26Z

lib/linguist/languages.yml

-  tm_scope: text.groff
+  - .tmac
+  filenames:
+  - mmn


Can it also be .mmn? In your search results for that filename there seem to be quite a few .mmn files...

Where? Searching for .mmn throws up only a handful of results, and none of them are Roff.

As a matter of fact, I'm not sure WHAT they are.

Here for instance, but they do not seem to be Roff :-)

Hah! Nope, definitely not. ;)

They all just seem to be dates for some reason. :|

RalphCorderoy · 2016-07-22T12:47:10Z

Regarding grouping, if this is to do with a selection presented in a UI then I suspect "troff" is the most common description of the file format, e.g. file(1) uses that. They're all ROFFs in a sense, named after the RUNOFF program, and then Multics' Runoff, but widespread use came with Unix and that had the troff program for typesetting run-off. nroff, new roff, came first on Unix, and then it was modified to support a typesetter when they got the CAT, giving troff. The two programs share a lot of the same source. Folks don't write nroff source, they write troff source, and nroff is just a formatter for limited output devices that can read the same source. Using roff suggests you're talking historical pre-Unix RUNOFF descendants.

Alhadis · 2016-07-22T13:13:45Z

Well, I settled on roff as the language-grammar's name, because it seemed to represent the language in the most neutral, unbiased form. Am I wrong in believing the roff language was commonly referred to as troff in the early years to help differentiate it from its RUNOFF ancestor?

I'd like to have a better understanding of the exact transition of name.

RalphCorderoy · 2016-07-22T14:47:01Z

Its' a bit of a tangle. RUNOFF came first on CTSS. runoff was the Multics version. roff on Unix by Joe Ossanna existed fairly briefly before he did nroff, new roff, and then that program grew to cope with a typesetter, troff, rather than the TTY-style devices up to then. RUNOFF input looked similar, but definitely different, e.g. https://github.com/bwarken/RUNOFF_historical/blob/master/RUNOFF-files/Kermit/k10mit-136/k10133.rno

Calling it roff is fine. I don't know the system you're talking about to really be commenting, just pointing out that someone looking for this in a list would probably check for troff too. There's no need for groff to be mentioned, other than I gather it already is, just as Heirloom troff, and its extensions, don't need to be named either.

Alhadis · 2016-07-22T15:05:41Z

Ah, right. Well, this does affect what name is displayed in the site's advanced search page. If for any reason than being technically correct, I'd stick to roff though... (the pedant inside me is wishing history made this easier on us, hahah).

pchaigno · 2016-07-23T07:41:53Z

I ran a few counts on these new filenames and extensions:

I download the first 1,000 files from this search query and found only 93 mmn files (the GitHub search engine matches any file with mmn in the filename with mmn files first).
I downloaded the first 1,000 files from this search query and found 137 mmt files.
The .rnh search query contains files from 126 repositories by 102 different users.

Alhadis · 2016-07-23T07:45:53Z

Well yes, but I did mention the results weren't huge. =)

Recall the antiquity of the language we're dealing with, heh. Are you saying the numbers aren't enough?

pchaigno · 2016-07-23T08:14:45Z

@Alhadis I don't know. I'll leave that decision to @arfon :p

Alhadis · 2016-07-23T12:49:19Z

@pchaigno I should also mention RUNOFF is still used in OpenVMS systems for their documentation, although they use a mutated variant of it (DIGITAL Standard Runoff). I know nothing of it other than it's developed too far from the original RUNOFF to really be considered the same language (Ralph will probably attest to that).

@RalphCorderoy Just wanna say thanks (again) for all your hard work getting this knowledge together, mate. :-) Your repos have been an invaluable source of information, and it's like having a time capsule into the 70s on my computer. I really appreciate having history at my fingertips, especially after all the endless running around I spent prior trying to find concrete info on /r(?:un)?off/i. =)

(Yes, I'm slipping regular expressions into conversation now... I need psychiatric help...)

EDIT: /\br(?:un)?off\b/i* Sorry, typo.

larsbrinkhoff · 2016-07-23T14:28:13Z

I tend to think that languages with a long, proven history should have a bit of leeway. But then I have a soft spot for retrocomputing.

arfon · 2016-07-29T12:26:11Z

@Alhadis I don't know. I'll leave that decision to @arfon :p

👍 let's do it.

Alhadis · 2016-07-29T12:26:58Z

Preserving history, one grammar at a time. <3

Alhadis added 5 commits July 21, 2016 07:13

Swap language grammar used for Roff highlighting

e84204a

Define additional extensions/names for Troff files

f2ae3b6

Add language definition and samples for RUNOFF

93341be

Add heuristic to distinguish RUNOFF from Roff

22609dc

Kill orphaned submodule

abfe89d

Alhadis mentioned this pull request Jul 21, 2016

doc: Clean up roff source in manpage nodejs/node#7819

Closed

2 tasks

pchaigno reviewed Jul 22, 2016
View reviewed changes

larsbrinkhoff merged commit 1466b70 into github-linguist:master Jul 29, 2016

Alhadis deleted the roff branch July 31, 2016 00:11

Alhadis mentioned this pull request Sep 6, 2016

Broken link to original RUNOFF repository bwarken/RUNOFF_historical#1

Open

github-linguist locked as resolved and limited conversation to collaborators Jun 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Roff support / Add RUNOFF to recognised languages #3126

Improve Roff support / Add RUNOFF to recognised languages #3126

Alhadis commented Jul 21, 2016 •

edited

Loading

larsbrinkhoff commented Jul 21, 2016 •

edited

Loading

Alhadis commented Jul 21, 2016

Alhadis commented Jul 21, 2016

larsbrinkhoff commented Jul 21, 2016

Alhadis commented Jul 21, 2016

larsbrinkhoff commented Jul 21, 2016 •

edited

Loading

larsbrinkhoff commented Jul 21, 2016

pchaigno Jul 22, 2016

Alhadis Jul 22, 2016

pchaigno Jul 23, 2016

Alhadis Jul 23, 2016

RalphCorderoy commented Jul 22, 2016

Alhadis commented Jul 22, 2016

RalphCorderoy commented Jul 22, 2016

Alhadis commented Jul 22, 2016

pchaigno commented Jul 23, 2016

Alhadis commented Jul 23, 2016

pchaigno commented Jul 23, 2016

Alhadis commented Jul 23, 2016 •

edited

Loading

larsbrinkhoff commented Jul 23, 2016

arfon commented Jul 29, 2016

Alhadis commented Jul 29, 2016

Improve Roff support / Add RUNOFF to recognised languages #3126

Improve Roff support / Add RUNOFF to recognised languages #3126

Conversation

Alhadis commented Jul 21, 2016 • edited Loading

Roff

Improved syntax highlighting

Extra extensions

Sample licenses

RUNOFF

Colour choice

Sample licenses / Highlighting preview

larsbrinkhoff commented Jul 21, 2016 • edited Loading

Alhadis commented Jul 21, 2016

Alhadis commented Jul 21, 2016

larsbrinkhoff commented Jul 21, 2016

Alhadis commented Jul 21, 2016

larsbrinkhoff commented Jul 21, 2016 • edited Loading

larsbrinkhoff commented Jul 21, 2016

pchaigno Jul 22, 2016

Choose a reason for hiding this comment

Alhadis Jul 22, 2016

Choose a reason for hiding this comment

pchaigno Jul 23, 2016

Choose a reason for hiding this comment

Alhadis Jul 23, 2016

Choose a reason for hiding this comment

RalphCorderoy commented Jul 22, 2016

Alhadis commented Jul 22, 2016

RalphCorderoy commented Jul 22, 2016

Alhadis commented Jul 22, 2016

pchaigno commented Jul 23, 2016

Alhadis commented Jul 23, 2016

pchaigno commented Jul 23, 2016

Alhadis commented Jul 23, 2016 • edited Loading

larsbrinkhoff commented Jul 23, 2016

arfon commented Jul 29, 2016

Alhadis commented Jul 29, 2016

Alhadis commented Jul 21, 2016 •

edited

Loading

larsbrinkhoff commented Jul 21, 2016 •

edited

Loading

larsbrinkhoff commented Jul 21, 2016 •

edited

Loading

Alhadis commented Jul 23, 2016 •

edited

Loading