Epic: Add links to all existing pages #5510
Labels
help wanted
You can help make tldr-pages better!
mass changes
Changes that affect multiple pages.
syntax
Issues related to the content and markup of the pages.
Comments
waldyrious
added
syntax
|
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? |
This was referenced Mar 26, 2021
|
An updated version of the list was moved to #6062, since it was rather long. The old list:
GNU coreutils
* The French translation cantains a thin unbreaking space, which can't be copied from the Github UI. The easiest way would be to copy it from another French page, like |
|
I'm not sure if this was a good idea though... |
This was referenced Mar 29, 2021
Merged
|
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?
|
This was referenced Mar 29, 2021
|
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? ( |
|
@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) |
|
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 ( > More information: N/A. |
Merged
|
What about alias pages #5299? Should we add links to them? In that issue I wrote
But now I'm not sure that's necessary. |
|
If we didn't, that would cause problems with |
|
I'd say we can adjust the logic of the linter to
|
|
👍🏻. 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 |
|
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. |
|
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. |
6 tasks
|
Hi Oh no, I nevermind this issue is to add links. |
|
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. |
6 tasks
2 tasks
5 tasks
|
Should I also close this issue or is there something left to discuss? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.The text was updated successfully, but these errors were encountered: