diff --git a/.gitignore b/.gitignore index ab8b81ca..fc8c07a2 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ version.h version man/*.gz +Documentation/*.gz btrfs btrfs.static btrfs-debug-tree diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 00000000..bf386172 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,91 @@ +# Guard against environment variables +MAN8_TXT = + +# Top level commands +MAN8_TXT += btrfs.txt +#MAN8_TXT += btrfsck.txt +#MAN8_TXT += btrfs-convert.txt +#MAN8_TXT += btrfs-debug-tree.txt +#MAN8_TXT += btrfs-find-root.txt +#MAN8_TXT += btrfs-image.txt +#MAN8_TXT += btrfs-map-logical.txt +#MAN8_TXT += btrfs-show-super.txt +#MAN8_TXT += btrfstune.txt +#MAN8_TXT += btrfs-zero-log.txt +#MAN8_TXT += fsck.btrfs.txt +#MAN8_TXT += mkfs.btrfs.txt + +# Sub commands for btrfs +#MAN8_TXT += btrfs-subvolume.txt +#MAN8_TXT += btrfs-filesystem.txt +#MAN8_TXT += btrfs-balance.txt +#MAN8_TXT += btrfs-device.txt +#MAN8_TXT += btrfs-scrub.txt +#MAN8_TXT += btrfs-check.txt +#MAN8_TXT += btrfs-rescue.txt +#MAN8_TXT += btrfs-inspect-internal.txt +#MAN8_TXT += btrfs-send.txt +#MAN8_TXT += btrfs-receive.txt +#MAN8_TXT += btrfs-quota.txt +#MAN8_TXT += btrfs-replace.txt +#MAN8_TXT += btrfs-dedup.txt + +MAN_TXT = $(MAN8_TXT) +MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) +DOC_MAN8 = $(patsubst %.txt,%.8,$(MAN8_TXT)) +GZ_MAN8 = $(patsubst %.txt,%.8.gz,$(MAN8_TXT)) + +mandir ?= $(prefix)/share/man +man8dir = $(mandir)/man8 + +ASCIIDOC = asciidoc +ASCIIDOC_EXTRA = +MANPAGE_XSL = manpage-normal.xsl +XMLTO = xmlto +XMLTO_EXTRA = +XMLTO_EXTRA = -m manpage-bold-literal.xsl +GZIP = gzip +INSTALL ?= install +RM ?= rm -f +BTRFS_VERSION = $(shell sed -n 's/.*BTRFS_BUILD_VERSION "Btrfs \(.*\)"/\1/p'\ + ../version.h) + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifndef V + QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; + QUIET_XMLTO = @echo ' ' XMLTO $@; + QUIET_GZIP = @echo ' ' GZIP $@; + QUIET_STDERR = 2> /dev/null + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + +all: man +man: man8 +man8: $(GZ_MAN8) + +install: install-man + +install-man: man + $(INSTALL) -d -m 755 $(DESTDIR)$(man8dir) + $(INSTALL) -m 644 $(GZ_MAN8) $(DESTDIR)$(man8dir) + +clean: + $(RM) *.xml *.xml+ *.8 *.8.gz + +%.8.gz : %.8 + $(QUIET_GZIP)$(GZIP) -n -c $< > $@ + +%.8 : %.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +%.xml : %.txt asciidoc.conf + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ + $(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \ + -o $@+ $< && \ + mv $@+ $@ diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 00000000..313f1857 --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,42 @@ +## linkbtrfs: macro +# +# Usage: linkbtrfs:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show Btrfslink as: (
); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?Plinkbtrfs):(?P\S*?)\[(?P.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +backslash=\ +tilde=~ +apostrophe=' +backtick=` +litdd=-- + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +Btrfs +{btrfs_version} +Btrfs Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/Documentation/btrfs.txt b/Documentation/btrfs.txt new file mode 100644 index 00000000..c9bed702 --- /dev/null +++ b/Documentation/btrfs.txt @@ -0,0 +1,117 @@ +btrfs(8) +======== + +NAME +---- +btrfs - control a btrfs filesystem + +SYNOPSIS +-------- +'btrfs' [] + +DESCRIPTION +----------- +'btrfs' 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 'btrfs sub snaps' instead of +'btrfs subvolume snapshot'. +But 'btrfs file s' is not allowed, because 'file s' may be interpreted +both as 'filesystem show' and as 'filesystem sync'. + +If a command is terminated by '--help', the detailed help is showed. +If the passed command matches more commands, +detailed help of all the matched commands is showed. For example +'btrfs dev --help' shows the help of all 'device*' commands. + +COMMANDS +-------- +'subvolume':: + Create/delete/list/manage btrfs subvolume. + + See `btrfs-subvolume`(8) for details. + +'filesystem':: + Manage a btrfs filesystem, including label setting/sync and so on. + + See `btrfs-filesystem`(8) for details. + +'[filesystem] balance':: + Balance btrfs filesystem chunks across single or several devices. + + See `btrfs-balance`(8) for details. + +'device':: + Manage devices managed by btrfs, including add/delete/scan and so + on. + + See `btrfs-device`(8) for details. + +'scrub':: + Scrub a btrfs filesystem. + + See `btrfs-scrub`(8) for details. + +'check':: + Do off-line check on a btrfs filesystem. + + See `btrfs-check`(8) for details. + +'rescue':: + Try to rescue damaged btrfs filesystem. + + See `btrfs-rescue`(8) for details. + +'restore':: + Manage a btrfs filesystem, including label setting/sync and so on. + + See `btrfs-restore`(8) for details. + +'inspect-internal':: + Debug tools for developers/hackers. + + See `btrfs-inspect-internal`(8) for details. + +'send':: + Send subvolume data to stdout/file for backup and etc. + + See `btrfs-send`(8) for details. + +'receive':: + Receive subvolume data from stdin/file for restore and etc. + + See `btrfs-receive`(8) for details. +'quota':: + Manage quota on btrfs filesystem like enabling/rescan and etc. + + See `btrfs-quota`(8) and `btrfs-qgroup`(8) for details. + +'qgroup':: + Manage quota group(qgroup) for btrfs filesystem. + + See `btrfs-qgroup`(8) for details. + +'replace':: + Replace btrfs devices. + + See `btrfs-replace`(8) for details. + +EXIT STATUS +----------- +'btrfs' returns a zero exist status if it succeeds. Non zero is returned in +case of failure. + +AVAILABILITY +------------ +'btrfs' 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. + +SEE ALSO +-------- +`mkfs.btrfs`(8), `ionice`(1), +`btrfs-subvolume`(8), +`btrfs-filesystem`(8), +`btrfs-balance`(8), +`btrfs-device`(8), +`btrfs-scrub`(8), +`btrfs-check`(8), +`btrfs-rescue`(8), +`btrfs-restore`(8), +`btrfs-inspect-internal`(8), +`btrfs-send`(8), +`btrfs-receive`(8), +`btrfs-quota`(8), +`btrfs-qgroup`(8), +`btrfs-replace`(8), diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 00000000..a264fa61 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + sp + + + + + + + + br + + + diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 00000000..608eb5df --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ + + + + + + + fB + + + fR + + + diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 00000000..a48f5b11 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ + + + + + + +\ +. + +