{"id":216,"date":"2008-08-24T04:22:01","date_gmt":"2008-08-24T12:22:01","guid":{"rendered":"http:\/\/wp.colliertech.org\/cj\/?p=216"},"modified":"2009-01-18T19:13:01","modified_gmt":"2009-01-19T03:13:01","slug":"writing-free-software-part-11-a-simple-man-page","status":"publish","type":"post","link":"https:\/\/wp.c9h.org\/cj\/?p=216","title":{"rendered":"Writing Free Software: Part 11 &#8211; A simple man page"},"content":{"rendered":"<h3>Introduction<\/h3>\n<p>Okay&#8230; it&#8217;s high time we wrote some docs.  I come from a perl background, so we&#8217;re going to write the docs using perldoc.  I know there are better ways to do this for C# projects and I&#8217;m happy to take contributions to this series.  Just ask for contributor status and you can post the next article :)<\/p>\n<h3>Return to the workspace<\/h3>\n<p><code><b>$<\/b> cd ~\/src\/greeting<\/code><\/p>\n<h3>Create the <a href=\"http:\/\/en.wikipedia.org\/wiki\/Plain_Old_Documentation\">POD<\/a><\/h3>\n<p><code><b>$<\/b> mkdir doc<br \/>\n<b>$<\/b> cat &gt; doc\/greeting.pod.in<br \/>\n<\/code><\/p>\n<pre>\r\n=head1 NAME\r\n\r\nGreeting - Example to illustrate writing and distributing Free Software\r\n\r\n=head1 VERSION\r\n\r\nVersion @PACKAGE_VERSION@\r\n\r\n=head1 SYNOPSIS\r\n\r\n Greeting will greet the planet specified numerically\r\n (1 = Mercury .. 9 = Pluto) or the world, given\r\n no argument or arg value 0.\r\n\r\n $ greeting\r\n Greetings World!\r\n $ greeting -n 1\r\n Greetings Mercury!\r\n $ greeting --number 3\r\n Greetings Earth!\r\n\r\n=head1 COPYRIGHT\r\n\r\nCopyright 2008 J. Random Hacker <jrh@cpan.org>.\r\n\r\n  Permission is granted to copy, distribute and\/or modify\r\n  this document under the terms of the GNU Free\r\n  Documentation License, Version 1.2 or any later version\r\n  published by the Free Software Foundation; with no\r\n  Invariant Sections, with no Front-Cover Texts, and with\r\n  no Back-Cover Texts.\r\n\r\n=cut\r\n<\/pre>\n<h3>Update configure.ac<\/h3>\n<p><code><b>$<\/b> patch configure.ac<br \/>\n@@ -11,11 +11,18 @@<br \/>\n   AC_MSG_ERROR([Can't find \"gmcs\" in your PATH])<br \/>\n fi<br \/>\n&nbsp;<br \/>\n+AC_PATH_PROG(PERLDOC, perldoc, no)<br \/>\n+if test \"x$PERLDOC\" = \"x\" ; then<br \/>\n+  AC_MSG_ERROR([Can't find \"perldoc\" in your PATH])<br \/>\n+fi<br \/>\n+<br \/>\n AC_CONFIG_FILES([<br \/>\n Makefile<br \/>\n ndesk\/Makefile<br \/>\n src\/Makefile<br \/>\n greeting<br \/>\n+doc\/Makefile<br \/>\n+doc\/greeting.pod<br \/>\n ])<br \/>\n AC_OUTPUT<br \/>\n&nbsp;<br \/>\n@@ -24,6 +31,7 @@<br \/>\n echo \"Thank you for configuring '$PACKAGE_NAME' version '$PACKAGE_VERSION'\"<br \/>\n echo \"Runtime:             $RUNTIME\"<br \/>\n echo \"C# compiler:         $CSC\"<br \/>\n+echo \"Perldoc interpreter:  $PERLDOC\"<br \/>\n echo \"installation prefix: $prefix\"<br \/>\n echo \"\"<br \/>\n echo \"=================\"<br \/>\n<\/code><\/p>\n<h3>Create doc\/Makefile.am file for man page<\/h3>\n<p><code><b>$<\/b> cat &gt; doc\/Makefile.am<\/code><\/p>\n<pre>\r\nall: man1\/greeting.1\r\n\r\nman1\/greeting.1: man1 greeting.pod\r\n        $(PERLDOC) -d man1\/greeting.1 greeting.pod\r\n\r\nman1:\r\n        mkdir man1\r\n\r\nclean:\r\n        rm -rf man1\r\n\r\nnoinst_docdir = $(prefix)\/share\/man\/man1\r\nnoinst_doc_DATA = man1\/greeting.1\r\n\r\nDISTCLEAN_FILES = greeting.pod\r\n<\/pre>\n<h3>Update Makefile.am<\/h3>\n<p><code><b>$<\/b> patch Makefile.am<br \/>\n@@ -1,3 +1,3 @@<br \/>\n-SUBDIRS = src ndesk<br \/>\n+SUBDIRS = src ndesk doc<br \/>\n&nbsp;<br \/>\n bin_SCRIPTS = greeting<br \/>\n<\/code><\/p>\n<h3>Re-build Makefile files and configure script<\/h3>\n<p><code><b>$<\/b> autoreconf<\/code><\/p>\n<h3>Test<\/h3>\n<p><code><b>$<\/b> make<br \/>\n...<br \/>\n<b>$<\/b> man -M doc greeting<br \/>\n...<br \/>\n<b>$<\/b> sudo make install<br \/>\n...<br \/>\n<b>$<\/b> man greeting<br \/>\n<\/code><\/p>\n<h3>Conclusion<\/h3>\n<p>There&#8217;s a lot more to documentation than this, but like the other pieces of this series, this is an introduction that should get you to a point where you can distributed &#8220;just enough.&#8221;  Some other good tools to look at:<\/p>\n<ul>\n<li><a href=\"http:\/\/www.mono-project.com\/Monodoc\">monodoc<\/a><\/li>\n<li><a href=\"http:\/\/en.wikipedia.org\/wiki\/DocBook\">docbook<\/a><\/li>\n<li><a href=\"http:\/\/www.gnu.org\/software\/texinfo\/\">GNU Texinfo<\/a><\/li>\n<\/ul>\n<p>I&#8217;m serious about having others beef up this series with a 11.1, 11.2, etc.  Leave a comment or catch me on IRC and I&#8217;ll hook you up with contributor status.<\/p>\n\n<div class=\"twitter-share\"><a href=\"https:\/\/twitter.com\/intent\/tweet?via=cjamescollier\" class=\"twitter-share-button\">Tweet<\/a><\/div>\n","protected":false},"excerpt":{"rendered":"<p>Introduction Okay&#8230; it&#8217;s high time we wrote some docs. I come from a perl background, so we&#8217;re going to write the docs using perldoc. I know there are better ways to do this for C# projects and I&#8217;m happy to take contributions to this series. Just ask for contributor status and you can post the [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[180,38,79,181,7,18,166],"tags":[],"class_list":["post-216","post","type-post","status-publish","format-standard","hentry","category-autotools","category-c","category-free-software","category-irc","category-mono","category-perl","category-software"],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/p1YDIB-3u","jetpack_sharing_enabled":true,"jetpack_likes_enabled":true,"_links":{"self":[{"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=\/wp\/v2\/posts\/216","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=216"}],"version-history":[{"count":5,"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=\/wp\/v2\/posts\/216\/revisions"}],"predecessor-version":[{"id":325,"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=\/wp\/v2\/posts\/216\/revisions\/325"}],"wp:attachment":[{"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=216"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=216"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wp.c9h.org\/cj\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=216"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}