Re: How to make man pages
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 ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
On Mon, 12 Apr 2010 16:49:04 +0800, Fbsd1 fb...@a1poweruser.com wrote: 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. 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. ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
Matthew Seaman wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 31/03/2010 08:54:25, Fbsd1 wrote: 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 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. 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? ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 01/04/2010 09:41:59, Fbsd1 wrote: 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 -BEGIN PGP SIGNATURE- Version: GnuPG/MacGPG2 v2.0.14 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAku0ZFIACgkQ8Mjk52CukIxTjACffpWoxOj7/QPl+KgFpxCSIq4z Yn0AniejXWTWtZZwpgr4RpoIQTF5xMur =YLBi -END PGP SIGNATURE- ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
Matthew Seaman wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 01/04/2010 09:41:59, Fbsd1 wrote: 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 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. ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 01/04/2010 10:29:48, Fbsd1 wrote: 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 -BEGIN PGP SIGNATURE- Version: GnuPG/MacGPG2 v2.0.14 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAku0aIMACgkQ8Mjk52CukIz2ygCfRoFoguCJuLVbNEH/LodGP6tz LWoAoIcsP1vs/82Ex4ex6lSloRU5E+wJ =qQe5 -END PGP SIGNATURE- ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 31/03/2010 04:00:15, Fbsd1 wrote: 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 -BEGIN PGP SIGNATURE- Version: GnuPG/MacGPG2 v2.0.14 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAkuy+P8ACgkQ8Mjk52CukIxcggCeLR3OcpdwZ/OZGZv623DawCC9 E+4AoJNMvoINM9xkL2CdYBwz/ozPnAgK =qVD0 -END PGP SIGNATURE- ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
On 31/03/2010 04:00:15, Fbsd1 wrote: 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 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? ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 31/03/2010 08:54:25, Fbsd1 wrote: 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 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 -BEGIN PGP SIGNATURE- Version: GnuPG/MacGPG2 v2.0.14 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAkuzE+0ACgkQ8Mjk52CukIx6VgCfV9R1LOrqcjzlnwSEMNHAT/Ys iOEAniohL9mC7ehGZXKub+9RHKmI87px =fhC7 -END PGP SIGNATURE- ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
On Wed, 31 Mar 2010 15:54:25 +0800, Fbsd1 fb...@a1poweruser.com articulated: On 31/03/2010 04:00:15, Fbsd1 wrote: 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 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 freebsd.u...@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 ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
Matthew == Matthew Seaman m.sea...@infracaninophile.co.uk writes: 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 mer...@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 ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
Re: How to make man pages
On Wed, 31 Mar 2010 15:54:25 +0800, Fbsd1 fb...@a1poweruser.com wrote: 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. keram...@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 keram...@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. ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
How to make man pages
Where can I find documentation on the procedure to create man pages for a port? ___ freebsd-questions@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-questions To unsubscribe, send any mail to freebsd-questions-unsubscr...@freebsd.org
