util: improve the command line argument parsing in wmmenugen

The code ignored the last argument provided on the command line;

It did not support the recommended '--version' and '--help' from GNU which
are often handy;

It used an unusual syntax to specify the parser, now it can also use more
usual "-parser=name" and "-parser name", the old syntax is still supported
to avoid breaking compatibility;

When a problem is found with an argument, the program stops instead of
printing an error message and continuing;

There's been updates on the exit codes in case of problem because it is an
information that could be useful for people calling the program from a
script;

Took the opportunity to provide more information in the man page and to
get it cross-checked against the program's option list during "make check".

Signed-off-by: Christophe CURIS <christophe.curis@free.fr>

doc/Makefile.am

@@ -49,7 +49,7 @@ am__v_CHKOPTS_0 = @echo "  CHK      $@" ;
 am__v_CHKOPTS_1 =
 
 check-local: wmaker-args WPrefs-args wmagnify-args geticonset-args getstyle-args seticons-args setstyle-args \
-	wdread-args wdwrite-args wmgenmenu-args wmsetbg-args wxcopy-args wxpaste-args
+	wdread-args wdwrite-args wmgenmenu-args wmmenugen-args wmsetbg-args wxcopy-args wxpaste-args
 
 wmaker-args:
 	$(AM_V_CHKOPTS)$(top_srcdir)/script/check-cmdline-options-doc.sh \
@@ -91,6 +91,10 @@ wmgenmenu-args:
 	$(AM_V_CHKOPTS)$(top_srcdir)/script/check-cmdline-options-doc.sh \
 		--program "$(top_builddir)/util/wmgenmenu" --man-page "$(top_srcdir)/doc/wmgenmenu.1"
 
+wmmenugen-args:
+	$(AM_V_CHKOPTS)$(top_srcdir)/script/check-cmdline-options-doc.sh \
+		--program "$(top_builddir)/util/wmmenugen" --man-page "$(top_srcdir)/doc/wmmenugen.1"
+
 wmsetbg-args:
 	$(AM_V_CHKOPTS)$(top_srcdir)/script/check-cmdline-options-doc.sh \
 		--program "$(top_builddir)/util/wmsetbg" --man-page "wmsetbg.1"
@@ -104,4 +108,4 @@ wxpaste-args:
 		--program "$(top_builddir)/util/wxpaste" --man-page "$(top_srcdir)/doc/wxpaste.1"
 
 .PHONY: wmaker-args WPrefs-args wmagnify-args geticonset-args getstyle-args seticons-args setstyle-args \
-	wdread-args wdwrite-args wmgenmenu-args wmsetbg-args wxcopy-args wxpaste-args
+	wdread-args wdwrite-args wmgenmenu-args wmmenugen-args wmsetbg-args wxcopy-args wxpaste-args

doc/wmmenugen.1

@@ -1,22 +1,93 @@
-.TH "wmmenugen" "1" "15 August 2011"
+.TH "wmmenugen" "1" "16 May 2015"
 .SH "NAME"
 \fBwmmenugen\fR \- Window Maker PropList menu generator
 .PP
 .SH "SYNOPSIS"
-.B wmmenugen \fI\-parser:<parser> fspec \fR[ fpsec ... \fR]
-\fR[\fI\-parser:<parser> fspec \fR[ fpsec ... \fR] ... \fR]
-.PP
+.B wmmenugen
+.RI [ options ...]
+.BI \-parser= <name>
+.IR fspec " [" fspec "...]"
+.BI \fR[\fP\-parser= <name>
+.IR fspec " [" fspec "...]...]"
 .SH "DESCRIPTION"
-\fBwmmenugen \fR\- Window Maker PropList menu generator
-.PP
+.B wmmenugen
+generates a menu in the
+.I PropList
+format for Window Maker from the input file
+.IR fspec .
+In the case where
+.I fspec
+is a directory instead of a file, then
+.B wmmenugen
+will read all the files present in the hierarchy of this directory.
 .SH "OPTIONS"
 .TP
-.B \-parser
-\fRspecify the parser. Known parsers are xdg and wmconfig.
+.BR \-\-help ", " \-h
+print a help message with the list of options
 .TP
-.B \-fspec
-\fRspecify the file.
+.B \-parser
+specify the format of the file to be parsed
+.TP
+.B \-\-version
+print the version of Window Maker from which the program comes
+.SH "PARSERS"
+.B wmmenugen
+supports these file formats for input files:
+.TP
+.I wmconfig
+the format of the menu generation tool for X of the same name
+.TP
+.I xdg
+the format of the menu specification as defined by the
+.I FreeDesktop
+standard, currently at version 1.1
+.SH "RETURN VALUE"
+The exit status from the
+.B wmmenugen
+command provides information for the caller:
+.TP
+.B 0
+when the
+.I PropList
+menu was successfully generated on
+.IR stdout .
+.TP
+.B 1
+when a
+.I fspec
+caused a problem (non readable file, ...)
+.TP
+.B 2
+the arguments of the command line where not recognised
+.TP
+.B 3
+the program met an unexpected menu structure;
+you probably want to look at the section
+.B BUGS
+below.
+.SH "BUGS"
+If you get the exit status
+.B 3
+with the unclear error message about
+.IR "unprocessed levels on the stack" ,
+you encountered a limitation of
+.BR wmmenugen .
+It would be a good idea to prepare an archive with the files incriminated and submit them to the
+mailing list (wmaker-dev@lists.windowmaker.org) with you command line, so the team can work on
+improving the behaviour of the program on this case.
+.SH "SEE ALSO"
+.BR wmgenmenu (1),
+the tool to generate a default menu
 .PP
+the
+.I Wmconfig
+program can be found at:
+<http://www.arrishq.net/index.html>
+.PP
+the
+.I xdg
+specification can be found at:
+<http://standards.freedesktop.org/menu-spec/menu-spec-1.1.html>
 .SH "AUTHOR"
 wmmenugen is a part of Window Maker. It was written by Tamas TEVESZ.
 .PP