If libiscsi is disabled in the build, the man page shouldn't contain
information on how to construct iscsi URLs etc.

This patch is best viewed with whitespace changes ignored.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 docs/system/device-url-syntax.rst.inc | 60 ++++++++++++++-------------
 qemu-options.hx                       |  9 ++--
 2 files changed, 37 insertions(+), 32 deletions(-)

diff --git a/docs/system/device-url-syntax.rst.inc b/docs/system/device-url-syntax.rst.inc
index 7dbc525fa8..c882bce418 100644
--- a/docs/system/device-url-syntax.rst.inc
+++ b/docs/system/device-url-syntax.rst.inc
@@ -1,47 +1,49 @@
 
 In addition to using normal file images for the emulated storage
-devices, QEMU can also use networked resources such as iSCSI devices.
-These are specified using a special URL syntax.
+devices, QEMU can also use networked resources. These are specified using a
+special URL syntax.
 
-``iSCSI``
-   iSCSI support allows QEMU to access iSCSI resources directly and use
-   as images for the guest storage. Both disk and cdrom images are
-   supported.
+.. only:: not DISABLE_LIBISCSI
 
-   Syntax for specifying iSCSI LUNs is
-   "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
+    ``iSCSI``
+       iSCSI support allows QEMU to access iSCSI resources directly and use
+       as images for the guest storage. Both disk and cdrom images are
+       supported.
 
-   By default qemu will use the iSCSI initiator-name
-   'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
-   the command line or a configuration file.
+       Syntax for specifying iSCSI LUNs is
+       "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
 
-   Since version QEMU 2.4 it is possible to specify a iSCSI request
-   timeout to detect stalled requests and force a reestablishment of the
-   session. The timeout is specified in seconds. The default is 0 which
-   means no timeout. Libiscsi 1.15.0 or greater is required for this
-   feature.
+       By default qemu will use the iSCSI initiator-name
+       'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
+       the command line or a configuration file.
 
-   Example (without authentication):
+       Since version QEMU 2.4 it is possible to specify a iSCSI request
+       timeout to detect stalled requests and force a reestablishment of the
+       session. The timeout is specified in seconds. The default is 0 which
+       means no timeout. Libiscsi 1.15.0 or greater is required for this
+       feature.
 
-   .. parsed-literal::
+       Example (without authentication):
 
-      |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \\
-                       -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \\
-                       -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+       .. parsed-literal::
 
-   Example (CHAP username/password via URL):
+          |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \\
+                           -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \\
+                           -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
 
-   .. parsed-literal::
+       Example (CHAP username/password via URL):
 
-      |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
+       .. parsed-literal::
 
-   Example (CHAP username/password via environment variables):
+          |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
 
-   .. parsed-literal::
+       Example (CHAP username/password via environment variables):
+
+       .. parsed-literal::
 
-      LIBISCSI_CHAP_USERNAME="user" \\
-      LIBISCSI_CHAP_PASSWORD="password" \\
-      |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+          LIBISCSI_CHAP_USERNAME="user" \\
+          LIBISCSI_CHAP_PASSWORD="password" \\
+          |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
 
 ``NBD``
    QEMU supports NBD (Network Block Devices) both using TCP protocol as
diff --git a/qemu-options.hx b/qemu-options.hx
index ba3ae6a42a..4d3721f1ea 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1363,7 +1363,7 @@ SRST
         If the filename contains comma, you must double it (for instance,
         "file=my,,file" to use file "my,file").
 
-        Special files such as iSCSI devices can be specified using
+        Special files such as for network protocols can be specified using
         protocol specific URLs. See the section for "Device URL Syntax"
         for more information.
 
@@ -1831,8 +1831,11 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
 
 SRST
-``-iscsi``
-    Configure iSCSI session parameters.
+
+.. only:: not DISABLE_LIBISCSI
+
+    ``-iscsi``
+        Configure iSCSI session parameters.
 ERST
 
 DEFHEADING()
-- 
2.31.1

On Mon, 31 Jan 2022 at 17:33, Kevin Wolf <kwolf@redhat.com> wrote:
>
> If libiscsi is disabled in the build, the man page shouldn't contain
> information on how to construct iscsi URLs etc.
>
> This patch is best viewed with whitespace changes ignored.
>
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---

> -``iSCSI``
> -   iSCSI support allows QEMU to access iSCSI resources directly and use
> -   as images for the guest storage. Both disk and cdrom images are
> -   supported.
> +.. only:: not DISABLE_LIBISCSI

Unfortunately the Sphinx "only::" tag is unusably broken by design.
It doesn't work the way you might expect (similar to ifdef, making
the docs be built as if the markup disabled by only:: was not
present in the source rst files). Instead it filters out generated
doctree nodes very late. The effect is that documentation that you
try to suppress with an 'only' directive will still show up in
the table of contents, index and search.

Upstream bug, closed 'wontfix':
https://github.com/sphinx-doc/sphinx/issues/1420

I ran into this when I was looking at whether there were nicer ways
to structure how we generate some of our manpages etc. Unfortunately
my conclusion was that the only safe approach was to avoid use
of the 'only::' directive entirely :-(

thanks
-- PMM

Am 31.01.2022 um 19:57 hat Peter Maydell geschrieben:
> On Mon, 31 Jan 2022 at 17:33, Kevin Wolf <kwolf@redhat.com> wrote:
> >
> > If libiscsi is disabled in the build, the man page shouldn't contain
> > information on how to construct iscsi URLs etc.
> >
> > This patch is best viewed with whitespace changes ignored.
> >
> > Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> > ---
> 
> > -``iSCSI``
> > -   iSCSI support allows QEMU to access iSCSI resources directly and use
> > -   as images for the guest storage. Both disk and cdrom images are
> > -   supported.
> > +.. only:: not DISABLE_LIBISCSI
> 
> Unfortunately the Sphinx "only::" tag is unusably broken by design.
> It doesn't work the way you might expect (similar to ifdef, making
> the docs be built as if the markup disabled by only:: was not
> present in the source rst files). Instead it filters out generated
> doctree nodes very late. The effect is that documentation that you
> try to suppress with an 'only' directive will still show up in
> the table of contents, index and search.
> 
> Upstream bug, closed 'wontfix':
> https://github.com/sphinx-doc/sphinx/issues/1420
> 
> I ran into this when I was looking at whether there were nicer ways
> to structure how we generate some of our manpages etc. Unfortunately
> my conclusion was that the only safe approach was to avoid use
> of the 'only::' directive entirely :-(

Hm, that's very disappointing. :-(

Does it affect anything that is used in man pages, though? Otherwise I
guess we could have something like ::only (not man) or (not DISABLE*) to
make things conditional at least in the man pages even if we can't in
HTML.

Or I guess the alternative would be manually preprocessing docs (maybe
even just with cpp) before feeding them to sphinx...

In fact, a large part of the man pages is already preprocessed by
hxtool. But obviously, the changes I make in this patch are outside of
it for the most part.

Kevin