src2man(1)src2man(1)NAME
src2man - extract man pages from source files.
SYNOPSIS
src2man [-n][-d date][-v volume][-r release] [srcfile ...]
DESCRIPTION
src2man scans source file srcfile. Only C source files are supported for now. Comments blocks starting by "/** num", where num is a section
number, are converted into a man file, using txt2man(1).
The first line of the comment block must contain the name of the manpage, usually the function name, followed by a "-" and a short
description.
The following lines are the "DESCRIPTION" section content, except if they are in upper case, in which case they define a new sec-
tion.
If the next line after a comment block is empty, Then no "SYNOPSIS" section will be generated. Otherwise, src2man will look in the follow-
ing source lines for a function prototype or a type definion (struct, union, typedef, ...) matching the manpage name, and include it in a
"SYNOPSIS" section.
This avoids to duplicate the type or function prototype in the comment block.
The best place for code documentation is in the source file, where the body is implemented, not the header file which only contains the
prototype. src2man automatically searches for the presence of a prototype in the corresponding header file, and if found, will print a
"#include" statement in the synopsis.
OPTIONS -d date
Set the date of the man pages. Defaults to current date.
-n No man page is created. The name of the manpages that would be created are printed.
-v volume
Specify the name of the volume to be printed in center header of generated manpages.
-r release
Specify the project name and release number for the generated manpage.
EXAMPLE
The following example displays C code and comments to generate a manpage foobar.3:
/** 3
* foobar - a sample dummy function
* This line is now the first of the description section.
* Note that function parameters parm1 and parm2 are highlighted
* in the generated man page.
*/
int foobar(char *parm1, int parm2)
{
...
return 0;
}
SEE ALSO txt2man(1), bookman(1).
AUTHOR
Marc Vertes <mvertes@free.fr>
txt2man-1.5.5 11 April 2011 src2man(1)
Check Out this Related Man Page
yodlmanpage(7) Your Own Document Language yodlmanpage(7)NAME
yodlmanpage - Yodl's `manpage' document type
SYNOPSIS
The manpage document type was specifically implemented to write Unix-style manual pages. Other Yodl document formats, such as article,
report and book are documented in the Yodl guide and in the manpage for yodlmacros.
DESCRIPTION
This manual page briefly describes the manpage document type of the YOLD document language. This document type is specific enough that it
warrants a separate manpage.
manpage documents do not use the `standard' sectioning commands (e.g., sect() and subsect()), but have specific manpage...() macros. You
can however use (and are encouraged to..) other `normal' macros, such as description(...) or itemization(...) for lists, or bf() for bold-
face and em() for emphasis. As for fonts, the following is suggested:
o Use em(text) when text is a variable, or a placeholder, etc..
o Use bf(text) when text is literal, such as a command, a filename, a directory. Each manpage document in Yodl must be organized as
follows:
o manpage(name) (section) (date) (package) (source): This is the preamble of the document. It states whatever the page describes, the
section where it belongs, the release date, the package that it belongs to, and the source of the package. The section number
should be (according to the Linux manpage on man): 1 for commands, 2 for system calls, 3 for library calls, 4 for special files, 5
for file formats, 6 for games, 7 for macro packages and conventions, 8 for system management commands, and 9 for other special sub-
jects (e.g., kernel commands).
o manpagename(name) (short description): The name is again whatever is described, the short description is what e.g., the whatis
database uses for descriptions.
o manpagesynopsis(): a very short `usage' information or similar. Keep this section short, e.g., a line with all program options is
acceptable but without descriptions (these come later).
o manpagedescription(): the purpose of the program and such. This is also the place to document the workings.
o manpageoptions(): This is the place to document e.g. the flags that are stated in the manpagesynopsis(). This section is optional,
but when present, must appear at this place.
o manpagefiles(): relevant files are described in this section.
o manpageseealso(): this section lists related manual pages.
o manpagediagnostics(): Error conditions, error messages, etc..
o manpagebugs(): This is where known bugs are described. This section is optional.
o manpageauthor(): stating the author and/or the maintainer.
o manpagesection(NAME): This macro starts a generic, non-required section. E.g., you might want a manpagesection(EXAMPLES) in your
document. As a typographic suggestion, use upper case for the NAME argument for consistency reasons.
SEE ALSO yodlstriproff(1), yodl(1), yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmacros(7), yodlpost(1), yodlverbinsert(1).
BUGS -
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl),
yodl_3.00.0.tar.gz 1996-2010 yodlmanpage(7)