-
-
Notifications
You must be signed in to change notification settings - Fork 4.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Syntax for linking to another tool's page #784
Comments
I'm also wary about making changes to the agreed format which may not be friendly to clients which display the raw markdown as plain text. Alternatively, we could supply an extra file for metadata. So
Another benefit is that clients can choose to ignore this extra file, and wouldn't need to change their markdown parsers. |
I guess the point here is the "direct" linking of pages which only makes sense in web clients. For command line clients like the node-client, there is already a see-also section. |
For any causal readers: node-client looks for command-names in code blocks. So the I like this! Copying the idea for my iOS client. |
I think we can come up with a format that displays well in raw markdown, both because that way the simple clients (and directly reading the pages as plain text) would also benefit from the additional info. Of course, that would require adaptation from the clients that do parse the markdown. |
I'm a fan of his idea as well. Man pages end with a see also list of similar commands.
…Sent from my iPhone
On May 1, 2017, at 6:27 AM, Waldir Pimenta ***@***.***> wrote:
I'm also wary about making changes to the agreed format which may not be friendly to clients which display the raw markdown as plain text.
I think we can come up with a format that displays well in raw markdown, both because that way the simple clients (and directly opening the pages) would also benefit from the additional info, and because it ensures that related content is maintained in the same place, which is easier to keep track of (btw, following this latter argument also means we might want to take a look at fixing our oldest still-open issue, #190).
Of course, that would require adaptation from the clients that do parse the markdown, so a process similar to #958 would be required to make sure none of the actively maintained clients are broken.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.
|
Adding a reference to #2621 where I proposed the Given the edit I made to my previous comment, I'd say we could actually move forward with this one without having too coordinate with the clients. Anyone up for doing the changes? :D |
Great idea! I'm down for I think a simple find and replaces should do the trick:
Would that be |
Also, we really need a specification document. Is there a master list of everywhere we've discussed things that should go in the client spec? It's the end of the University semester, so I might be able to draft something up. |
I'm afraid such a bulk replacement method might get us a lot of false positives, but sure, let's try and see. As for the tool to use, I would suggest trying Regarding the page spec, IIRC the main discussions have happened in #958 and #1065, plus those linked from #1082, and generally those under the syntax label. |
Ah, good thinking. We could use
And thanks! I'll take a look at writing something up if I have time (or don't get distracted :P) |
As an update to this long-standing issue, informally we've been adding an extra description line like this: > See also: `command_a`, `command_b`. |
Thanks for the update and bump, @sbrl. I'll also add that we do have more detailed page formatting guidelines now, as well as a client spec, so we could simply adjust those two to support the proposed linking syntax (assuming there's no objection to it) and then start converting the pages! |
Yeah, @waldyrious! I think the client spec doesn't need updating though, because all it states is that clients must support CommonMark, and the syntax above is CommonMark-compliant. |
Very often, it is necessary to refer to one tool from another tool's tldr page. For example, the csvcut.md page has a reference to unix's cut tool (
Like Unix's
cutcommand, but for tabular data.
). I've just proposed that tldr pages could have a 'see also' section (in issue #785); if that is implemented, it would result in a lot more references to other tools.Currently, the de facto standard for mentioning the name of another tool has been surrounding the name with graves. This works, but it'd be really great if there were a way to unambiguously refer to the name of another tool, so that TLDR clients could provide some easy way to jump to that other page (i.e. web clients could easily insert hyperlinks).
Here's what I have in mind: If you want to talk about a command called "foo", you write
[foo]
. TLDR clients will automatically determine which OS version of "foo" should be linked. (minor note: TLDR clients would also need to take into consideration that there might not be a tldr page for "foo" -- it's conceivable that you'd want to mention "foo" even if there's not a page for "foo" yet)If you want to talk about a specific version of "foo", you write
[linux/bar]
or[common/bar]
or whatever. This is very useful if there's a platform-specific tool AND a cross-platform tool of the same name. For example, in PR #764, we couldn't really come up with an easy way for the OS X page for base64 to reference the existence of the GNU coreutils cross-platform base64 tool. Having links like this would allow a mention of that other tool, and solve the issue of confusion there.The one big issue with the syntax I've described is that it's incompatible with Markdown. Perhaps a better syntax would be
<tldr://foo>
for referencing any version, or<tldr://foo/linux>
or<tldr://foo/common>
or whatever for referencing specific versions. This is a valid link destination in Markdown syntax. (I don't think link title syntax -- i.e.[foo](tldr://bar)
-- is a good idea, because there's no easy way for CLI clients to display both the link title and the URL)The text was updated successfully, but these errors were encountered: