Frequently Asked Questions document

[pchaigno]

From #4263:

I started working on this because I don't feel the current documentation fits the users' expectations. They arrive here with a specific problem and must devise a solution by reading a complete description of how Linguist works (overview, overrides, troubleshooting, etc.). I'm guessing this is part of the reason why so many users don't read the documentation before filling in the issue template.

An FAQ seems more fitting. We can address the most common issue with concise explanations and adapt it as users file new issues. I think it should be extensive without aiming to be comprehensive. I'm imagining a single Markdown document with a summary of questions at the top and 1-4 lines answers to each.

This pull request adds said FAQ, with the answers. I also updated the README and the issue template.

@lildude @Alhadis Don't hesitate to push new commits if you want to improve the wording.

Template removes as it doesn't apply.

[lildude]

Thanks for starting this @pchaigno. I don't have the bandwidth this week for a full review, but will take a proper look and push changes etc when I get the chance.

[pchaigno]

Ping @lildude @Alhadis. I'm hoping this could help reduce the number of issues being opened each week.

[lildude]

@lildude @Alhadis Don't hesitate to push new commits if you want to improve the wording.

Sorry about the delay @pchaigno. I'll block out some time this afternoon to work on this. I'll probably make changes directly to the branch and push them up.

[lildude]

@pchaigno whoops. I'm so used to the branch method we use internally that I completely missed you used your fork for this PR.

I've pushed my changes to the faq branch on this repo and have opened pchaigno#9 against your faq branch - nothing like PRs for PRs. 😄

[lildude]

I'm biased as I contributed a lot to this as it stands now, so I'm going to hold off putting my 👍 on it until @Alhadis has had a chance to use his excellent 👸🇬🇧 skills. (I was taught 👸🇬🇧 in 🇿🇦 as a kid but it clearly isn't as good as that taught in 🇦🇺 😆).

[Alhadis]

I'm normally a champion when it comes to deliberately misreading sentences that contain those bloody emoji faces). But I was clutching at straws tonight. 😢 I'll just have to read it like a normal adult. 😢

[lildude]

👸🇬🇧 == Queen's English

[Alhadis]

Fun fact: When writing documentation, it helps to start each sentence on a new line. Not only does this facilitate diffing and code review, it helps to identify sentences which are too damn long.

Sentence length is an overlooked aspect of documentation quality, one which isn't mitigated by enforcing a maximum line length. 😉 Try disabling line-wrapping for a while; it's a real eye-opener.

Alright, diatribe finished. Back to a refreshingly clearer review. 👍

[pchaigno]

Fun fact: When writing documentation, it helps to start each sentence on a new line. Not only does this facilitate diffing and code review, it helps to identify sentences which are too damn long.

I couldn't agree more! It even has a name :-)

Sentence length is an overlooked aspect of documentation quality, one which isn't mitigated by enforcing a maximum line length. 😉 Try disabling line-wrapping for a while; it's a real eye-opener.

Although I agree we should restrain from writing long sentences for documentation, I'd argue they can be a real pleasure to read. And we don't want paragraphs made only of single-clause sentences...

[Alhadis]

I couldn't agree more! It even has a name :-)

Heh. Brian Kernighan, the driving force behind the troff typesetting system, is credited by the author as his inspiration for semantic linefeeds. 😀 No surprises there.

Roff actually benefits from the "one sentence per line" rule. It helps the typesetter with paragraph justification and alignment, producing more even-looking language and fewer rivers, among other things. :)

[Alhadis]

I've spent virtually all day reviewing this and am now brain-dead as a result, please enjoy.

PS: I hate markdown. Markdown must die.

[stale]

This pull request has been automatically marked as stale because it has not had recent activity, and will be closed if no further activity occurs. If this pull request was overlooked, forgotten, or should remain open for any other reason, please reply here to call attention to it and remove the stale status. Thank you for your contributions.

[timotheecour]

ping

[lildude]

Nudge.

[stale]

This pull request has been automatically marked as stale because it has not had recent activity, and will be closed if no further activity occurs. If this pull request was overlooked, forgotten, or should remain open for any other reason, please reply here to call attention to it and remove the stale status. Thank you for your contributions.

[Hrxn]

Not sure if this is a good fit for the Frequently Asked Questions document, but I could not find anything relevant elsewhere, and it's not really an issue either, so I figured just try and ask here..

Is there something wrong with the language stats bar? I'm suddenly seeing the language percentages below the bar (instead of displayed in the stats bar itself like before), and I somehow thought this looked a bit broken.
Or is this an intentional design change?

If yes, is there any changelog for stuff like that?

[lildude]

Is there something wrong with the language stats bar? I'm suddenly seeing the language percentages below the bar (instead of displayed in the stats bar itself like before), and I somehow thought this looked a bit broken.
Or is this an intentional design change?

If yes, is there any changelog for stuff like that?

This is definitely a design change on the GitHub.com side of things that is completely independent of Linguist. The best peeps to ask are GitHub Support using the "Contact GitHub" link at the bottom of every page.

[Hrxn]

Okay, good to know, thanks for the quick response!

[davidbrown2324]

Hello,

This is my first post to an open source project so I apologize if I have done this wrong. I have spent a few weeks trying to add support for the ImageJ macro language ( .ijm files ) to GitHub by contributing to linguist. This file type is widely used for scientific image analysis and is present in thousands of GitHub repos.

At this point I have:

• ruby installed
• ubuntu 20.04 installed
• docker installed
• linguist repo forked and cloned and edited according to instructions.
• my own language-ijm repo containing a grammars folder
• an imageJ.tmLanguage file within that folder

I am stuck at the point of running add-grammar from powershell in windows.

"PS C:\Users\David Brown\Documents\PythonScripts_New\addIJM\linguist\script> ruby add-grammar https://github.com/davidbrown2324/language-ijm/blob/main/grammars/imageJ.tmLanguage
Checking docker is installed and running
$ docker ps
Registering new submodule: vendor/grammars/language-ijm
$ git submodule add -f https://github.com/davidbrown2324/language-ijm vendor/grammars/language-ijm
$ script/grammar-compiler add vendor/grammars/language-ijm
Traceback (most recent call last):
5: from add-grammar:108:in main
4: from add-grammar:48:in command
3: from C:/Ruby27-x64/lib/ruby/2.7.0/open3.rb:390:in capture2e
2: from C:/Ruby27-x64/lib/ruby/2.7.0/open3.rb:208:in popen2e
1: from C:/Ruby27-x64/lib/ruby/2.7.0/open3.rb:213:in popen_run
C:/Ruby27-x64/lib/ruby/2.7.0/open3.rb:213:in `spawn': Exec format error - script/grammar-compiler (Errno::ENOEXEC)"

What would have helped me, what I would add to the FAQs

• Do I need ruby to contribute a new language?
• Do I need docker to contribute a new language?
• Is a syntax highlighter file necessary to add a new language?
• What language should a syntax highlighter be written in? (If it works for Atom will it work for linguist and vice versa).

Sorry for the long post. Thanks for all your combined efforts, I would really love to contribute. Any help/ response appreciated.

[davidbrown2324]

@waldyrious thanks for the thumbs up. Are you equally lost, or do you know how I might resolve the error message?

[waldyrious]

@waldyrious thanks for the thumbs up. Are you equally lost, or do you know how I might resolve the error message?

I just appreciated the care you took in documenting in detail what you did, where you stumbled, and what would have helped you (in the context of the FAQ that's tracked in this issue). I'm sorry that I can't help you myself.

[davidbrown2324]

@waldyrious Thanks for the community spirit, and for your response. Very motivating.
I have made a lot of progress understanding this, but not solved it yet.

[lildude]

I have made a lot of progress understanding this, but not solved it yet.

@davidbrown2324 the error:

C:/Ruby27-x64/lib/ruby/2.7.0/open3.rb:213:in `spawn': Exec format error - script/grammar-compiler (Errno::ENOEXEC)"

... indicates the script/grammar-compiler script is missing the execute permission. This has probably been lost because you're on Windows. I think you might have more success if you cloned the repo and ran the scripts etc from within WSL. Or, I think you can boot the container and change the permissions within it and manually run the script from within the container.

If you need any further help, please open a new discussion as your issue isn't really related to this PR.