Tldr: Syntax for linking to another tool's page

[oxguy3]

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'scutcommand, 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)

[mflint]

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 foo.md remains unchanged, but a new file foo.meta.yaml contains some metadata:

related: 
  - {platform: "common", command: "bar"} 
  - {platform: "linux", command: "baz"} 

Another benefit is that clients can choose to ignore this extra file, and wouldn't need to change their markdown parsers.

[agnivade]

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.

[mflint]

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 csvcut markdown contains `cut`, which is identified as the name of another command.

I like this! Copying the idea for my iOS client.

[waldyrious]

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 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. A process similar to #958 would be required to make sure none of the actively maintained clients are broken. Edit: on second thought, if the syntax does not overload any existing syntax (or standard markdown syntax used for something else), I'd expect clients to merely ignore the extra markup and simply render it as plain text, so that shouldn't be a problem. 🎉

[jeeftor]

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 [e-mail] 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.

[waldyrious]

Adding a reference to #2621 where I proposed the [[...]] syntax, which has precedence as internal links in similar lightweight markup languages, such as mediawiki.

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

[sbrl]

Great idea! I'm down for [[command]], as it appears to be a better alternative to graves.

I think a simple find and replaces should do the trick:

\b` -> [[
`\b -> ]]

Would that be sed -e 's/`\b/]]/g' -e 's/\b`/[[/g' with sed? I'm unsure as to whether sed supports the \b (word boundary) syntax.

[sbrl]

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.

[waldyrious]

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 perl instead. The tldr page for perl has an example for how to use it as a sed replacement (and of course its regex support is much more complete).

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.

[sbrl]

Ah, good thinking. We could use grep's PCRE-compatible mode to check for what would be replaced:

find . -type f -iname "*.md" | grep -iP '\b`[^`]+`\b

And thanks! I'll take a look at writing something up if I have time (or don't get distracted :P)

[sbrl]

As an update to this long-standing issue, informally we've been adding an extra description line like this:

```markdown

See also: command_a, command_b.

[waldyrious]

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!

[sbrl]

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.