From cde653e0f50e638ace022041d1bdc98a8c82c94d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20Bl=C3=A4ttermann?= Date: Mon, 29 Mar 2021 19:45:19 +0200 Subject: [PATCH] po-man: Update the example man page --- man-common/manpage-stub.adoc | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/man-common/manpage-stub.adoc b/man-common/manpage-stub.adoc index f1b745732..1da0a8981 100644 --- a/man-common/manpage-stub.adoc +++ b/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 -.... +// 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[]