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.
Jab2870
All 46 comments
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.
agnivade
on 13 Dec 2018
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.
waldyrious
on 13 Dec 2018
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.
sbrl
on 13 Dec 2018
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.
Jab2870
on 14 Dec 2018
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.
waldyrious
on 14 Dec 2018
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.
Jab2870
on 14 Dec 2018
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.
waldyrious
on 14 Dec 2018
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:
jedahan
on 14 Dec 2018
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.
waldyrious
on 14 Dec 2018
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}}>
Sure. I personally don't feel it's necessary, but explicit is always better than implicit, so I'm fine with having the label.
waldyrious
on 16 Dec 2018
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}})
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:
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}}>
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.
waldyrious
on 17 Dec 2018
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.
Jab2870
on 17 Dec 2018
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 :)
waldyrious
on 17 Dec 2018
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.
agnivade
on 17 Dec 2018
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".
jedahan
on 17 Dec 2018
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
Jab2870
on 17 Dec 2018
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.
agnivade
on 17 Dec 2018
~ 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 ~
jedahan
on 17 Dec 2018
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.
agnivade
on 17 Dec 2018
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.
sbrl
on 17 Dec 2018
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?
waldyrious
on 18 Dec 2018
SGTM.
agnivade
on 18 Dec 2018
Looks good to me.
Jab2870
on 18 Dec 2018
Yep! Looks ok to me. Let's do that :smiley_cat:
sbrl
on 18 Dec 2018
So should we all just start creating PRs for different pages?
jedahan
on 18 Dec 2018
@waldyrious - any concerns before we move ahead ?
agnivade
on 18 Dec 2018
@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?
waldyrious
on 18 Dec 2018
: Do we have a hard limit of two lines for the command description?
Nope, I tested it.
agnivade
on 18 Dec 2018
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
Jab2870
on 19 Dec 2018
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).
waldyrious
on 19 Dec 2018
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.
sbrl
on 20 Dec 2018
Oops! I've encountered an issue. I pushed to master by accident, reverted it and created a branch instead - but now I can't create a PR 'cause GitHub claims there aren't any changes - when git diff clearly shows otherwise......
sbrl
on 20 Dec 2018
It is because you haven't rebased master on the branch. If I go here, it says the branch is 1 commit behind master.
agnivade
on 20 Dec 2018
Thanks, @agnivade! I've rebased master on top of the branch, but I'm still getting the same error :-/
sbrl
on 20 Dec 2018
@sbrl first of all, I would have actually removed the new commit to master rather than add a reversal commit, considering that no commits have been added on top of the first one. Would you guys object to that? We're can still do it.
Anyway, the confusion seems to be due to the following sequence, if I'm understanding things correctly:
* revert B [master] * revert B [master]
| |
--> * B [master] --> * B --> * B [new-branch]
| | |
* A [master] * A * A * A
At this point, new-branch was indeed one commit behind master, as @agnivade pointed out. However, rebasing master atop new-branch wouldn't do anything, since it is already on top of it! I'll assume you guys meant the opposite, i.e. rebasing new-branch on top of master. That, however, will (and did) misfire, since git detects that commit B from new-branch is already on master, so instead of the following:
* B [new-branch]
|
* revert B [master]
|
* B
|
* A
...it simply omits the B commit, resulting in this:
* revert B [master] [new-branch]
|
* B
|
* A
That is, new-branch is indeed on top of master, but it has zero additional commits (that aren't already in master), so it coincides with master's tip (that's the current situation at the time I'm writing this.
From here, to actually re-add commit B atop the "revert B" commit, like so, you need to cherry-pick commit B (while on new-branch). Hopefully git won't consider it a duplicate this time, but I'm not 100% sure it won't. If all goes well, this would then result in the following graph:
* B2 [new-branch]
|
* revert B [master]
|
* B
|
* A
But I think that makes the situation even worse, as we now would have 3 commits for the same change. I'd much rather do the following instead, as I mentioned at the start of this comment:
* B [new-branch]
|
* A [master]
To do so, the fastest way (albeit not the cleanest) is the following:
# Leave whatever branch is currently checked out, and go to "detached HEAD" mode
git checkout HEAD
# Move master to its previous location
git branch -f master <commit A>
# Move new-branch to the first commit that went to master by mistake
git branch -f new-branch <commit B>
# Push the new branch heads upstream
# (careful not to overwrite other commits that may have been made to master!)
git checkout master && git push -f
git checkout new-branch && git push -f
If you guys are OK with that, I can take care of it.
waldyrious
on 20 Dec 2018
Update: re-writing master is no longer a clean option :( other commits have been added on top. So now the cherry-pick is the way to go, I suppose.
waldyrious
on 20 Dec 2018
Can't we delete the 2 commits and force push ?
agnivade
on 20 Dec 2018
We can, of course. It's just even more of a kludge now than it would be if we did it before any commits had been added on top. For example, the commit that integrated the changes in #2657 will have a different hash, and github may start showing that PR as closed without being merged. Not that this matters a lot since that's kind of a failure on github's side, and we can always leave a comment there to clarify things.
I would have no opposition to doing that anyway, but considering that we do have other wrinkles in our git history, I wouldn't insist on this point. I'm fine either way.
waldyrious
on 20 Dec 2018
I tried to force-push, but it wouldn't let me - claiming that master is a 'protected branch'. I was unsure as to whether I should disable that temporarily.
Thanks for the advice on cherry picking - I ended up doing that and opening #2660
sbrl
on 20 Dec 2018
Yes, force pushing needs to make master unprotected. Let's go with cherry picking.
agnivade
on 20 Dec 2018
It's too bad, there should be a way to protect master against direct commits too, not just forced pushes.
waldyrious
on 20 Dec 2018
This is done now. Closing.
agnivade
on 26 Mar 2019
Related issues
waldyrious
路
4Comments
kelthuzadx
路
3Comments
pascaliske
路
3Comments
mikerouxfr
路
3Comments
TobiasRoland
路
3Comments
Most helpful comment
Nope, I tested it.