Closed waldyrious closed 1 year ago
navarroaxel
commented
3 years 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?
bl-ue
commented
3 years ago 
marchersimon
commented
3 years ago An updated version of the list was moved to #6062, since it was rather long.
marchersimon
commented
3 years ago I'm not sure if this was a good idea though...
bl-ue
commented
3 years ago 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.
marchersimon
commented
3 years ago @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.)
bl-ue
commented
3 years ago 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.
waldyrious
commented
3 years ago 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.
tomadojuice
commented
3 years ago 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...
bl-ue
commented
3 years ago Yes definitely. Those pages are very informative.
marchersimon
commented
3 years ago Should we also change the links of the current coreutils? (chmod, dd, mkdir, touch, b2sum, cat, basename)
tomadojuice
commented
3 years ago @marchersimon It's certainly helpful but then again you could just look it up in the man page.
bl-ue
commented
3 years ago 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)
bl-ue
commented
3 years ago @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.
marchersimon
commented
3 years ago @bl-ue could I also add a note that it should be copied from another french page?
bl-ue
commented
3 years ago Certainly @marchersimon please feel free and you don't need to ask 👍🏻
bl-ue
commented
3 years ago @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 extensionI made it because I couldn't take the tedious and highly error-prone procedure of manully adding them one more second 😝
marchersimon
commented
3 years ago This is really cool, thanks!
bl-ue
commented
3 years ago Hey @marchersimon can you wait for a second before updating that comment? I'm trying to add some stuff 🙂
marchersimon
commented
3 years ago Oh, sorry, sure.
marchersimon
commented
3 years ago Did you remove the sections or did I mess something up? Because I can't revert it
bl-ue
commented
3 years ago You removed the sections (according to GH). We both hit "update comment" at the exact same time :D
bl-ue
commented
3 years ago I like it better without the letter grouping, so will you please leave it all open? It's easier to find items, I think.
marchersimon
commented
3 years ago Okay, sure.
waldyrious
commented
3 years ago @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.
marchersimon
commented
3 years ago Oh, I thought all coreutils pages would be a bit too much for one PR. Sorry for the mess, then.
bl-ue
commented
3 years ago Well it would just be another really large PR, but we've had plenty of those :-)
bl-ue
commented
3 years ago 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?
waldyrious
commented
3 years ago 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.
waldyrious
commented
3 years ago Yes, those exactly were the comments I was thinking.
Next time I'd appreciate if you saved me the duplicated work, then 😅
sbrl
commented
3 years ago 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.
marchersimon
commented
3 years ago 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.
waldyrious
commented
3 years ago 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).bl-ue
commented
3 years ago 👍🏻. 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.
waldyrious
commented
3 years ago 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?
bl-ue
commented
3 years ago 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/.
waldyrious
commented
3 years ago 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).
bl-ue
commented
3 years ago About the link: I agree. About the compact format: so zero examples? I'm not sure the linter would like that.
waldyrious
commented
3 years ago 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.
patricedenis
commented
3 years ago 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 ^^
marchersimon
commented
3 years ago 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?
sbrl
commented
3 years ago @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.
marchersimon
commented
3 years ago Done. I left out finished pages to avoid getting a notification for every PR which was linked in the list.
marchersimon
commented
2 years ago 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.