I am working in a company where they use lots of tools and commands for linux (internal and external)
I would like to create a custom manual, with examples per tool.
Thought of using info tool for this:
info CompanyName tool1
info CompanyName tool2
info CompanyName tool3
..
and the output of each should be a simple text of examples and comments added by me.
But as far as I know, the info in Linux is created for a specific tool and not for a your customized needs.
Any idea what would be the best way to achieve the above?
Currently I am using sublime with tab per tool and every once and then I update the sublime tab with the new examples.
Any advice will be most appreciated.
For what it's worth, I am not a fan of info pages. I prefer the good old Unix man pages and it is very simple to write them. You can simply open any man page in an editor, look at it's source and just copy it to suit your needs.
On most systems the man pages are found in a directory like /usr/share/man/{man1,man2,man3,man4,man5,man6,man7,man8}/, or you can use the -w option of the man command to see the location of any man page and then open it. For example
$ man -w ls
/usr/share/man/man1/ls.1.gz
$ vim /usr/share/man/man1/ls.1.gz
You can see how it is written, and mimic it to write your own man page. In order for anyone to be able to read the man page written by you, the man page has to be installed in one of the directories where the man utility searches for man pages. On Linux, you can usually see this list of directories by running the manpath command (on other systems it might be different and you will have to see the man page of the man command itself). If you store your man pages in one of these directories then any one can read it by using the man utility.
As per POSIX the man utility also respects the environment variable MANPATH, so if you store your man page in a non-standard location, you can set the MANPATH variable, so that man can look it up. Or you can also modify the /etc/man.conf file to add your man page directory to the search path of man.
Now, man pages use a macro language to do the mark up. Linux systems tend to use man(7) macro syntax, for which you can see the manual here
There is another modern macro set for writing man pages, called mdoc(7), which is used extensively in the BSD family of operating systems. You can see its manual here
Related
I created a small project using C to make some commands in Linux terminal.
I want to add a description to my project to call it when I use man command. Such as if my project name is hello.c, I want when I write command man hello.c to print the description I wrote for my project. Where do I write this description?
I saw this but don't know where or how I write the description.
There are several great tutorials for doing so:
How to write a man
page
Creating your own manpage
How to write a UNIX man page.
Pick one, and hack away.
If you feel that you are stuck somewhere, take a look at man pages from FreeBSD utilities like cat, echo, etc
is there a way to dump all linux man pages into a database or set of files?
or do they already exist in some formats on the linux system where I can get a copy?
Use following command:
manpath
it will show you path of man pages
example:
user#Null-Pointer:$ manpath
/usr/local/man:/usr/local/share/man:/usr/share/man
If you take a look in the directory you will see all tar files..so almost all the man pages are stored in tar archive format and they are extracted on the fly when you ask for some man pages using
man some-command-
Man pages are already set of files. If you are interested in having them, you are better off downloading them from the original source rather than installing packages into your system and then fishing out installed files. Plus, Linux distributions are almost always running a little bit behind and have slightly outdated manual pages. There is also a good collection of up to date manual pages maintained by Michael Kerrisk (who runs man7.org), which you can download here - https://www.kernel.org/doc/man-pages/download.html
Hope it helps.
Where do I write a manual entry when creating a deb package? Is there any formatting rule/best practice to respect?
I'm very new to deb package creation. Following some tutorials, I just created a package that installs/executes nicely, so now I'd like to write some documentation so that man myFancyPackage returns something instead of no manual entry for myFancyPackage.
Unfortunately none of the tutorials I found speak about manual creation.
There are lots of methods to build a Debian package, but the current "best practice" is to use the tools provided by Debhelper. In the case of man pages, there is a tool named dh_installman (read its manpage) that is called automatically by dh. If you used dh_make or similar to create a template for your package, then a dh invocation will be in your debian/rules file.
dh_installman works by reading the file debian/manpages, or debian/nameofyourpackage.manpages. This file has a list of paths pointing to the man pages of your package. The paths are relative to the root of your package. Here you have an example of a real package. Then, this program will properly install your man pages in the right directory.
So, to sum up, you only have to create the debian/package.manpages and fill it with the paths to your man pages. These paths have to be relative to the root of your package. If you, the packager, are writing the man pages, then they have to be placed in the Debian/ directory.
Man pages were traditionally composed in a typesetting language called roff using a macro package called an (so the command line was roff -man, sic) but few people write raw roff anymore.
There are various SGML and XML documentation formats which have the capability to generate man page sources, though in this day and age, Markdown is probably gaining ground as the de facto standard for new documentation. The top Google hit for me is https://github.com/remarkjs/remark-man though I would definitely also suggest you look at pandoc.
# NAME
Markdown - popular text markup language
# SYNOPSIS
man markdown
# DESCRIPTION
This is a popular lightweight syntax
to generate styled text from an
editor-friendly text source.
It is used on [Stack Overflow][1],
[Github][2], and increasingly on
blogging and authoring platforms.
[1]: https://stackoverflow.com/
[2]: https://github.com/
I'll also mention POD format, which has a long history in the Perl community, and many features in common with popular, more recent lightweight formats. Unless you have other reasons to like it, I would not choose it for new documentation, but it used to be moderately popular even far outside the Perl world back when it was one of the only options with a simple human-readable source format, obvious semantics, and a versatile and well-maintained toolchain and support ecosystem. Some would probably say it still is.
=head1 NAME
Pod::Example - Example POD document
=head1 SYNOPSIS
pod2man thisdoc.pod >thisdoc.1
=head1 DESCRIPTION
Lightweight syntax for subheads,
hyperlinks, indented lists,
and not much else.
Natively supported in Perl source files
to facilitate a crude form of
literate programming.
I have some directories with a number of "hidden" files. One example of this is I'm in a source controlled sandbox and some of the files have not been checked out yet.
When I hit TAB, I'd like the option of seeing these files.
A similar question has been asked before: CVS Tab completion for modules under linux
The answers to that question summarize to: "Ubuntu's got that built in".
I don't have the option of switching to Ubuntu, but surely I can use the same mechanisms.
how can I hook into the TAB-completion feature of tcsh to add additional file Support for CVS, SVN and BitKeeper would all be useful.
More important than support for a specific source control system is the ability to control the returned list myself.
An acceptable solution would also be to use a key-binding other than TAB. (ctrl- perhaps)
From the manpage:
the complete builtin command can be used to tell the shell how to complete words other than filenames, commands and variables
might get you started
I do not know how to program in tcsh. But if you can, then you could look at the file named "bash_completion" from the archive (find the download link here.)
On line 1673 begins CVS completion code - and this might be portable to csh if you are familiar with the differences between bash/tcsh.
On my ubuntu machine, there is also a section for SVN completion (in /etc/bash_completion) that doesn't seem to be present in the maintainer's archive.
That's not Ubuntu-specific behavior, it's the bash-completion project.
You could use that, if you can switch from tcsh to bash.
Duplicate: https://stackoverflow.com/questions/587676/why-do-programs-in-unix-like-environments-have-numbers-after-their-name/
For instance, if I type:
man ps
...and then scroll to the very end I see something like this:
SEE ALSO
kill(1), w(1), kvm(3), strftime(3), sysctl(8)
How am I supposed to interpret this? I know that kill is another command but what's the meaning of (1)? Is there anything to this?
The git man page is riddle with these:
git-add(1), git-am(1), git-archive(1)
What is someone trying to tell me?
To access the man page for a given numbered section, type man number command
From man man
Executable programs or shell
commands
System calls (functions provided by the kernel)
Library calls (functions within program libraries)
Special files (usually found in /dev)
File formats and conventions eg /etc/passwd
Games
Miscellaneous (including macro packages and conven‐tions), e.g.
man(7), groff(7)
System administration commands> (usually only for root)
Kernel routines [Non standard]
So for example,
man 1 printf
Will give you the page for the shell printf command, whereas
man 3 printf
Will give you the page for the C library call.
The man pages are divided into sections, e.g. for system calls, commands, macros etc. mainly to prevent name conflicts, e.g. when a system call has the same name as a command.
One example for this is sleep:
man 1 sleep
versus
man 3 sleep
Section 1 is reserved for user commands.
The contents of man are divided into several sections:
Commands available to users
Unix and C system calls
C library routines for C programs
Special file names
File formats and conventions for files used by Unix
Games
Word processing packages
System administration commands and procedures
So kill(1) is about a command but strftime(3) is about a C routine.
Man pages are divided into sections. For example section 1 has commands and 2 has system calls.
If you run man kill it finds kill(1) which is the command.
If you run man 2 kill it shows you the system call also named kill.
Same goes for crontab(1) and crontab(5).
As other say, man pages are divided into sections. git-branch(1) refers to the man page named git-branch in the section 1 of manual. You access this specific man page with one of the two commands (depending of your flavour of man):
man 1 git-branch
or
man -s 1 git-branch
Moreover, some items can appear in several sections, with different meanings, e.g., printf(1) and printf(3). Typing:
man printf
displays man page for the first item found, depending of the order of your MANPATH environment variable. You can reorder MANPATH for changing your priority of sections or use:
man -a printf
for displaying all man pages for printf.