po-man: Update the example man page

man-common/manpage-stub.adoc

@@ -1,3 +1,17 @@
+//po4a: entry man manual
+////
+Please treat this file as a real man page! We provide it only to show how
+things should be formatted. Besides this example file, see the existing .adoc
+files for many more formatting options.
+The first line above is a hint for po4a that the :man manual: entry needs
+to be translated.
+As you can see here, use //// to write comment blocks. For a single comment
+line, just use //.
+Please don't wrap lines within a paragraph. Our translation tool po4a behaves
+a bit unpredictable in such cases.
+We also urgently recommend to test the creation of the *roff file to see possible
+issues.
+////
 = foobar(1)
 :doctype: manpage
 :man manual: User commands
@@ -11,7 +25,7 @@ foobar - do nothing
 
 == SYNOPSIS
 
-*foobar* _options file_
+*foobar* _options_ _file_
 
 == DESCRIPTION
 
@@ -19,11 +33,18 @@ Describe *foobar* briefly.
 
 == OPTIONS
 
+//Format options bold and values italic: 
+*-o*, *--option* _value_::
+This option has a value.
++
+For empty lines within a desription (to keep the indentation) you can use the "plus" character at the beginning of an otherwise empty line.
+
+//Last but not least, don't forget the common options:
 *-V*, *--version*::
-  Display version information and exit.
+Display version information and exit.
 
 *-h*, *--help*::
-  Display help text and exit.
+Display help text and exit.
 
 == NOTES
 
@@ -31,16 +52,15 @@ Put your notes here which don't match any other paragraph.
 
 == AUTHORS
 
-....
-John Doe <john.doe@example.com>
-....
+// Format mail addresses as follows:
+mailto:john.doe@example.com[John Doe]
+// If you need more than one address, use a comma-separated list or leave empty lines between the entries.
 
-[[see_also]]
 == SEE ALSO
 
 *foo*(1),
 *bar*(1)
-
+ 
 include::../man-common/bugreports.adoc[]
 
 include::../man-common/footer.adoc[]