Hacker News Reader

Comment by nikcub | Hacker News Reader

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.

View on HN

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.

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

(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...

Reply on news.ycombinator.com