mirrors/qemu
0
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2025-01-09 23:23:40 +08:00
Code Issues Packages Projects Releases Wiki Activity
b3175081a1
qemu/docs/system/qemu-block-drivers.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

25 lines
369 B
ReStructuredText
Raw Normal View History

docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
:orphan:
docs: standardize book titles to === with overline Documents within a Sphinx manual are separate files and therefore can use different conventions for headings. However, keeping some consistency is useful so that included files are easy to get right. This patch uses a standard heading format for book titles, so that it is obvious when a file sits at the top level toctree of a book or man page. The heading is irrelevant for man pages, but keep it consistent as well. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-09-07 21:58:12 +08:00
============================
qemu-block-drivers: Convert to rST The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
2020-01-23 23:22:40 +08:00
QEMU block drivers reference
============================
docs/system: standardize man page sections to --- with overline Man pages in docs/system use file inclusion heavily. Use headings with overlines in the main files, so that the same included file work well from both manuals and man pages. This style of heading is a bit more heavy-weight, so it is not used by the other man pages in interop/ and tools/. If in the future they are changed to use include files, for example to avoid having sections named "synopsis" or "description", they can switch to --- with overline as well. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-09-07 23:33:27 +08:00
--------
docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
Synopsis
--------
qemu-block-drivers: Convert to rST The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
2020-01-23 23:22:40 +08:00
docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
QEMU block driver reference manual
qemu-block-drivers: Convert to rST The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
2020-01-23 23:22:40 +08:00
docs/system: standardize man page sections to --- with overline Man pages in docs/system use file inclusion heavily. Use headings with overlines in the main files, so that the same included file work well from both manuals and man pages. This style of heading is a bit more heavy-weight, so it is not used by the other man pages in interop/ and tools/. If in the future they are changed to use include files, for example to avoid having sections named "synopsis" or "description", they can switch to --- with overline as well. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-09-07 23:33:27 +08:00
-----------
docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
Description
-----------
qemu-block-drivers: Convert to rST The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
2020-01-23 23:22:40 +08:00
docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
.. include:: qemu-block-drivers.rst.inc
qemu-block-drivers: Convert to rST The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
2020-01-23 23:22:40 +08:00
docs/system: standardize man page sections to --- with overline Man pages in docs/system use file inclusion heavily. Use headings with overlines in the main files, so that the same included file work well from both manuals and man pages. This style of heading is a bit more heavy-weight, so it is not used by the other man pages in interop/ and tools/. If in the future they are changed to use include files, for example to avoid having sections named "synopsis" or "description", they can switch to --- with overline as well. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-09-07 23:33:27 +08:00
--------
docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
See also
--------
qemu-block-drivers: Convert to rST The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
2020-01-23 23:22:40 +08:00
docs/system: put qemu-block-drivers body in an included file This removes the "only" directives, and lets us use the conventional "DESCRIPTION" section in the manpage. This temporarily drops the qemu-block-drivers documentation from the system manual, but it will be put back (in the right place in the toctree) in a later commit. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-14-peter.maydell@linaro.org Message-id: 20200226113034.6741-14-pbonzini@redhat.com Reviewed-by: Peter Maydell <peter.maydell@linaro.org> [PMM: Added commit message note about temporarily losing qemu-block-drivers from the system manual] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 23:35:59 +08:00
The HTML documentation of QEMU for more precise information and Linux
user mode emulator invocation.
Reference in New Issue Copy Permalink