[PATCH 2/6] Add the header/footer/introduction of the man page.

[Goffredo Baroncelli <kreijack@libero.it>]

From: Goffredo Baroncelli <kreijack@inwind.it>

Add the header/footer/introduction of the man page. There is also an
introduction to the syntax recognized by the tool helpextract to format
the information.
---
 btrfs.c |  176 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 176 insertions(+), 0 deletions(-)

diff --git a/btrfs.c b/btrfs.c
index 67d6f6f..98abb6c 100644
--- a/btrfs.c
+++ b/btrfs.c
@@ -26,6 +26,182 @@
 #define BASIC_HELP 0
 #define ADVANCED_HELP 1
 
+/**
+ ** The comments below are used to make the man page
+ **
+ ** There are:
+ ** - Header, 
+ ** - The synopsis title section (the content are extracted from other 
+ **   comments)
+ ** - The synopsis format, which is a template: the '%s' is replaced by 
+ **   the command line "syntax"
+ ** - The btrfs introduction section
+ ** - The btfrs command title section (the content are extracted from other 
+ **   comments)
+ ** - The command format, which is a template: the first '%s' is replaced by 
+ **   the command line "syntax"; the ssecond '%s' is replaced by the
+ **   detailed descritpion
+ ** - The "notes" section 
+ ** - The footer (currentli empty)
+ **
+ ** The comments are the following sytax [replace '{slash}' with '/']
+ **
+ ** If the comment starts with '{slash}**** text: ', then all the text below
+ ** are used until ' ***'. The text after 'text: ' are the key used to
+ ** index teh content. 
+ **
+ ** If the comment starts with '{slash}**** man: ', then below the comment are
+ ** divided in three section:
+ ** 1) (one line) command line syntax
+ ** 2) (multiple line) short description (showed in the command "btrfs help")
+ ** 3) (multiple line) detailled description (showed in the man page and
+ **    command "btrfs <subcommand> --help")
+ ** The text after 'man: ' are the key used to index the content. This must
+ ** be equal to the subcommand which the info is referred.
+ ** 
+ ** Below the escape sequence which may be used in the text
+ **
+ **	     escape      troff
+ **          sequence    command
+ **
+ **                \B	 \fB         bold 
+ **                \b	 \fP         end bold 
+ **                \I	 \fI         italic 
+ **                \i	 \fP         end italic 
+ **                \c	 .\"         comment 
+ **                \P	 .PP         start paragraph 
+ **                \p	 .TP         indented paragraph 
+ **                \h	 .SH         header 
+ **                \d	 .BR         bold regular 
+ **                \e	 .B          bold 
+ **                \t	 .IP         indented paragraph 
+ **                \w	 .RS         move the left margin 
+ **                \q	 .RE         move the left margin back
+ **		   \-    \-          minus (it *must* escaped )
+ **
+ **
+ **/
+
+
+/**** text: man btrfs header
+ * .TH BTRFS 8 "" "btrfs" "btrfs"
+ * .\"
+ * .\" Man page for the "btrfs" tool 
+ * .\"
+ * .SH NAME
+ * btrfs \- control a btrfs filesystem
+ ****/
+
+/**** text: man btrfs synopsis
+ * .SH SYNOPSIS
+ ****/
+
+/**** text: man btrfs synopsis format
+ * \fB%s\fP
+ * .PP
+ ****/
+
+/**** text: btrfs introduction
+ * \h DESCRIPTION
+ * \Bbtrfs\b is used to control the filesystem and the files and directories 
+ * stored. It is the tool to create or destroy a snapshot or a subvolume for 
+ * the filesystem, to defrag a file or a directory, flush the data to the disk,
+ * to resize the filesystem, to scan the device.
+ * 
+ * It is possible to abbreviate the commands unless the commands  are ambiguous.
+ * For example: it is possible to run
+ * \Ibtrfs sub snaps\i instead of \Ibtrfs subvolume snapshot\i. But \Ibtrfs 
+ * file s\i is not allowed, because \Ifile s\i may be interpreted both as
+ * \Ifilesystem show\i and as \Ifilesystem sync\i.  
+ * 
+ * If a command is terminated by \I--help\i, the detailed help is showed. 
+ * If the passed command matches more commands, detailed help of all the 
+ * matched commands is showed. For example \Ibtrfs dev --help\i shows the 
+ * help of all \Idevice*\i commands.
+ ****/
+
+/**** text: man btrfs command format
+ *
+ * .TP
+ * %s%s
+ ****/
+
+/**** text: man btrfs commands
+ * .SH COMMANDS
+ * .TP
+ */
+
+/**** text: btrfs notes
+ * \h BALANCE FILTERS
+ * 
+ * With balance filters, it is possible to perform a balance operation on
+ * only a subset of the available chunks. Filters are specified with the
+ * \B--filter\b option of \Bbtrfs filesystem balance\b or \Bbtrfs
+ * balance start\b. Multiple filters may be given, either with multiple
+ * \B--filter\b options, or in a colon-separated list. When multiple
+ * filters are given, only the chunks meeting all of the selection
+ * critera are balanced. Help on the avaialble filters can be obtained
+ * with \B--filter=help\b.
+ * 
+ * 
+ * \Btype\b=[\B~\b]\I<flagname>\i[\B,\b...]
+ * 
+ * Select only the chunks with the given type flag(s). Requiring a flag
+ * to be off can be specified with a \B~\b preceding the flag
+ * name. Flag names are:
+ * 
+ * \Bmeta\b, \Bdata\b, \Bsys\b for metadata, file data and system
+ * chunk types.
+ * 
+ * \Braid0\b, \Braid1\b, \Braid10\b, \Bdup\b for chunks of the
+ * given replication levels.
+ * 
+ * 
+ * \Bdevid\b=\I<n>\i
+ * 
+ * Select chunks which have data on device ID \I<n>\i. This can be
+ * used, for example, to reduplicate data in a mirrored configuration
+ * where one drive has been lost due to hardware failure.
+ * 
+ * 
+ * \Bvrange\b=\I<start>\i,\I<end>\i
+ * 
+ * Select chunks which have btrfs-internal virtual addresses within the
+ * range \I<start>\i (inclusive) to \I<end>\i (exclusive). Given the
+ * address of the last chunk moved, this filter can be used to restart a
+ * cancelled or interrupted balance operation, by supplying a range of
+ * \I0,<chunkaddr+1>\i.
+ * 
+ * \Bdrange\b=\I<start>\i,\I<end>\i
+ * 
+ * Select chunks which contain data in the address range \I<start>\i
+ * (inclusive) to \I<end>\i (exclusive) on \Iany\i block device in
+ * the filesystem. Can be mixed with the \Bdevid\b filter to select
+ * chunks in a given address range on a specific device.
+ * 
+ * \h EXIT STATUS
+ * \Bbtrfs\b returns a zero exist status if it succeeds. Non zero is returned in
+ * case of failure.
+ * 
+ * \h AVAILABILITY
+ * \Bbtrfs\b is part of btrfs-progs. Btrfs filesystem is currently under 
+ * heavy development, and not suitable for any uses other than benchmarking and
+ * review.
+ *
+ * Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+ * further details.
+ *
+ * \h SEE ALSO
+ * \Bmkfs.btrfs (8)\b
+ ****/
+
+/**** text: man btrfs footer
+ ****/
+
+
+
+
+
 typedef int (*CommandFunction)(int argc, char **argv);
 
 struct Command {