Make it possible to select sphinx doc generator instead of asciidoc so
we don't have two makefiles for that. It's still a bit crude and does
not support installing the files.
The required package is python-Sphinx (or similar name), built by
'sphinx-build'.
Configure:
$ ASCIIDOC_TOOL=sphinx ./configure
...
doc generator: sphinx
...
Generate:
$ cd Documentation/
$ make man
$ make html
$ make info # yes we can have info pages too
There are several more targets provided by sphinx, run 'make' to list
them.
Signed-off-by: David Sterba <dsterba@suse.com>
XMLTO_EXTRA is defined above, and then appended to if `asciidoctor` is
used to generate the manual pages. The second definition was clearing
the value of this variable, which caused builds with asciidoctor to
fail with:
```
[XMLTO] btrfs-ioctl.3
xmlto: /usr/src/packages/user/btrfs-progs/src/btrfs-progs-v5.4/Documentation/btrfs-ioctl.xml does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
validity error : no DTD found!
Document /usr/src/packages/user/btrfs-progs/src/btrfs-progs-v5.4/Documentation/btrfs-ioctl.xml does not validate
make[1]: *** [Makefile:114: btrfs-ioctl.3] Error 13
```
Fixes: 669f56177 ("btrfs-progs: docs: use docbook5 backend for asciidoctor")
Signed-off-by: A. Wilcox <AWilcox@Wilcox-Tech.com>
Signed-off-by: David Sterba <dsterba@suse.com>
Switch backend to docbook5 for asciidoctor and disable validation as v5
does not use DTBs.
Pull-request: #203
Issue: #201
Signed-off-by: Dimitri John Ledkov <xnox@ubuntu.com>
Signed-off-by: David Sterba <dsterba@suse.com>
There's a regular manual page that matches the file glob mask *.8 so we
have to be more careful and remove only the known intermediate files.
Signed-off-by: David Sterba <dsterba@suse.com>
The manual pages are not compressed anymore and we can remove gzip from
build dependencies and build steps.
Signed-off-by: David Sterba <dsterba@suse.com>
Build systems do not typically compress man pages when installing them.
This is generally left to distro packaging mechanisms, which may end up
recompressing them using a different compressor.
Author: Mike Gilbert <floppym@gentoo.org>
Signed-off-by: David Sterba <dsterba@suse.com>
In order to install uncompressed manual pages we can't use the symlink
for the deprecated btrfsck page. Replace it by source command provided
by the manual page format.
Old: man8/btrfsck.8.gz (symlink)
New: man8/btrfsck.8 (file)
Reported-by: Mike Gilbert <floppym@gentoo.org>
Signed-off-by: David Sterba <dsterba@suse.com>
Its function has been superseded by btrfs inspect-internal show-super.
Furthermore the tools is currently not built by default. Just remove it.
Deprecated since 4.8.
Issue: #97
Signed-off-by: Nikolay Borisov <nborisov@suse.com>
Signed-off-by: David Sterba <dsterba@suse.com>
Its function has been subsumed by "btrfs rescue zero-log". Remove its
source file and adjust make/tests soruces accordingly.
Deprecated since 4.0.
Issue: #97
Signed-off-by: Nikolay Borisov <nborisov@suse.com>
Signed-off-by: David Sterba <dsterba@suse.com>
There is already a replacement in the face of btrfs inspect-internal
dump-tree. And this command is just a simple wrapper around it. Just
remove it and adjust the show-blocks script to call the main btrfs
binary to achieve the same effect.
Informally deprecated since 4.4.
Issue: #97
Signed-off-by: Nikolay Borisov <nborisov@suse.com>
Signed-off-by: David Sterba <dsterba@suse.com>
We've been using asciidoc that's written in python2, which is going to
be phased out and deprecated next year. There's a replacement,
asciidoctor. Add a configure-time detection which tool is available,
update Documentation/Makefile.in.
The original asciidoc tool is still preferred as it produces slightly
better output. The file asciidoc.conf does not have a direct equivalten
in asciidoct and would need to be replaced by extension written in ruby.
The differences:
- the <literal> are not automatically underlined and are less visible in
the generated manual page, but it's still acceptable
- the inline CSS for the html output looks subjectively worse, is less
compact and colourful
Issue: #89
Signed-off-by: David Sterba <dsterba@suse.com>
Start documenting the ioctl interface to btrfs. The overall structure
should be settled, the formatting of the ioctl description may change in
the future, newly added ioctl descriptions should follow the examples of
BTRFS_IOC_SUBVOL_CREATE.
The document is not finished yet and will not be installed until most of
ioctls' details are filled in.
Signed-off-by: David Sterba <dsterba@suse.com>
Copy the functionality of standalone btrfs-zero-log to the main tool.
Delete man page for btrfs-zero-log and copy the relevant parts into
btrfs-rescue(8). The standalone utility will be removed later.
Signed-off-by: David Sterba <dsterba@suse.cz>
A few minor benefits:
* editors set highliting according to the extensions
* web access to the git repository (github) renders the .asciidoc
files:
* we can link to them from the wiki
* the files are editable via browser and such editations can be
submitted for merge easily
Signed-off-by: David Sterba <dsterba@suse.cz>
David Sterba
A. Wilcox
Dimitri John Ledkov
Mike Gilbert
Nikolay Borisov
Adam Borowski
David Sterba