Show `man` output for a single file #781

Open
mvriel opened this Issue Mar 22, 2013 · 1 comment

Projects

None yet

2 participants

@mvriel
Member
mvriel commented Mar 22, 2013

Improvement reported by @stuartherbert and @phpcodemonkey on twitter: https://twitter.com/phpcodemonkey/status/315034019504988160

phpDocumentor should be able to interpret a single file and show documentation as if it were a man page on the STDOUT.

Possible angle:

Perhaps a nice idea is to add a new command 'man' to phpDocumentor that sets a few presets and directs to a new template that generates man-style output but instead of writing it to file outputs it to STDOUT and (if on Linux) pipes it through less?

@stuartherbert suggests using an output similar to the malloc man page (https://twitter.com/stuherbert/status/315044731547684864)

@stuartherbert

A few thoughts:

  • Make piping work the same as Git (support PHPDOC_PAGER env var, pipe to less by default, do not pipe to less if stdout is not connected to a terminal)
  • Command line needs to be as simple as possible (because it will get typed a lot)
  • Might make sense to have a dedicated script for this (to avoid having to pass lots of switches to phpdoc command) ... perhaps call it 'phpman' (or hopefully something better)?
  • If you're going to support ANSI colours in the output, make it possible to disable those (via both command-line and via ENV var ... the 'ls' command is a great template for how to do this well)

I see the primary mode of operation as working on a file provided by the user, e.g.:

phpman path/to/file/MyClassFile.php

but there's even more awesomeness available if we also support the following:

phpman MyClass

and it can look up 'MyClass' from a central place of some kind.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment