Closed waldyrious closed 10 months ago
Question: What we should do with pages like https://github.com/tldr-pages/tldr/blob/master/pages/linux/ksvgtopng5.md? This is an internal command/util from the KDE Plasma desktop and doesn't have a man page. Should we use the link to the git repository?
An updated version of the list was moved to #6062, since it was rather long.
I'm not sure if this was a good idea though...
Yeah, that's a crazily long list 😂
@marchersimon I'd open PRs fixing pages in batches of 10 or so, to reduce the PR count given these are simple changes.
@bl-ue what about @waldyrious's suggestion?
(Note: This should be done with a separate PR for each page (or at best, multi-page PRs for related sets of pages, such as all the subcommands of a given command), so that discussion about which links to use for some pages won't block the straightforward changes to the other pages.)
I'm fine with that, the only thing I'm not sure about of is opening a bunch of PRs that each add one line to one file...I'm not sure if that's a great idea. But if that's okay with @waldyrious it's okay with me.
If multiple PRs are adding links to the same site, or add links to pages that are related to each other, then yeah, it makes more sense to group those changes into a single PR.
Other than that, I don't see any problems with having lots of small PRs that are indeed unrelated to each other. Simple PRs are easy to review, and allow a fast turnaround, which is good both for maintainers and contributors alike.
For the GNU coreutils (cd, mv, ...) should we add the link to the respective page on gnu.org? Example https://www.gnu.org/software/coreutils/manual/html_node/mv-invocation.html for mv. I don't really see another way...
Yes definitely. Those pages are very informative.
Should we also change the links of the current coreutils? (chmod, dd, mkdir, touch, b2sum, cat, basename
)
@marchersimon It's certainly helpful but then again you could just look it up in the man page.
If they're man7.org ones I think we should move them to the gnu pages. I like those ones better; they're official and informative (and a contrast to man7.org that's all over lots of pages)
@marchersimon that's a really nice table you've made up there, but there's one problem with that you couldn't have avoided: in French, a special thin, unbreakable space is used before most punctution including colons, but it's hard (if not impossible) to copy the French space from the GitHub UI, so you might need to get it manually.
It's code 160
(0xa0
, →
), and the best way to get it is to open your browser's JavaScript console and enter String.fromCharCode(0xa0)
, and then copy the resulting character within the quotes.
@bl-ue could I also add a note that it should be copied from another french page?
Certainly @marchersimon please feel free and you don't need to ask 👍🏻
@marchersimon try this for changing/adding links: https://gist.github.com/bl-ue/5b52c9f80dd21074c0633a2bcdeb01fb
Usage:
export TLDR_ROOT="path/to/tldr_directory" # run this once per terminal session
python3 set_more_info_link.py -p common/chmod "https://url......." # omit the .md extension
I made it because I couldn't take the tedious and highly error-prone procedure of manully adding them one more second 😝
This is really cool, thanks!
Hey @marchersimon can you wait for a second before updating that comment? I'm trying to add some stuff 🙂
Oh, sorry, sure.
Did you remove the sections or did I mess something up? Because I can't revert it
You removed the sections (according to GH). We both hit "update comment" at the exact same time :D
I like it better without the letter grouping, so will you please leave it all open? It's easier to find items, I think.
Okay, sure.
@marchersimon just to be clear, when I said
If multiple PRs are adding links to the same site (...) it makes more sense to group those changes into a single PR.
...I had in mind precisely a case such as the GNU coreutils pages, which all follow the same pattern an link to the same base site. In that case, rather than opening one PR per page, it would be OK to have all changes in a single PR (even if you keep the changes to each page on its own commit in the PR branch). Can you do so for the remaining ones, please? And apply a similar logic to the updates to the other pages as well.
Oh, I thought all coreutils pages would be a bit too much for one PR. Sorry for the mess, then.
Well it would just be another really large PR, but we've had plenty of those :-)
Related: #5111
In that issue we discussed enforcing more information links. Here, as there, I think it would be good to enforce them.
@waldyrious what are your thoughts with the discussion in #5111 in mind?
Thanks for cross-linking the threads! I believe you may be referring to the following comments (please correct me if not):
@owenvoke:
I have nothing against adding links from non-official sources (I'm all for adding more links that are useful). I just feel like it might lead to adding links that aren't particularly useful just because that's the only thing available.
@schneiderl
I don't think I like forcing to have a link for every page. In some cases, there is no interesting link to be put on the description. Also, in some cases, we might be just repeating ourselves (see #3041).
@sbrl:
Adding links is nice, but it's not suitable for all commands. Take arch or nproc for example. I think this is best left out of the linter.
The conversation in #3041 which @schneiderl linked to (and which I've shamefully ended up never responding to until now (though in my defense GitHub started deleting notifications older than 6 months a while ago 😢)) also has some points against adding links when they may be considered redundant, mostly by @agnivade.
In all these cases, I believe what I suggested above can address those concerns:
Pages of projects that don't have a dedicated web page should either link to their parent project's page, or we should come up with a way to explicitly indicate that they don't have a homepage.
I realize could have been more explicit there, but I didn't want to make the opening comment too verbose. What I had in mind was either a metadata file like what @srsudar suggested for the aliases in #5299, or a special markup that we could add to the pages themselves. Something like this, for example:
# foobar
> Description bla bla bla.
> More information: <N/A>.
Yes, those exactly were the comments I was thinking.
I like the idea of using N/A
—I think it would solve all the problems without requiring a spec revision / client update.
Yes, those exactly were the comments I was thinking.
Next time I'd appreciate if you saved me the duplicated work, then 😅
Yeah, finding a way to explicitly indicate that there isn't a suitable web page is a good idea. We can't use the angle-brackets (<N/A>
) though, because in the CommonMark spec that's the syntax for autolinks. Perhaps simply dropping the angle brackets and doing something like this would be better:
> More information: N/A.
What about alias pages #5299? Should we add links to them?
In that issue I wrote
with the link intentionally omitted.
But now I'm not sure that's necessary.
If we didn't, that would cause problems with tldr-lint
as soon as we make them required. But we also can't use <N/A>
, since that would be wrong.
I'd say we can adjust the logic of the linter to
N/A
) is present in a way that ignores the alias pages (which should be easily identifiable if the point above is implemented).👍🏻. What if an alias has it's own particular page which documents the fact that it is an alias and links to the source command's page?
I'm inclined to require links on all alias pages, and ensure they are identical to those of the source pages.
I don't understand what you mean. Are you suggesting to use the "More information" field in alias pages to link to the original pages, rather than the example format that was proposed in #5299?
Sorry, that wasn't very coherent 😛
No, I was that an alias page should (must) have the exact same link as the source page. For example, if abc.md
has a link to https://abc.com/
, then def.md
, which is an alias page to abc.md
, should have a link https://abc.com/
.
That seems redundant and even noisy IMO. The alias page should be as short as possible and contain only the information needed to allow the user to find the correct page. In fact, I'm even thinking that we might want to use a more compact format, such as
# foo
> Alias of `bar`.
(though this format is something to be discussed at #5299, not here).
About the link: I agree. About the compact format: so zero examples? I'm not sure the linter would like that.
If the linter will have an exception for alias pages so it won't require a link in those cases, then it can just as well do the same for requiring examples.
Hi I was trying to add pinky.md but then I found that it was already included from Pull Request #2284 and commit #e4c03937386. We may tick the case above, don't we?
Oh no, I nevermind this issue is to add links. I'll do it right now ^^
Should I move my list to a seperate issue, so it's possible to scroll and discuss here and keep track of pages in the new issue?
@marchersimon perhaps a good idea, since it is quite long haha
Have this as the meta discussion issue, and a new one as a tracking issue.
Done. I left out finished pages to avoid getting a notification for every PR which was linked in the list.
Should I also close this issue or is there something left to discuss?
Since #2649, tldr pages support adding a link to the tool's homepage, and substantial efforts to backfill links into existing pages have been made, but many are still lacking it.
We should ensure that all pages have a link that people can follow to learn more about the tool and explore more comprehensive documentation. Pages of projects that don't have a dedicated web page should either link to their parent project's page, or we should come up with a way to explicitly indicate that they don't have a homepage.
(Note: This should be done with a separate PR for each page (or at best, multi-page PRs for related sets of pages, such as all the subcommands of a given command), so that discussion about which links to use for some pages won't block the straightforward changes to the other pages.)
Once that work is completed, we should add a check to tldr-lint to make this field required, thus ensuring that new pages won't regress our coverage in that regard (see #5046 for examples of link-related checks that were incorporated into tldr-lint). We should also change the template for a page in
CONTRIBUTING.md
, the style guide, and other places where that may be relevant.