Browse files

[enhance] manpages: added README file for instructions

  • Loading branch information...
1 parent 0721b47 commit 41daf1555ae657c70e710deee7f03b3ff187e963 Mathieu Baudet committed Dec 19, 2011
Showing with 41 additions and 0 deletions.
  1. +41 −0 manpages/README
View
41 manpages/README
@@ -0,0 +1,41 @@
+-----
+Manpage generation for Opa binaries
+-----
+
+.Overview
+
+The manpage of a binary XX is generated according to the rules of
+'Makefile'.
+
+0) if a file XX.man exists, we use it
+
+1) if the manpage of XX is generated by a specific Ocaml program, we
+use it (e.g. this is the case for the compiler 'opa')
+
+2) otherwise, we try to use existing files:
+- XX.summary
+- XX.synopsis
+- XX.description
+- XX.options
+and the output of 'XX --help' to build a default manpage.
+
+
+.How to live with the default manpage generation
+
+Everything should work fine provide 'XX --help' outputs somethings
+like this:
+
+XX: do something useful ## summary
+Usage: XX [options] arguments ## synopsis
+This is some description ## beginning of description
+split
+on several lines. ## end of description
+Options: ## introduce the options
+ -o <name> some useful option
+ ...
+
+
+Existing files .description .summary etc are always higher prioritary
+than the chunks of the help message. Missing sections are
+omitted. When regexp matching fails, the text ends up as a description
+by default.

0 comments on commit 41daf15

Please sign in to comment.