Man page

[avdv]

Description

This PR adds a manual page for colorls. It tries to automatically make it work on the user's system by using the manpages gem.

The man page is written in ronn format.

In the future, the man page could probably be semi-generated using the defined options in the code...

• Relevant Issues : Support for man page #80
• Relevant PRs : (none)
• Type of change :
  • New feature
  • Bug fix for existing feature
  • Code quality improvement
  • Addition or Improvement of tests
  • Addition or Improvement of documentation

[athityakumar]

@avdv - Is there a way we can automatically generate the man page by passing the opts variable formed by Optparse module, to manpages?

[athityakumar]

Also, the formed man file from rake man has to be put in the proper system directory so that man colorls is picked up. For example, cp man/colorls.1 /usr/local/share/man/man1/colorls.1 works for Mac.

[avdv]

Also, the formed man file from rake man has to be put in the proper system directory so that man colorls is picked up. For example, cp man/colorls.1 /usr/local/share/man/man1/colorls.1 works for Mac.

This is handled by the manpages gem:

This plugin automatically hooks into the ruby gems system. Every gem installed afterwards is checked for manpages. If this gem finds them, it exposes them to the man command.

I can confirm that it works for Linux. They say it works for Mac, too. Just try it!

If you wanted to install it to the system, you would need to run this as root... Also, throughout the net, consensus seemed to be that this would be the job of a package manager, like rpm or homebrew.

[avdv]

@avdv - Is there a way we can automatically generate the man page by passing the opts variable formed by Optparse module, to manpages?

Yes, I am looking into it...

[avdv]

I have updated this branch, the options of the man page are now generated.

[avdv]

Another update... alas, the travis build still fails.

The problem is the rubocop violation of:

colorls.gemspec:40:24: C: Style/GlobalVars: Do not introduce global variables.
  spec.files         = $files
                       ^^^^^^

I had introduced the global method, since otherwise rubocop complained about the number of lines in the block:

colorls.gemspec:24:1: C: Metrics/BlockLength: Block has too many lines. [28/25]
Gem::Specification.new do |spec| ...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What are the options here? Exclude the gemspec file? Increase the limit?

[athityakumar]

Disable the Metrics/BlockLength cop before the block, with # rubocop:disable Metrics/BlockLength

[avdv]

Thanks! Done.

[athityakumar]

Can the man/colorls.1 be gitignored?

[athityakumar]

Works well. The formed man file is automatically exposed to manpath - cool! Confirmed for Mac.

One question though - if there's already a man/colorls.1 file, rake installing doesn't re-form the man file. So, any changes in the ronn file doesn't get reflected unless the existing man/colorls.1 is manually removed? Can a File.delete('man/colorls.1') be included within the task?

[avdv]

Can the man/colorls.1 be gitignored?

Yes, good point!

I'll look into the rake task issue, probably need to define a phony target...

[avdv]

I have updated the branch according to your comments:

• added man/colorls.1 to the .gitignore file
• refined the man/colorls.1 Rake task to depend on the source files
• removed the explicit dependency of the install task on the man/colorls.1 task, since Rake does that automatically, due to the gemspec files

[athityakumar]

@avdv - Awesome work. Just add "Man pages have been added. Checkout man colorls" to both README and POST_INSTALL_MESSAGE of gemspec file. We're almost ready to merge. 👍

[athityakumar]

Should ronn rather be a runtime dependency? When a user does gem install colorls, is the manpages created by default by ronn? For that, we'd require ronn to be installed while installing colorls right?

[avdv]

No, the man page is generated when building the package/gem, ie. when running rake.

[athityakumar]

Hmm, so how does the user generate the man page? The user is going to only do gem install. Not git clone and rake install. Should we have a --setup flag for that?

[avdv]

The manpage is part of the gem, it is included. This way it is only generated once and then uploaded to the gem server.

[athityakumar]

If it's part of the gem, should it NOT be git-ignored? I thought that the user would be generating the man pages after installing colorls, that's why I asked to gitignore colorls.1 file. But if we're to generate the man file and push to Rubygems too, it shouldn't be gitignored.

[avdv]

I have adjusted the message and README as per your comment. :-)

[athityakumar]

One final query: If the man file is a part of the gem, it should NOT be gitignored right? I thought that the user would be generating the man pages after installing colorls, that's why I asked to gitignore colorls.1 file. But if we're to generate the man file and push to Rubygems too, it shouldn't be gitignored.

[avdv]

One final query: If the man file is a part of the gem, it should NOT be gitignored right? I thought that the user would be generating the man pages after installing colorls, that's why I asked to gitignore colorls.1 file. But if we're to generate the man file and push to Rubygems too, it shouldn't be gitignored.

I guess that depends on your policy. Usually my policy is to never check in something that is generated. Thusly, it should be added to git ignore.

But I also have seen projects using ronn, that commit the generated files. Actually, I do not see the benefit of it... except that you would not have to add the files to the gemspec manually.

So, OK. I'll change that.

[avdv]

@athityakumar OK, done!