Hacker News Reader

Comment by coldtea | Hacker News Reader

I do find TLDR useful, but is there anything preventing adding it as a standard section of the actual manpages we all use?

Perhaps with a switch (man --tldr) or something?

Wouldn't a project to add those short examples to manpages be good?

View on HN

You can add a section 0 to man pages for example (tldr) versions. Man also already supports rendering HTML if that is the preferred format that contributors want to write.

With a handful of commands i've got the tldr pages rendering in man:

    mkdir /usr/local/share/man/man0/
    pandoc -f markdown_github -t html https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/tar.md > /usr/local/share/man/man0/tar.0.html
    export MANPAGER="`which lynx` -stdin"
    man 0 tar

tada.

We really shouldn't be rewriting tools and fragmenting community effort to fit a new feature that is already 90% implemented.

edit: one idea I do like is having content that is easy to contribute to, such as man pages, in separate repositories. Contributing to open source projects for content writers can often be intimidating - having a pure text separate man page repo that all the distro's use would be great.

(I am interested in your edit.) Are you suggesting a separate documentation repository for each project or a single repository shared by some specific centralized entity that somehow maintains man pages for everyone?

Both. First each project would have a documentation repository. This exists with gh-pages but it is a separate branch, which is confusing to newbies. Having a repo with just content would make it easier to open to contributors who are non-developers (and take advantage of features like inline editing in GitHub[1] (although that needs to automate the fork step as well))

Distributions can then create documentation meta-repositories that include relevant doc repo's as submodules.

If i'm a debian volunteer and I edit a typo in the man page for tar it gets pushed/pull-req up the to main tar repo from where it gets pulled out everywhere else

Not an entirely well formed idea, but the goal is to both lower the threshold for contributing documentation to project and second eliminate the duplicate effort in currently maintaining docs (which the OP project is only further complicating). Git can sit underneath what to contributors looks like nothing more than a wiki.

[1] https://help.github.com/articles/editing-files-in-your-repos...

I like the idea of adding a section for examples, but not sure "0" would be the best place for it - as it's already taken by C headers:

https://en.m.wikipedia.org/wiki/Man_page#3

Maybe [ed:1e] for "general commands - examples"?

why not 1e? 3 is library functions

Generally agree that augmenting existing man pages is then way to go. However, using a new number to categorize "use cases" or "examples" is probably incorrect.

man page categories (1, 2, 3, etc.) are organized by type of command. See: http://www.schweikhardt.net/man_page_howto.html#q2

Reviewing the convention for man pages, it seems like adding an EXAMPLES section to existing man pages is the correct way to augment the documentation.

Definitely support your position that improving existing documentation is the way to go. Just wanted to share my research on how man pages are supposed to work.

Thanks, I remembered it being extensible. Turns out that section is a char in the man code so it could easily be a new section or a switch to extract the examples.

I might do some work on this - import the examples from tldr and bro and get them into the man pages, and hopefully find a way so that man pages are easier to contribute to.

For each example in the TLDR pages repository, find the corresponding man page on your system, render the markdown to groff, insert it as EXAMPLE section before AUTHOR/SEE ALSO or at the end of the file if these sections are missing.

See man(7), man-pages(7)

Manpages already have a one-line summary, check out the "whatis" and "apropos" commands. You could combine that with the frequently occuring "EXAMPLES" section to build a similar tool.

Reply on news.ycombinator.com