tldr-pages / tldr-lint Goto Github PK

Do not allow markdown links as they do not display properly in the command line. This is in response to a review that I received.

tldr-lint rejects all example descriptions that start with a verb ending in e.g. as:

This causes the (infinitive) example description Antialias an image...: to be incorrectly rejected.

See tldr-pages/tldr#12198 (comment)

Right now we do have some platforms for which we document the pages, but if you would like, you could easily misspell the directory when creating a new page e.g. tldr-pages/tldr#11107. Maybe we could add an error if the page isn’t inside a folder in the list of supported platforms (android, common, linux, osx, sunos and windows)

This commit was accepted by the bot even though there was a breaking issue at line 8: A curly parentheses in an example wasn't closed properly.
Such an issue is hard to notice, so it would be nice if your neat build bot could report that as well.

Ref. tldr-pages/tldr#12195

Afaik we discourage this. We could also add this to our style-guide.

The linter should allow, and enforce, the correct punctuation for all languages. For example, Hindi (pages.hi) seems to use । as period character. In that case, the linter should require that sentences in the page description end with that character.

TODO: add Chinese info

Example:

command {{path/to/directory1}} {{path/to/directory2}}

Suggest join these placeholders (but don't affect error status because some commands may require just N arguments explicitly):

command {{path/to/directory1 path/to/directory2 ...}}

I seem to have come across a bug, where the linter reported an error in line 4, but it actually was in line 5. See the original lint report and my response here.

As discussed in tldr-pages/tldr#5510 (comment), we should use > More information: N/A for pages which have no suitable online documentation to explicitly mention that. This would however need a slight adjustment of tldr-lint, since it expects a <...> after More information:.

As per https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md#special-cases

Checkout this comment please from MELPA maintainers.

I had made a typo, and luckily it was found, but I figure this could be done by the automated validation check.

More information: hhttps://flameshot.js.org/.
More information: https://flameshot.js.org.

@sbrl tagging you since you were part of the approval process for that PR.

See this discussion for context.

Currently, when a page has a syntax error, tldr-lint prints the line number, but not the filename, which isn't very helpful 😄

$ tldrl . |& grep -vE 'TLDR015|TLDR104|TLDR004|TLDR005'
Error: Parse error on line 16:
...getprop`- 查看进程列表- 重置所有运行时权限为它们的默认值:
-------------------^
common/case.md:3: TLDR003 Descriptions should start with a capital letter
common/code.md:26: TLDR002 A single space should precede a sentence
common/gpg-zip.md:17: TLDR008 File should contain no trailing whitespace
...

Hey Ruben,
It's technically not open source without a license outlining contributors' and users' rights.

Cheers

Markdown files depend on trailing whitespace to add a line break without creating a new paragraph.

Due to our .editorconfig and TLDR008, we don't have 2 spaces between the description and more information link. This makes websites and other Markdown renderers render them on the same line.

For example, this issue occurs when viewing files on GitHub and on tldr.ostera.io.

I think TLDR008 should be replaced with a similar rule that disallows trailing whitespace on all lines except the page description.
Following this, our .editorconfig should include the rule:

[*.{markdown,md}]
trim_trailing_whitespace = false

Actual

Expected

Inspired by this PR: https://github.com/tldr-pages/tldr/pull/12617/files

Now that we've got #12 merged, it would be great if we could push a new version to npm.

We may also want to consider:

• Updating dependencies
• Updating the version in package.json and package-lock.json
• Pushing a(nother) new tag to this git repo

/cc @rubenvereecken, who was the last one to push a new version to npm.

Some rules are defined and implemented here that are generic and can be handled already by EditorConfig.
We have an .editorconfig file defined in tldr-pages/tldr.

I think we can reduce the code surface by using something that enforces EditorConfig instead.
This means less code to maintain, while having access to more rules.

Solutions

Prettier

I think the best way would be to delegate some rules to Prettier.
It documents that we can read an .editorconfig file which can use it to override rules. (More Info)

This would cover:

• TLDR010
• TLDR012

Prettier doesn't support the other properties that would help out yet, though:

• insert_final_newline for TLDR009

GitHub Actions

This one would be out of scope for this repository, but we could just scrap those rules and use a GitHub Action.

setup-editorconfig-checker

setup-editorconfig-checker might be good, and it uses editorconfig-checker which is still maintained.

EditorConfig-Action

EditorConfig-Action wins by star count, but this just uses jedmao/eclint under the hood, which is an archived and unmaintained project.

EditorConfig JavaScript Core

Alternatively, we could use EditorConfig JavaScript Core to parse the .editorconfig file, and apply the rule from there instead. That would defeat the point, as we'd still have to implement ourselves anyway, though. 🤔

I have already opened a issue for the TLDR main repo: tldr-pages/tldr#11068, but I can imagine we maybe want to have a check in the linter itself if the user isn't introducing a reference to a non-existing TLDR-page.

Running tldr cgroups -p linux results in:

- Show the tldr page for `cgclassify`:
    tldr cgclassify

But running tldr cgclassify -p linux results in:

This page doesn't exist yet!
Submit new pages here: https://github.com/tldr-pages/tldr

Right now this is the status per language:

11 missing TLDR Pages in missing-tldr.md.
188 missing TLDR Pages in missing-tldr-hi.md.
198 missing TLDR Pages in missing-tldr-ne.md.
186 missing TLDR Pages in missing-tldr-ta.md.
0 missing TLDR Pages in missing-tldr-cs.md.
197 missing TLDR Pages in missing-tldr-bs.md.
198 missing TLDR Pages in missing-tldr-pt_PT.md.
199 missing TLDR Pages in missing-tldr-uk.md.
190 missing TLDR Pages in missing-tldr-sv.md.
198 missing TLDR Pages in missing-tldr-th.md.
166 missing TLDR Pages in missing-tldr-es.md.
185 missing TLDR Pages in missing-tldr-tr.md.
160 missing TLDR Pages in missing-tldr-de.md.
0 missing TLDR Pages in missing-tldr-uz.md.
161 missing TLDR Pages in missing-tldr-fr.md.
0 missing TLDR Pages in missing-tldr-fa.md.
180 missing TLDR Pages in missing-tldr-pl.md.
183 missing TLDR Pages in missing-tldr-nl.md.
199 missing TLDR Pages in missing-tldr-da.md.
187 missing TLDR Pages in missing-tldr-ja.md.
0 missing TLDR Pages in missing-tldr-ro.md.
177 missing TLDR Pages in missing-tldr-id.md.
145 missing TLDR Pages in missing-tldr-pt_BR.md.
163 missing TLDR Pages in missing-tldr-ko.md.
200 missing TLDR Pages in missing-tldr-lo.md.
183 missing TLDR Pages in missing-tldr-ru.md.
153 missing TLDR Pages in missing-tldr-it.md.
182 missing TLDR Pages in missing-tldr-zh_TW.md.
0 missing TLDR Pages in missing-tldr-sh.md.
196 missing TLDR Pages in missing-tldr-ca.md.
198 missing TLDR Pages in missing-tldr-ar.md.
0 missing TLDR Pages in missing-tldr-sr.md.
196 missing TLDR Pages in missing-tldr-ml.md.
148 missing TLDR Pages in missing-tldr-zh.md.
0 missing TLDR Pages in missing-tldr-bn.md.
195 missing TLDR Pages in missing-tldr-no.md.

As you can see, there are only 7 languages that don't have any non-existing links.

(Issue originally included as a TODO in the README.)

In other words, throw an error if after a command description there is a line which text is equal to ``

I'm not sure this will necessarily be true in 100% of the cases, but perhaps if we equate hyphens to spaces (e.g. git-rebase.md → git rebase), it might be enough.

(Issue originally included as a TODO in the README.)

There are some pages in other languages that aren’t available in English. Maybe we need a (warning?) check if the English page exists before adding it to a different language.

To be complete; right now there are:

• 8 pages in linux in different language(s) that aren’t available in English.
• 4 pages in osx in different language(s) that aren’t available in English.
• 1 page in windows in different language(s) that aren’t in English.

I'm creating this issue to track (more visibly) a TODO comment that was added to the GitHub Actions specification:

Has anyone thought of adding some nice colors to the output of tldr-lint (at least when stdout/stderr is a terminal)?

It would make using it a lot easier, IMO.

This is regarding the discussion started here.

I decided to create an issue here on the linter repo just to keep track.

We've never formally tested that this warning is issued, and was only informally tested by the CI issuing it on a separate test case. #131 removes the informal testing, and we should add a proper formal test to ensure behavior / prevent regressions.

Test structure would probably be that within jest, we do jest.spyOn(console, 'warn') and then within the test do expect(console.error).toHaveBeenCalledTimes(1) and also testing what was passed into the spyed on console.warn (I don't know how to off-hand).

This character is visually the same as hyphen minus (‐, code point U+002D), so it's very hard to catch for humans.

Multiline fenced code blocks in input incorrectly report TLDR103. The attached example file returns the following result:

Error: Parse error on line 10:
... [f]iles:```bash`tar cf {{{target.tar
--------------------^
Expecting 'NEWLINE', 'TEXT', 'DASH', 'BACKTICK', got 'COMMAND_TEXT'
specs/pages/passing/fenced-code-block.md:8: TLDR103 Command example is missing its closing backtick

Note that the language spec (in this case bash) is followed by a backtick in the output but not in the original input. The parser and lexer (and other places in the lexer) seem to assume that all examples will fit on one line. While that's an understandable goal for tldr, it just doesn't fit all situations. For example tldr-pages/tldr#6868 includes examples of program input, not just program execution.

Expected behavior: Multiline fenced code blocks should be handled as such. The three backticks should be treated as opening and closing markers, not as adjacent, incomplete inline code blocks.

fenced-code-block.md

Why don't we commit package-log.json as almost all Node.js/npm projects universally do?

    $ npm install
    npm WARN deprecated [email protected]: Package no longer supported. Contact [email protected] for more info.
    npm WARN deprecated [email protected]: Package no longer supported. Contact [email protected] for more info.
--> npm notice created a lockfile as package-lock.json. You should commit this file.
    npm WARN notsup Unsupported engine for [email protected]: wanted: {"node":"^10 || ^12 || ^14"} (current: {"node":"15.4.0","npm":"6.14.8"})
    npm WARN notsup Not compatible with your version of node/npm: [email protected]

    added 130 packages from 142 contributors and audited 130 packages in 3.359s

    7 packages are looking for funding
      run `npm fund` for details

    found 0 vulnerabilities

Quoting from https://docs.npmjs.com/cli/v7/configuring-npm/package-lock-json:

This file is intended to be committed into source repositories, and serves various purposes:

• Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.

• Provide a facility for users to "time-travel" to previous states of node_modules without having to commit the directory itself.

• To facilitate greater visibility of tree changes through readable source control diffs.

• And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.

I'm not sure if this is a new behavior introduced with the upgrade of the Stale action from v3 to to v8 (done by @kbdharun in #245), or if it had always been the case since its introduction (done by @owenvoke in #29), but we need to reconfigure the Stale action so that it doesn't close issues simply because they are stale.

The current behavior is especially bad because the stale-adding action is not accompanied by a comment, so even people watching this repo or the specific issues don't get a notification (I don't think I got one).

In fact, maybe it shouldn't even close PRs that are stale, but simply remind people of them.

Affected issues, which have recently been closed by stale bot (and need to be reopened):

• #56
• #76
• #77
• #83
• #135
• #197
• #211
• #210 (already reopened)
• #93 (already reopened)

To keep the pages up-to-date, we could introduce an linter error if the link in “More information” isn’t working/reachable.

I found out at least one page where the filename doesn’t match the command on line 1;
https://github.com/tldr-pages/tldr/blob/main/pages.de/common/aw-backup.md - aws-backup.md

Maybe we can introduce a new linter error to check this.

To be clear, we could check if there is a space after the opening backtick or a space before the closing backtick. I don't think it has any effect on a command on any platform.

I fixed some of these pages on tldr-pages/tldr#11850.

Rules TLDR003 "Descriptions should start with a capital letter" and TLDR015 "Example descriptions should start with a capital letter" need to be extended to allow characters native to other languages. I've started compiling a list below. I'll be updating this list.

I've taken this list from https://github.com/sindresorhus/transliterate/blob/7c6ff0f9127a095d51689605f15a5091cb527153/replacements.js.

German allowed start characters:

• ẞ
• Ä
• Ö
• Ü

Russion allowed start characters:

• А
• Б
• В
• Г
• Д
• Е
• Ж
• З
• И
• Й
• К
• Л
• М
• Н
• О
• П
• Р
• С
• Т
• У
• Ф
• Х
• Ц
• Ч
• Ш
• Щ
• Ъ
• Ы
• Ь
• Э
• Ю
• Я
• Ё