There was a workaround for asciidoc/xmlto build because page btrfs.5 and
btrfs.8 used the same intermediate file. To avoid clash for the section
5 page it is part of the name, this is still needed, but for sphinx we
can use the final name as it will get the right suffix. This affects
only the generated manual pages.
Signed-off-by: David Sterba <dsterba@suse.com>
Update sphinx build so that by default it now builds the manual pages,
in quiet mode. 'make html' builds the html, other sphinx targets are
available, see 'make help'. Installation now works as well.
Note: sphinx is still conditional and must be selected by
ASCIIDOOC_TOOL=sphinx ./configure
Signed-off-by: David Sterba <dsterba@suse.com>
The max width of the page is set to 800px, that renders of commands and
output in a small box requiring a scrollbar. Increase the limit to
1200px. Also update some subvoulme related text.
Signed-off-by: David Sterba <dsterba@suse.com>
The feature pages share the contents with the manual page section 5 so
put the contents to separate files. Progress: 2/3.
Signed-off-by: David Sterba <dsterba@suse.com>
The feature pages share the contents with the manual page section 5 so
put the contents to separate files.
Signed-off-by: David Sterba <dsterba@suse.com>
At this point it's not clear what exactly needs the indices and they
appear in the left column with list of index pages which is a bit
confusing.
Signed-off-by: David Sterba <dsterba@suse.com>
[BUG]
There is a bug report that a corrupted key type (expected
UUID_KEY_SUBVOL, has EXTENT_ITEM) causing newer kernel to reject a
mount.
Although the root cause is not determined yet, with roll out of v5.11
kernel to various distros, such problem should be prevented by
tree-checker, no matter if it's hardware problem or not.
And older kernel with "-o uuid_rescan" mount option won't help, as
uuid_rescan will only delete items with
UUID_KEY_SUBVOL/UUID_KEY_RECEIVED_SUBVOL key types, not deleting such
corrupted key.
[FIX]
To fix such problem we have to rely on offline tool, thus there we
introduce a new rescue tool, clear-uuid-tree, to empty and then remove
uuid tree.
Kernel will re-generate the correct uuid tree at next mount.
Reported-by: S. <sb56637@gmail.com>
Signed-off-by: Qu Wenruo <wqu@suse.com>
Signed-off-by: David Sterba <dsterba@suse.com>
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>
All long command line options in the html target render as a single
character which is confusing and wrong as we expect that to be '--'.
Disable it.
Signed-off-by: David Sterba <dsterba@suse.com>
Cell spanning is not supported for manual page target, so add separate
columns for the redundancy numbers.
Signed-off-by: David Sterba <dsterba@suse.com>
The asciidoc format needs to be tweaked but otherwise is basically the
same. Changes:
- bold text is ** **
- italics is * *
- NOTE is directive .. note
- definition list is simple indented block after the term
- section NAME in the manual page is generated from date in
conf.py:man_pages
- new page has to be added to the index
To do:
- references to other manual pages, will be RST native linking once all
the pages are converted
The output is in Documentation/_build/man and the format is visually not
much different from what is generated by asciidoc.
Signed-off-by: David Sterba <dsterba@suse.com>
Add basic config and build files for sphinx. The long term plan is to
convert all asciidoc sources to ReST and host majority of wiki contents,
and maybe more.
Build:
$ cd Documentation/
$ make -f Makefile.sphinx html
The result is in Documentation/_build/html.
Signed-off-by: David Sterba <dsterba@suse.com>
