Having a man page for read
(in section 1 of the manual) that says anything else than "There is no read
command, but your shell might have a read
builtin command, see your shell manual for details" is misleading, because read
is a shell builtin and the behaviour and supported options vary from shell to shell.
Some systems (generally not Linux ones) however do have a read
command (in /bin
, /usr/bin
or elsewhere) as POSIX requires (but the Linux Standard Base (LSB) specification lifts that requirement), and on those systems, the man page will describe the behaviour of that read
command, and will be misleading because it's generally not that read
that you invoke when you call read
at a shell prompt or in a shell script or in system()
, popen()
... but the shell builtin one.
That http://ss64.com site describes the bash
builtin read
command (though it doesn't say which version of bash
, and for instance, it's different from the read
builtin in the version of bash
on this machine, which itself is different from that read
from the bash
of another (older) machine I have access to) in a bash
section. In that regard, it's not misleading, but where it's very misleading is where it puts all sorts of other non-bash related commands in that same section and sort of implies that bash
(one of many shells available on Linux and other Unices, shells being one of many ways to run commands) is necessary to run those commands or that those commands have anything to do with it.
Now, when you do man read
, if there's no read
command in section 1 (user commands) of the manual, it will search in other sections. For instance, if you have installed the manpages-dev
package (on Debian), you'll get the man page of the read
system call (in section 2). If not, but you have installed the TCL documentation package, you'll get the man page for the read
TCL function in section 3tcl
.
You can ask explicitly for the read
user command with man 1 read
(man -s 1 read
on some systems). If your manual had a 1bash
section, it would bring it up before the one in section 1zsh
, so you'd need to write it man 1zsh read
to get the zsh
variant. You can get all the man pages with man -a read
, you can find out what packages they come from on Debian with: dpkg -S $(man -wa read)
. For instance, on this system, I have:
$ dpkg -S $(man -wa read)
9base: /usr/share/man/man1/plan9-read.1.gz
tcl8.5-doc: /usr/share/man/man3/read.3tcl.gz
manpages-dev: /usr/share/man/man2/read.2.gz
With zsh
, pressing Alt-H at the prompt brings the manual (via the man
command) for the command you're currently typing. The default zsh
installation on Debian improves it to make use of the run-help
function (see info -f zsh --index-search=run-help
), so you get help for the builtins as well.
With the fish
shell, there's a help
builtin function that tries to bring the most sensible documentation for a given command or fish
concept (from man
or the fish
documentation).
If for some reason, you're forced to using bash
(grin) or can't be bothered to change from the default, bash
also has a help
builtin command that brings help on bash
builtins (however note that help read
is like help '*read*'
, that is it brings the manual for all the builtins whose name contains read
, use help '[r]ead'
for instance, if you only want the read
manual).
bash
's help only works for bash
builtins. If you want to extend it to include search in the manual in sections 1 (user commands) and 6 (games) and 8 (administrative commands), you could redefine it as:
help() {
builtin help "$@" 2> /dev/null ||
MANSECT=1:8:6 man "$@"
}
You have not specified your desired output format but from the things you've tried, it looks like you're not picky. This will produce correctly formatted, unwrapped html but it needs to be run on the actual man page file.
So, first locate the man file you're interested in:
$ man -w mmap
/usr/share/man/man2/mmap.2.gz
Them, run man2html
on it:
man2html /usr/share/man/man2/mmap2.2.gz > mmap.html
Or, simply
zcat $(man -w mmap) | man2html > mmap.html
The output looks like this:
man2html
was available in the Debian repository, I installed it with sudo apt-get install man2html
.
Once you have it in HTML, you can translate to other formats easily enough: Actually, these won't work, they'll wrap the line automatically again.
man2html /usr/share/man/man1/grep.1.gz | html2ps > grep.ps
man2html /usr/share/man/man1/grep.1.gz | html2ps | ps2pdf14 - grep.man.pdf
`
Best Answer
Definitely, the
bundle-gem
online manual was created from the bundle-gem.ronn file. Andronn
is a format (and program) meant to be formatted as a man page.First let's get the files (for
bundler-gem
andronn
):And create the man page:
(You probably have the gem path in PATH, but I added it here just in case. Also
-r
stands forroff
i.e. the format used for man pages)And see the manpage:
If you want the manpage to show when you do
man bundle-gem
place it somewhere sensible and add that place toMANPATH
. For example:(Note the use of man sections here)
Extra notes
Since
ronn
useshpricot
you can useronn -5 <file.ronn>
to generate that web manual you were reading.gem
will runronn
for you, therefore if you installedbundler
withgem
you will have the manual page in~/.gem/ruby/<version>/gems/bundler-<version>/man
. Unfortunatelygem
does not follow the *nix convention of dividing man sections into directories (man1
,man2
, ...), therefore it may be troublesome to retrieve the man pages from~/.gem
(usingMANPATH
isn't an option here).If you do not have
MANPATH
set yet, then your system is using/etc/man_db.conf
. In that case you should setMANPATH
as: