Add links to the tools' homepages/websites

[Jab2870]

Firstly, great tool. Thanks for creating it.

Some tools are pretty obsucure. In my case it was x_x. I came accross it by acident but I'm glad I did. The description caught my interest but searching for the repo wasn't as easy as a websearch.

It would be very helpful in this case, and I am sure others, if the pages included a link to a repo or a project page.

[agnivade]

Thanks, I think this was brought before sometime in the past. I am not against this. But this requires a change in the page format, which needs to be discussed and approved and implemented by all clients. A non-trivial amount of work.

[waldyrious]

This had originally been proposed in the discussion of the (otherwise unrelated) #934. Thanks for opening an issue -- now we can track this properly, as a sub-item of #1082.

[sbrl]

Do you have some suggested syntax, @Jab2870? Ideally, it should be something that doesn't break existing clients, feels like markdown, and looks good even if not supported by a particular client.

[Jab2870]

Well, a link in MarkDown is this:

[Link Text](URL)

So that would probably be a starting point.

Perhaps we could have a section called relevant links?

## Relevant Links

* [Github](https://github.com/tldr-pages/tldr/)
* [Project Page](https://tldr.sh/)

Potentially a more future proof solution would be adding YAML headers to the files. This would mean that clients would need to be updated but would have the advantage of allowing us to add a lot more "meta" information to the pages. Potentially things like date created, date modified, a list of authors, original manpage, etc, although that is probably out of scope for this issue. Probably more relevant for #1082.

[waldyrious]

Using standard markdown syntax for links seems like the sensible choice to me as well.

I like the idea of a metadata section, but perhaps it would make more sense at the bottom of the pages, rather than at the beginning.

[Jab2870]

The only reason I say top is that there are other Markdown Syntaxes that use Yaml at the top Pandoc is the one I am most familier with although I think R Markdown does this as well.

[waldyrious]

I see, thanks for the context. I was thinking at the bottom so that pages to ensure pages could be consumed in plain text, with the most important information at the top (title, brief description and examples), and the auxiliary information at the bottom.

This would make pages more friendly to humans, while remaining just as parsable to machines as if the metadata were at the start.

[jedahan]

I'd advocate for links to just be part of the natural description up top, where we provide context.

A single link to a homepage feels in the spirit of tl;dr

ex:

# x_x

> View Excel and CSV files from the command-line. 
> [homepage](https://github.com/kristianperkins/x_x)

- View an XLSX or CSV file:

`x_x {{file.xlsx|file.csv}}`

- View an XLSX or CSV file, using the first row as table headers:

`x_x -h {{0}} {{file.xlsx|file.csv}}`

- View a CSV file with unconventional delimiters:

`x_x --delimiter={{';'}} --quotechar={{'|'}} {{file.csv}}`

"plaintext" is also nice

# x_x

> View Excel and CSV files from the command-line. 
> homepage: https://github.com/kristianperkins/x_x

- View an XLSX or CSV file:

or with commonmark autolinks

# x_x

> View Excel and CSV files from the command-line. 
> <https://github.com/kristianperkins/x_x>

- View an XLSX or CSV file:

[waldyrious]

Yes, I agree the main link of the project feels central enough to justify placing it at the top, as part of the main description (rather than inside a metadata block).

From the options you presented, I like the autolink one the best.

[sbrl]

Hrm. I link the autolink, but I feel like it doesn't give enough context as to what it's doing there. How about this:

> Homepage: <{{url_here}}>

[waldyrious]

Sure. I personally don't feel it's necessary, but explicit is always better than implicit, so I'm fine with having the label.

[Jab2870]

I personally think we should stick to Markdown links. Autolinks are great but this would make the repository CommonMark specific wouldn't it? I may be wrong but it appears that there is currently nothing in the repo that is outside the standard Markdown spec. I agree with @waldyrious that Explicit is better than implicit so I would prefer to go with

[Homepage]({{url_here}})

[waldyrious]

While I agree on principle, I don't think there's anything wrong with following CommonMark, since it's the only actively maintained and widely supported Markdown specification. Besides, the autolink syntax is cleaner to read in plain text mode than the inline link syntax.

That said, I do lament that we can't use the inline link in the actual title line (which would make the most semantic sense IMO), due to readability concerns. Like this:

# [x_x](https://github.com/kristianperkins/x_x)

> View Excel and CSV files from the command-line. 

- View an XLSX or CSV file:

I'm afraid that's not a viable option since it would make the title of the page hard to read in plain text mode.

An alternative to that could be the reference link form:

# [x_x][1]

> View Excel and CSV files from the command-line. 
> [1]: https://github.com/kristianperkins/x_x

- View an XLSX or CSV file:

But to be honest, I still prefer the autolink form:

# x_x

> View Excel and CSV files from the command-line. 
> Homepage: <https://github.com/kristianperkins/x_x>

- View an XLSX or CSV file:

[Jab2870]

Why wouldn't you consider pandoc or github flavors of markdown as active or widley supported? Just out of interest as I have just checked and both also support the autolink syntax.

Since the autolink syntax is more widley supported that I previously thought, I would agree that it is the nicest to read of the options.

Have we decided against a list of links?

* <{{Homepage}}>
* <{{Github repo}}>

[waldyrious]

Why wouldn't you consider pandoc or github flavors of markdown as active or widley supported? Just out of interest as I have just checked and both also support the autolink syntax.

Because they make no claim to be a generic standard that anyone can use, and are tuned to the specific needs of the projects they're part of. CommonMark, on the other hand, was created explicitly as a project to offer an unambiguous markdown specification fit for general use by any project.

Have we decided against a list of links?

I think additional links can go in a metadata section, which we'll likely add sooner or later in order to support the various kinds of metadata that can be associated with pages, as tracked in #1082.

I suggest we keep this issue focused on the main link, since we seem to be converging on extending the main description without additional changes to the page syntax, which makes implementing this change easier.

[Jab2870]

Fair enough. Is it now just a matter of going through and adding them? I would be very happy to contribute some time this evening to adding links if we are in agreement.

[waldyrious]

Let's wait for @sbrl and @agnivade to comment, since they had intervened above. Once we all agree on the format, yes, it's just a matter of someone rolling up the sleeves and making the changes to the pages :)

[agnivade]

Sure, I don't have any strong feelings regarding the specifics of the format. But I think having a prefix like homepage: will help clients parse that and display it nicely.

[jedahan]

More options, if we are okay with autolinks, that don't look awful with cat, but still are reasonably easy to parse by different clients

After title

# x_x 
<https://github.com/kristianperkins/x_x>

> View Excel and CSV files from the command-line. 

- View an XLSX or CSV file:

Title inline

# x_x <https://github.com/kristianperkins/x_x>

> View Excel and CSV files from the command-line. 

- View an XLSX or CSV file:

After Description

# x_x 

> View Excel and CSV files from the command-line. 

<https://github.com/kristianperkins/x_x>

- View an XLSX or CSV file:

Footer

# x_x 

> View Excel and CSV files from the command-line. 

- View an XLSX or CSV file:
...snip

<https://github.com/kristianperkins/x_x>

I feel like the footer reads the best with a simple cat, but I am very worried that these pages will become super long as people feel like they can stuff in all sorts of information at the end of the file. By putting it in the header, we add a ton of friction that makes it kinda impossible to add more than a single line. This feels like a good thing as I want these pages to be tl;dr, not a substitute for "everything you would want to know about x_x".

[Jab2870]

I definately prefer After Description or Footer. Although, I think as @agnivade has said, we should label them somehow.

Also, should we clarify the types of links we should including?

Off the top of my head:

• Project website
• Git repo

[agnivade]

We cannot do "after description", "after title" or "footer" without breaking the linter, and possibly other clients. Let us just go with a new line in sub-heading.

And the link should be the home page of the tool if it has one, else the git repo. In short, whatever helps the user to know more about the tool.

[jedahan]

~ dreams about PRs running a smoke test of tldr x_x on a bunch of clients, possibly with screenshots of their rendered output to see what actually breaks ~

[agnivade]

The linter will obviously break. So that is a bigger problem than the clients. If we are going to add the links in those sections, we need to change the linter first.

[sbrl]

Hey! All good points raised here - especially about CommonMark (I think it's a great idea to follow an explicit standard).

The linter is a problem because it's currently written in flex, and it's hard to maintain at the moment. I think there's discussion in some issue or other about potentially rewriting the linter to be more maintainable.

I could actually, in theory, rewrite it in C♯ with a lexer class I've written recently for University.

As for the formats, I'd personally prefer the 2nd description line. The "after description" one looks odd - as if it's a description of a command, but it isn't. "title inline" looks interesting, but I'd personally prefer to keep the title line as free as possible - adding the autolink clutters it I think. "after title" looks ok. I wouldn't mind that one at all. In fact, thinking about it, I might prefer that over the 2nd description line one.

[waldyrious]

I agree with @sbrl that it's best to keep the title line clean, so the "Title inline" (the only one of @jedahan's second batch of options that wouldn't break the lexer, as @agnivade mentioned) would be a no go from me.

If I understand correctly, among the options that can be introduced immediately (i.e. that don't break the lexer nor the clients), both @sbrl and @agnivade picked the hybrid I suggested between the "plaintext" and the "autolinks" options from @jedahan's original comment:

# x_x

> View Excel and CSV files from the command-line. 
> Homepage: <https://github.com/kristianperkins/x_x>.

- View an XLSX or CSV file:

There are two slight adaptations: "Homepage" is kept from the plaintext version, but capitalized; and a period was added to the end of the line. Both of these are currently required by the syntax checker, and IMO the line actually looks better that way, since it's consistent with the first line of the description.

So what do you guys say? Can we move forward with this one?

[agnivade]

SGTM.

[Jab2870]

Looks good to me.

[sbrl]

Yep! Looks ok to me. Let's do that 😺

[jedahan]

So should we all just start creating PRs for different pages?

[agnivade]

@waldyrious - any concerns before we move ahead ?

[waldyrious]

@agnivade just a small thing: Do we have a hard limit of two lines for the command description? If so, we probably will want to bump it to 3.

Also, I'd rather have this change done in bulk than one PR for each page. Or at least in batches. @Jab2870 did you have any plans regarding how to perform this mass edit, or were you also planning to do them one by one?

[agnivade]

: Do we have a hard limit of two lines for the command description?

Nope, I tested it.

[Jab2870]

I might be able to put some time into a script at the weekend that would search GitHub for the command name. If a match is found, add that. We could then manually update any that should point to a project page rather than the GitHub repo.

If there isn't a GitHub match, we probably wouldn't be able to anything

EDIT

Many things could go wrong with this though. I will give it a go but it might not work

[waldyrious]

I was thinking we could try one of the online manpage sites with the command name, since the URL is generally consistent and matches the command name. That would get us a long way for the most common commands. We can later manually replace the manpage links with more appropriate URLs in case the commands have dedicated webpages.

For commands that don't have manpages, usually the issue or PR that introduced the tldr page has a link to the project's home page (be it the github repository or an actual website).

[sbrl]

Tools like ffmpeg, 7z, ansible, weasyprint, etc. have their own websites, which I think we could point to. I'll put together a mass-changes PR for some of those.

[agnivade]

This is done now. Closing.