Sorry, your platform is not supported yet (linux) about tldr

[rprieto]

Thanks, that's the next thing to tackle.

Linux is just "switched off" in code for now, but what's really missing is some actual "pages" (the arguments usually differ from OSX). I'll amend the README for now.

[diffalot]

i'm thinking through a structure i'd like to contribute to make supporting linux easier.

osx commands can differ from linux commands, but i find that the differences are random and few, rather than common. iirc, most of the differences come from the os-x preference for bsd tools over their gnu counterparts. so it might be good to have separate folders for those two as well as a common folder (the initial search path?)?.

this would require searching multiple paths from remote.js. @rprieto, would that affect performance for remote search and searching for commands that aren't in the index too much?

[andrewboerema]

I agree with @diffalot. As a linux and osx user, I find that the commands I use on a daily basis are the exact same. However, I usually use ubuntu, so I don't know if that will hold true across all flavors. I'm in favor of the common structure.

[rprieto]

If most commands are the same, I think you're right a common structure would save a lot of time / duplication. I guess we could either have

common
  |__ tar.md
osx
  |__ tar.md
linux
  |__ tar.md

or split sections within the Markdown documents themselves. This would add more Markdown parsing, which I was hoping to get away from though, to add more liberty in the "pages" content.

@diffalot for now it will definitely add some overhead making multiple requests, but eventually I think it would be nice to download bundled pages. For example a build process could create dist/tldr-pages.tar to be pushed to GitHub. The tldr command would then download the bundle on first request, and periodically check for updates based on the last etag. If we go down that route, resolving the relevant examples will be a local (and fast) activity.

[kud]

Sounds good to me.

[Tug]

How does one contribute to the documentation of a command today?
I guess you have to submit a pull request to this repository?
It could be nice to have a local repository (where you define your own doc) and from which you can publish to a central repo (a bit like npm). But let's keep in mind the KISS principle for now I think :)

[kud]

You fork the project, you create a .md of a command, you explain it, and you make a PR, yes.

[rprieto]

Yep that's about it!

@Tug that's a good idea for down the track. Someone else mentioned being able to install pages when you install a given program, ie. if you brew install foobar it could add short tldr pages on how to use it, alongside the full man pages. This would work well with local repos too, but I'm not sure yet how it cooperates with the upstream registry. Maybe there's something we can learn from npm :)

Anyway for the time being I think you're right, PRs should do the job fine!

[kud]

I was on bropages but I prefer to contribute to a nodejs project so I'm doing all what I can to make some PRs ;)

By the way, why this weird name? ain't easy to remember.

[rprieto]

Thanks @kud !
The name was kind of tongue-in-cheek for the fact that a lot of man pages are a little too long; didn't read.

[Tug]

@kud yeap. Cool thing with Github is you can edit a Markdown file directly from you browser, it will fork the project and make a pull request for you.

So Gihub seems to be the perfect platform for this project, no need to have a server with CouchDB intalled (npm backend), a web frontend, etc.

[rprieto]

Definitely agree, Github has quite a low barrier to entry, but still enough to help avoid anonymous spammy/trolling submissions.

And so back on topic, I'd love to hear the opinion of cross-platform folks about going osx, linux and common. My guess is then most examples would live in common until someone mentions otherwise.

[xfalcox]

The common infrastructure proposed it's the best, IMO.

First search at specific .md, and if not found search at common.

The overhead is minimal.
I'm hopping to contribute with some commands, as I tend to forget the syntax to easily 😄

[kud]

!

[rprieto]

@xfalcox from experience, do you think commands that differ will warrant their own files completely, or is it worth making both calls & trying to merge common examples with the OS-specific ones?

[kud]

We had some troubles with linux/macosx differences yes. We're all on macosx except our sysadmin and guess who does most of our system scripts? the sysadmin. And something, we've got illegal options or some stuff like that.

He's on debian (linux/gnu), we're on macosx (darwin, kind of bsd). So, yes, some commands ain't the same.

[xfalcox]

Following the KISS principle, we better have entirely different files for the few commands that will figure simple examples were the syntax isn't the same.

I'm assuming that tldr will contain simple and quick how to get somenthing done, and nothing to replace man pages.

The workflow can be somenthing like this:

Guys submit a PR (usually it goes to common folder)
Some example fails at some plataform, another guy open issue.
We make a PR that moves the .md to specifc folder and create another working examples at the failing plataform.

What u guys think? I believe that the specific ones will be a minority (10% maybe?) IF we keep the examples at simple things.

Add 'alias tldr=man' to your bashrc.
Solves all issues on Linux.

[kud]

Maybe we should have cp.md in common folder and cp.md in osx folder to add some particular examples.

And when you request cp it concats common + osx...? depending on your os.

[kud]

@pawlowskimichal

@kud 👍

[Tug]

I have started working on it #44

[waldyrious]

👍 for @kud's common + platform-specific concatenation.

[Tug]

I'm not sure. Most commands are exactly the same.
The ones that differs have completely different arguments, like ifconfig or netstat. Those should have a specific documentation per OS.

[waldyrious]

Wouldn't it suffice to, in the cases where there's no common base, simply not have a .md file in the common directory? Or have one with just the definition, and no usage examples?

[xfalcox]

That was my point. We should not be merging .md files.

Just search for the specific first and fall back to common if not found.
On Jan 28, 2014 4:28 PM, "Waldir Pimenta" [email protected] wrote:

Wouldn't it suffice to, in the cases where there's no common base, simply
not have a .md file in the common directory? Or have one with just the
definition, and no usage examples?

Reply to this email directly or view it on GitHubhttps://github.com//issues/21#issuecomment-33508185
.

[rprieto]

Yep I agree with that, let's keep it simple and serve either the platform-specific file or the common one.

Merging examples would definitely add complexity, and would also require the parsing to become quite strict when I was hoping to relax it a bit. Plus bonus, Windows users might even be happy to add windows/cp.md, which I'm pretty sure is 100% different to the Unix command 😄

[waldyrious]

Yeah, on second thought that does make more sense.

[kud]

I don't see why it could be hard to display common and just after specific-os file? When I said merge or concat, it was just about displaying, not about files themselves.

What if common doesn't have an option that macosx has? Should I duplicate common/cp.md to macosx/cp.md to add the example with the specific option? I've got two files to maintain in this case.

[kud]

$ tldr ls

-> search common/ls.md, yes? display it, no? search your-os/ls.md, yes? display it, no? end.

[kud]

which gives you (it's an example, it's purely abstract)

• common/ls.md

# ls

> List directory contents

- List all files, even hidden

`ls -a`

- Sorting by size

`ls -s`

• macosx/ls.md

- List all files with their rights, groups, owner

`ls -ls`

[kud]

But it also means in fact that all titles and descriptions should be on common/your-cmd.md, if not, you'll never get a title or a description. :/

[kud]

My point is I don't want to maintain two or three files, just because some os have specific options and I have to duplicate the whole .md and add the specific example for my os.

[rprieto]

I get your point, definitely. However most people seem to say that commands are either the same, or completely different. I'd like to see a few concrete examples where the bsd & gnu flavours of a tool have most options in common except for 1 or 2.

We just landed @Tug 's PR to show either common or platform-specific, that's a great first step. Let's wait to see if this works well, I'm happy to revisit this later if it becomes cumbersome. Closing this issue for now since it said "Linux not supported".

[Tug]

@rprieto you were too fast at merging (but that's great ;)).
I just spotted a bug in my pull request. It should be fixed now with #50