Discussion:
How to make "man" pages
(too old to reply)
Fbsd1
2010-03-31 03:00:15 UTC
Permalink
Where can I find documentation on the procedure to create "man" pages
for a port?
Matthew Seaman
2010-03-31 07:25:51 UTC
Permalink
Post by Fbsd1
Where can I find documentation on the procedure to create "man" pages
for a port?
If you want to write a man page from scratch, probably the best way to
get started is to just copy a man page from the base system and edit it
to taste. See groff(1) for documentation on the command used to format
man pages from source, and groff_mdoc(7) for details on the groff macro
syntax. groff+mdoc might be a markup language, but it's nothing at all
like HTML.

If you're after how to install man pages for a port, then look at:

http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-manpages.html

Note that the MANX and other ports Macros only affect the pkg-list and
compressing the man pages /after/ installation. You'll still have to put
in some code to copy your self-written man page into place.

Cheers,

Matthew

- --
Dr Matthew J Seaman MA, D.Phil. 7 Priory Courtyard
Flat 3
PGP: http://www.infracaninophile.co.uk/pgpkey Ramsgate
Kent, CT11 9PW
Fbsd1
2010-03-31 07:54:25 UTC
Permalink
Post by Matthew Seaman
Post by Fbsd1
Where can I find documentation on the procedure to create "man" pages
for a port?
If you want to write a man page from scratch, probably the best way to
get started is to just copy a man page from the base system and edit it
to taste. See groff(1) for documentation on the command used to format
man pages from source, and groff_mdoc(7) for details on the groff macro
syntax. groff+mdoc might be a markup language, but it's nothing at all
like HTML.
http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-manpages.html
Note that the MANX and other ports Macros only affect the pkg-list and
compressing the man pages /after/ installation. You'll still have to put
in some code to copy your self-written man page into place.
Cheers,
Matthew
OK i want to write a man page from scratch. So lets say i want to use
/usr/share/man/man2/jail.2.gz as my starting sample. How do I convert
this .gz file to a plain text file so I can edit it with ee? And how do
I turn the edited text file back in to a man page .gz file?
Matthew Seaman
2010-03-31 09:20:45 UTC
Permalink
Post by Fbsd1
OK i want to write a man page from scratch. So lets say i want to use
/usr/share/man/man2/jail.2.gz as my starting sample. How do I convert
this .gz file to a plain text file so I can edit it with ee?
% cp /usr/share/man/man2/jail.2.gz .
% gunzip jail.2.gz
% mv jail.2 myname.2
% ee myname.2
Post by Fbsd1
And how do
I turn the edited text file back in to a man page .gz file?
To compress the groff source:

% gzip myname.2

To render the groff source as ascii text (what the man(1) command does):

% groff -mdoc -Tascii myname.2 | less

or

% gzcat myname.2.gz | groff -mdoc -Tascii | less

In general though, you should keep the man page source uncompressed
while you're working on it and within the port; install it uncompressed
and leave it to the ports machinery to compress it after installation.

Cheers,

Matthew

- --
Dr Matthew J Seaman MA, D.Phil. 7 Priory Courtyard
Flat 3
PGP: http://www.infracaninophile.co.uk/pgpkey Ramsgate
Kent, CT11 9PW
Fbsd1
2010-04-01 08:41:59 UTC
Permalink
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Post by Fbsd1
OK i want to write a man page from scratch. So lets say i want to use
/usr/share/man/man2/jail.2.gz as my starting sample. How do I convert
this .gz file to a plain text file so I can edit it with ee?
% cp /usr/share/man/man2/jail.2.gz .
% gunzip jail.2.gz
% mv jail.2 myname.2
% ee myname.2
Post by Fbsd1
And how do
I turn the edited text file back in to a man page .gz file?
% gzip myname.2
% groff -mdoc -Tascii myname.2 | less
or
% gzcat myname.2.gz | groff -mdoc -Tascii | less
In general though, you should keep the man page source uncompressed
while you're working on it and within the port; install it uncompressed
and leave it to the ports machinery to compress it after installation.
Getting closer but not there yet. Selected man jail to be my example of
macro commands used. Did [gunzip jail.8.gz] and now I have jail.8 file.
How to I convert this file to native macro file that I can edit with ee?

After editing the macro file how to I convert it to format ready to
compress? I want to test it with the man command.

When I do groff -mdoc -Tascii jail.8 | less
I get loads of this message "mdoc warning: Empty input line #xxx.
If I look at man jail screen output I see each message corresponds to a
blank line in the man page. Is this suppose to happen?
Matthew Seaman
2010-04-01 09:16:02 UTC
Permalink
Post by Fbsd1
Getting closer but not there yet. Selected man jail to be my example of
macro commands used. Did [gunzip jail.8.gz] and now I have jail.8 file.
How to I convert this file to native macro file that I can edit with ee?
Ah -- did you copy the right file? /usr/share/man/man8/jail.8.gz should
contain mdoc source, which looks like this:


.\"
.\" Copyright (c) 2000, 2003 Robert N. M. Watson
.\" Copyright (c) 2008 James Gritton
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the

[... copyright statements elided for reasons of space ...]

.\" $FreeBSD: src/usr.sbin/jail/jail.8,v 1.97.2.3 2010/01/23 16:40:35 bz
Exp $
.\"
.Dd January 17, 2010
.Dt JAIL 8
.Os
.Sh NAME
.Nm jail
.Nd "create or modify a system jail"
.Sh SYNOPSIS
.Nm
[...etc...]

No blank lines there. Don't confuse this with the preprocessed version
in /usr/share/man/*cat8*/jail.8.gz

Cheers,

Matthew

- --
Dr Matthew J Seaman MA, D.Phil. 7 Priory Courtyard
Flat 3
PGP: http://www.infracaninophile.co.uk/pgpkey Ramsgate
Kent, CT11 9PW
Fbsd1
2010-04-01 09:29:48 UTC
Permalink
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Post by Fbsd1
Getting closer but not there yet. Selected man jail to be my example of
macro commands used. Did [gunzip jail.8.gz] and now I have jail.8 file.
How to I convert this file to native macro file that I can edit with ee?
Ah -- did you copy the right file? /usr/share/man/man8/jail.8.gz should
.\"
.\" Copyright (c) 2000, 2003 Robert N. M. Watson
.\" Copyright (c) 2008 James Gritton
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
[... copyright statements elided for reasons of space ...]
.\" $FreeBSD: src/usr.sbin/jail/jail.8,v 1.97.2.3 2010/01/23 16:40:35 bz
Exp $
.\"
.Dd January 17, 2010
.Dt JAIL 8
.Os
.Sh NAME
.Nm jail
.Nd "create or modify a system jail"
.Sh SYNOPSIS
.Nm
[...etc...]
No blank lines there. Don't confuse this with the preprocessed version
in /usr/share/man/*cat8*/jail.8.gz
Cheers,
Matthew
Yep that is the problem. I have no source. I did minimum install.
Is there any way to convert the preprocessed version in
/usr/share/man/*cat8*/jail.8.gz to native macro file.
Matthew Seaman
2010-04-01 09:33:55 UTC
Permalink
Post by Fbsd1
Yep that is the problem. I have no source. I did minimum install.
Is there any way to convert the preprocessed version in
/usr/share/man/*cat8*/jail.8.gz to native macro file.
Download mdoc sources from here:

http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.sbin/jail/jail.8

Cheers,

Matthew

- --
Dr Matthew J Seaman MA, D.Phil. 7 Priory Courtyard
Flat 3
PGP: http://www.infracaninophile.co.uk/pgpkey Ramsgate
Kent, CT11 9PW
Jerry
2010-03-31 09:34:11 UTC
Permalink
Post by Fbsd1
Post by Matthew Seaman
Post by Fbsd1
Where can I find documentation on the procedure to create "man"
pages for a port?
If you want to write a man page from scratch, probably the best way
to get started is to just copy a man page from the base system and
edit it to taste. See groff(1) for documentation on the command
used to format man pages from source, and groff_mdoc(7) for details
on the groff macro syntax. groff+mdoc might be a markup language,
but it's nothing at all like HTML.
http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-manpages.html
Note that the MANX and other ports Macros only affect the pkg-list
and compressing the man pages /after/ installation. You'll still
have to put in some code to copy your self-written man page into
place.
Cheers,
Matthew
OK i want to write a man page from scratch. So lets say i want to use
/usr/share/man/man2/jail.2.gz as my starting sample. How do I convert
this .gz file to a plain text file so I can edit it with ee? And how
do I turn the edited text file back in to a man page .gz file?
If you visit this URL:
<http://www.tldp.org/LDP/abs/html/writingscripts.html> you will see
links to various scripts. One of them is for creating 'man' pages:
<http://www.tldp.org/LDP/abs/html/contributed-scripts.html#MANED>

You might want to investigate its usefulness for your project.
--
Jerry
***@seibercom.net

Disclaimer: off-list followups get on-list replies or get ignored.
Please do not ignore the Reply-To header.
__________________________________________________________________

FORTUNE REMEMBERS THE GREAT MOTHERS: #5

"And, and, and, and, but, but, but, but!"


Mrs. Janice Markowsky, April 8, 1965
Giorgos Keramidas
2010-03-31 16:22:23 UTC
Permalink
Post by Fbsd1
OK i want to write a man page from scratch. So lets say i want to use
/usr/share/man/man2/jail.2.gz as my starting sample. How do I convert
this .gz file to a plain text file so I can edit it with ee? And how do
I turn the edited text file back in to a man page .gz file?
The manpage sources are plain text files with text that uses formatting
macros from the groff_mdoc(7) macro collection. You can find sample
files for the style commonly used by the FreeBSD manpages in your
'/usr/share/examples/mdoc' directory.

***@kobe:/usr/share/examples/mdoc$ ls -ld *[0-9]
-r--r--r-- 1 root wheel - 3550 18 Μαρ 01:55 example.1
-r--r--r-- 1 root wheel - 7582 18 Μαρ 01:55 example.3
-r--r--r-- 1 root wheel - 3302 18 Μαρ 01:55 example.4
-r--r--r-- 1 root wheel - 7700 18 Μαρ 01:55 example.9
***@kobe:/usr/share/examples/mdoc$

Installed manpages can be found under '/usr/share/man/man?'. They are
usually compressed with gzip(1) to save some space, but you can extract
any manpage to a plain text file with gzip or zcat:

zcat /usr/share/man2/jail.2.gz | more

The source of a manpage commonly uses _many_ formatting macros from the
groff_mdoc(7) collection. You should probably print a copy of the
'groff_mdoc' manpage and keep it around for reference. Reading through
this printed copy of the manpage at least once will be useful too, as it
will help you understand how macro options work and you will have a good
idea of what features are available. Then you will be able to quickly
look in the printed reference copy for the features you need, because
you will know "they are there".
Fbsd1
2010-04-12 08:49:04 UTC
Permalink
For the questions list archives:
I wrote an How To Creating a manpage from scratch.

You can read it here.

http://www.daemonforums.org/showthread.php?t=4602

Thanks to all the people who replied to my post.

Joe
Giorgos Keramidas
2010-04-12 09:34:48 UTC
Permalink
Post by Fbsd1
I wrote an How To Creating a manpage from scratch.
You can read it here.
http://www.daemonforums.org/showthread.php?t=4602
Thanks to all the people who replied to my post.
Nice post. This is exactly the sort of post that raises the signal to
noise ratio in web-based forums. Good job writing it :-)

You should probably try to grok some of the semantic markup requests
like .Op too though. For example this part:

: SYNOPSIS
: jail [-dhi] [-J jid_file] [-l -u username | -U username] [-c | -m]
: jail [-hi] [-n jailname] [-J jid_file] [-s securelevel]
: [-l -u username | -U username] [path hostname [ip[,..]]

Is commonly written in several lines. If you try to read each line
separately they do make sense, e.g.:

.Nm
.Op Fl dhi

Will render as:

jail [-dhl]

with the flag letters displayed in bold text.

The .Op macro wraps everything in [...] brackets.

The .Fl macro marks up 'command flags'.

It takes a bit of practice to write manpages using this sort of markup,
but the displayed output looks great in ascii, PostScript or HTML output
modes. So it's worth trying to learn more about it.

Randal L. Schwartz
2010-03-31 13:30:42 UTC
Permalink
Matthew> groff+mdoc might be a markup language, but it's nothing at all
Matthew> like HTML.

No, it's not. It's actually turing-complete. I did "towers of hanoi"
in troff at one point. Can't do that with HTML. :)
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<***@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Smalltalk/Perl/Unix consulting, Technical writing, Comedy, etc. etc.
See http://methodsandmessages.vox.com/ for Smalltalk and Seaside discussion
Loading...