transcode: add page

[85pando]

transcode is a video stream editor. This adds examples to remove shaking from videos and resize a video.

[waldyrious]

A few comments:

• "huge number of options" is not very descriptive. At the very least, I'd suggest avoiding hyperbole.
• The first example has two commands, but it isn't clear if one should run both or either. Maybe separate it into two examples and explain the difference
• It would be nice to use the expanded option names, or at least use words in the command descriptions that match the letters of the short options. That makes it easier to memorize the command options

[85pando]

• Changed description.
• Split the first two commands into two seperate fields.
• Sadly there are no long options. I'd love to have something here to remember the flags by, but it's the way it is. Still: Changed the filenames to something more expressive and hopefully memorable.

[waldyrious]

Thanks for the quick reaction :) to be clear, I don't think the description should be too specific either, lest it induce people into thinking the tasks mentioned ("can change size of video or remove shaking") are the core functionalities of the tool. See for example the description at http://www.transcoding.org:

Transcode is a suite of command line utilities for transcoding video and audio codecs, and for converting beween [sic] different container formats.

For comparison, here's the description for moviepy (which is probably too long for tldr, but showcases a good balance between generality and specificity:

MoviePy is a Python module for video editing: cuts, concatenations, title insertions, video compositing (a.k.a. non-linear editing), video processing, and creation of custom effects.

Also, the separation of the first two commands doesn't seem warranted if the second depends on the first. I asked about that because it wasn't immediately clear from the initial description, so I'd suggest just making it clear what those two commands do but still keep them together.

Finally, even thought the options don't have long versions and the single letters don't correspond to a recognizable word (that I could find out, at least), it would be good to include mention the options used, particularly -J, -Z and -y, in the command descriptions. For example (and I'm making this up): "rezise a video to resolution 640x480 and output it to a file in the xvid format".

[85pando]

Hopefully I have know used up enough of your time to get me on the right track. I fully see your point. I was loath to create a complete description for the first two commands as this would create a multi-line description and I have not seen any in my non-exhaustive search.

Hopefully for the next command, this experience will help me to do this well on the first try (-;

• Improved Description.
• Remerged camera shake into one bullet.
• improved all descriptions to include parameters.

[waldyrious]

It is a learning process for me too, no worries :)

This seems good enough for a start, although I'd be able to comment better if I knew how to use the command myself. I'll let the maintainers comment if there are any further issues.

[rprieto]

Thanks for the new page! It's great when you discover new tools just reading the pages 😄
The content looks good to me now. Only feedback is about the structure of the first example, I'm afraid it could break tldr clients. The expected format:

# name

> high level description

- single line example description

'''
single example
'''

- single line example description

'''
single example
'''

[85pando]

I'll brain a little bit about how I could pack this into a one-line description.

[waldyrious]

I think I've seen commands with two-line descriptions (but can't point to any specific one off the top of my head, sorry)

[lord63]

@rprieto You may give the wrong example, in the CONTRIBUTING.md#markdown-format, the stardard format should be:

# command-name

> Short description
> Max 1 or 2 lines

- example description

`command -opt1 -opt2 -arg1 {{arg_value}}`

- example description

`command -opt1 -opt2`

note that the example command should be rounded with `, not ''', or it will really break the compatibility :-/

As far as I know, each command example starts with ` should be ok.

[85pando]

Maybe it should be clarified in the description if only one line is possible or more.

@lord63 Following this description i thought that multi-line comments were ok and in my understanding of markdown the best (= accepted by most parsers) way do to multiple lines in lists is to indent the second and further lines once and leave a free line.

@waldyrious I looked through loads of the files in common and did only see single line descriptions in the list.

[lord63]

@85pando

I'm afraid no. You should take clients into count. I mean, someone will use these pages to create a program to find the commands. The don't understand markdown, only simple rules(e.g. line starts)

By the way, your current PR seems that still has some problems, take a look at the example description and command usage.

[waldyrious]

@85pando I might have confused with the example in CONTRIBUTING.md, can't be sure tbh :/

[rprieto]

Indeed sorry about that, it's definitely single-line command examples.

It's a very good point about accepting any valid Markdown @85pando. I'd say it falls into 2 categories:

• accept fully arbitrary Markdown, and tldr just becomes a repo of pages (and basic Markdown renderer). This is talked about at Collaborate with bropages/cheat? #266, but it does deviate though from the original idea, which was 5-6 simple examples for each command, and if you want more you can read the man pages 😄
• keep tldr about examples, but be explicit what the Markdown constraints are: can you have multiple examples? What about multi-line descriptions? Unfortunately the current ones are not very explicit, and as @lord63 points out it's probably too late to change them. But we could think about that for a V2 format... for which it would be awesome to have a proper spec. We already have a great linter courtesy of @rubenvereecken, maybe then it could even be more rigorous.

[85pando]

In https://github.com/tldr-pages/tldr/blob/master/pages/common/find.md there are two bullets right after each other. Could this be applicable for this problem?

---

For the markdown thing, I'd rather say this should be discussed in a separate issue with a corresponding title.

[85pando]

Going for something similar to https://github.com/tldr-pages/tldr/blob/master/pages/common/find.md I think having multiple bullets for the dual command block could be a (preliminary) solution for the long description problem.

[rprieto]

Sorry find is probably a bad example that fell through the cracks :( I'll fix it later today. Please keep to the 1 bullet point / 1 command for now.

[waldyrious]

Note that, per #313, the two consecutive command lines should probably be separated by a newline.

[rprieto]

Sorry I'll disagree with that one. The CONTRIBUTING guidelines show we expect 1 command per example. I'm keen to keep it simple that like to simplify clients.

Unfortunately it also easily leads to pages like systemsetup.md

 - List valid startup disks, specify a new startup disk
 `systemsetup -liststartupdisks`
 `systemsetup -setstartupdisk {{path}}`

[85pando]

This should now be an acceptable variant.

[waldyrious]

"Pixels" shouldn't be capitalized.