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
Related
I am writing a few custom man pages and I would like to include things that might change often such as the date of the man page's writing.
For example, one is in a git repo that I would like to update the man page's date whenever a change is made to it without having to do it by hand.
Is there a possibility to #include or call shell variables in the *roff file, or perhaps a markdown file and then use pandoc to "compile" the man page with?
I understand this is a strange question, but I haven't come across anything similar.
Please note this is different than simply including a man page in the $MANPATH to be called by man.
I.E., I want to use something like:
.TH foo 10 "$(git log -n1 | grep Date | tail -c 31)" "$(git branch | grep "*")"
in place of having to manually change the date and branch/head name every time. Whether this is in markdown and given to pandoc or something else or just in the roff file itself, I am okay with either.
Consider composing the content of the man page using a documentation generator language like asciidoc, which has most of the desired features. The asciidoc format can include external input files, and change all sorts of things on-the-fly as needed.
To include shell script, see Substitutions inside literals in Asciidoc
.
Or one could use a shell script to generate a config file, then include that file.
Apologies in advance if this answer is at present little vague, in that it's more of a software recommendation (without any actual code) than a real answer.
I see from your example line that you're using Git - I believe you can use a 'pre-commit' git hook (basically a script that runs before your commit is processed) to update the contents of the manpage (and stage the changes) on every commit.
For example, you could put the following commands in your .git/hooks/pre-commit file to update the contents of the manpage in place whenever you commit:
sed -i "" "s/^.TH foo 1 \".*/.TH foo 1 \"$(date)\"/" path/to/manpage.roff
git add path/to/manpage.roff
Note that the path is relative to the root of the git repository.
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
I'm working on a lab that is supposed to help us better navigate the command line on a Linux system, but I'm getting stuck on man pages.
We are supposed to use the man command to find a list of the man page sections, adn I can't seem to figure out how to do this. I've tried entering
man man
but that doesn't give me any information on the individual sections. I've also tried looking on Google to find what command I should use, but no luck there either.
Can anybody point me in the right direction?
apropos -r '.*'
This will list all manual pages. A script to chop this up into lists by section is a follow-up homework assignment.
We have application which is written in Python in linux enviromet which is legacy code.I have task to document which help other in wiki page. I thought, Can I add one file into Existing code. So I can add documentation into another File. So if user open file it will pop us with code detail. if user does not want to see that file they can close this File. for Example
sample.py ( A File which contain code)
demo.txt ( which contain documentation file)
So if I open sample.py using vi like vi sample.py than demo.txt open by default like pop us or simple way which contain documentation part. I think it is like windows tool when we open tool it pop us infront of user. it is my idea I am not sure really it is valid or not. I have searched but could not find any useful information.
What you want to do will most likely confuse the user. If one types vi sample.py one expects to read this file. Now what you can do as #HAL said in his comment is add a comment in your code saying that the documentation for this code is in the demo.txt accessible at /path/to/demo.txt.
I think this is the common way to do it, and you will probably frustrate the user if you don't do it this way. (at least I would be ;) )
I am not aware of any Linux specific include functionality and I do not think that it exists, because the program you are executing is vi and not the Linux kernel. But editors support editor specific functions for hyper links. Here is an example for vim. vim: Add clickable label
Another way would be to replace vi with a shell script which does what you want. This is an example:
#! /bin/bash
if [ "$1" = "sample.py" ] ; then
vim demo.txt "$1"
fi
This will open the documentation together with the program in two vim buffers.
Is there a good database for Linux where I can search for a function name and it tells me which header it is defined in? Googling doesn't always work for me and there aren't always man pages.
Using manpages
For basic C functions, the manpages should work.
man 2 read
man 3 printf
Section 2 is for system calls (direct to the kernel), and section 3 is for standard C library calls. You can generally omit the section, and man will figure out what you need on its own.
Note that you may need to take extra steps to get development-related manpages on your system. For example, on my Debian system, I had to do apt-get install manpages-dev glibc-doc.
Using library-specific references
For non-basic C functions, you should check the documentation of the library you're using (e.g., GNU's docs for libstdc++, doc.qt.io for Qt, library.gnome.org for GNOME projects like GTK, and so on).
Using the web
linux.die.net is a good online mirror of web pages.
LSB Navigator (as described in this answer) looks cool. I did not know about that.
Using grep
Sometimes it's just easiest to search /usr/include yourself. grep works for this, but ack is much better. For example, if I'm trying to find the header that contains getRootLogger:
cd /usr/include
# Debian calls 'ack' ack-grep. Your system may differ.
# Add \b before and after to only match a complete word.
ack-grep '\bgetRootLogger\b'
ack will return a nicely formatted and colorized list of matches.
You can wrap this up in a function and put it in your .bashrc file (or equivalent) for easy use:
function findheaderfor() {
ack-grep \\b$1\\b /usr/include /usr/local/include
}
Try the man pages, I use them a lot. You get the files you need to include.
Sometimes you want to pass a section number. Here are some examples :
man 2 socket
man 2 accept
man 3 fopen
man sem_post
2 is for system call related functions
3 is for function from the C library.
If there is no ambiguity, the section number is not needed
If you are looking for kernel function definition or kernel source navigation, you should definitely try lxr.linux.no
Sure, have you tried "man" in Linux?
For C functions, you may want to do "man 3 ".
You could use LSB Navigator (use search field in the top-right corner). However, most functions, about which you will find header information there, have manpages as well.