From aa8bba1e2c99eb895c7e43f5092e4bf56d68d9c5 Mon Sep 17 00:00:00 2001 From: Goffredo Baroncelli Date: Sat, 16 Jul 2011 11:11:08 +0200 Subject: [PATCH 09/35] Add the header/footer/introduction of the man page. 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 1def354..d2f6d4d 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 --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\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\i + * + * Select chunks which have data on device ID \I\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\i,\I\i + * + * Select chunks which have btrfs-internal virtual addresses within the + * range \I\i (inclusive) to \I\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,\i. + * + * \Bdrange\b=\I\i,\I\i + * + * Select chunks which contain data in the address range \I\i + * (inclusive) to \I\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 { -- 1.7.6.233.gd79bc