From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089093; cv=none; d=zohomail.com; s=zohoarc; b=X/Fop4tWOJrPDigEBx+DflsLjPBsDOq0Nc5M5PY2SCmuksNSO5tejxSDXrGm99Te0Z/KSZtXDbl1FPWRsOE+PcldYSNbmnapIUhbAo44r1rOqjwSWXF+1Vtocd5Oj7WQlJk8RGmeoMfPDgpT98OKWUZGmbh125iE0OyB7alON4s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089093; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=d+45d/+k1cuAYKwT/RK62hRxeNRk6rEMJI9YOmMNXaA=; b=koqfqAyHg0c6w+aDYSdjY2ysHLOoRkZ05QIa/ihysAYqBC+XOi4O3EbF5sGJmehEiOwDFEmig3c1+wQNmhYOqn/igSL0SJgNT7H1u8MhgOBzBl81NR5bgtDtqkjTXjqF3RWQxkuAMuYeedP1JkDeGh5KWIuAI9ik3YhD+o2QAVA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089093115670.9657206705882; Mon, 10 Aug 2020 12:51:33 -0700 (PDT) Received: from localhost ([::1]:60744 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DpT-0001gw-Bz for importer@patchew.org; Mon, 10 Aug 2020 15:51:31 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51010) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5DoS-0008Qn-82 for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:28 -0400 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:36584) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5DoP-0004ii-SH for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:27 -0400 Received: by mail-wr1-x442.google.com with SMTP id 88so9308498wrh.3 for ; Mon, 10 Aug 2020 12:50:25 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=d+45d/+k1cuAYKwT/RK62hRxeNRk6rEMJI9YOmMNXaA=; b=vKgLPyTgwo+coOD7UC26IcVWVqNI2WgCpCI7HP+ZsgI1N4AhjmEgv7Bd/Svj6axNDZ G8S2brDZjgEkYAyKsdoJtQyfy7M9AYI7c/G1ZGTzF4VL+OEXjzqcMfI1l5Lqk5v7t2U7 M7Sw0fMfmYTsm5FTeLfBR+8x8eAu0/kjitTj39V8DoVgpQH/tixSFaC/Nr1jCDnM7TAV kfS4O40CRptbAQEKCa1c5BSPXK9W/KVLn/Y/5omZ6RRS5EOsCm8CmpE89dgyffqfNMze XLUse5B6zzrKGZ7NawzCHs3CeOurSKFgF1gJBSp5wawuP93+8dM+faaUis/igSO8AlFx CARw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=d+45d/+k1cuAYKwT/RK62hRxeNRk6rEMJI9YOmMNXaA=; b=Lc7to5M1yTpHUzkZBWT/Q7R2lbxL9/+oXjxYMXqOdly5HvooAJfEecqO1Fxz1YyoEW 1D+WTHgza7JduAeEUvrLBFAZ7yDvrVwVFm9hneGue/us4F9yr+h71SYhGaBHCb72g9MO jAQgqN9w9Tx672ZxoL/hgN7Q7JAur6mbDmfUgMcv+s6kzh+7iyadc/KPO/WVHVG7xnS2 Ffw7dNYDdgwUkNCC95QPApeXkF4tR3oKU2hWuWJDfnH4hEQtS5ruMukln5QzkRAtuzc4 loYRi6dq+HjNWKb5/BNuw80m80mufbb/QqELT2E6eNgR8EBVY26BOHrZR1uw54VeFRX8 3SxA== X-Gm-Message-State: AOAM531Vng2QmTg7R5hZq+2NCNcaDunfBbtdoWZkOuG66EJcVPltOq4X +04Niv1qU1YALrBPkuNstPOZf6h1a0OmaQ== X-Google-Smtp-Source: ABdhPJzn+b4djID+Nple2PxPnX4iAtiu7fuzNidpZRPgF9Ri0+5Q6Z4UMUEV69D7kYoJYxUqpoTUrg== X-Received: by 2002:adf:eccc:: with SMTP id s12mr3153874wro.157.1597089023561; Mon, 10 Aug 2020 12:50:23 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 01/20] qapi/migration.json: Fix indentation Date: Mon, 10 Aug 2020 20:50:00 +0100 Message-Id: <20200810195019.25427-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::442; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x442.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Commits 6a9ad1542065ca0bd54c6 and 9004db48c080632aef23 added some new text to qapi/migration.json which doesn't fit the stricter indentation requirements imposed by the rST documentation generator. Reindent those lines to the new standard. Reviewed-by: Markus Armbruster Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- qapi/migration.json | 60 ++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index ea53b23dca9..e07c9c0f1aa 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -629,18 +629,18 @@ # Defaults to none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 9, where 0 means no compression, 1 means the be= st +# compression speed, and 9 means best compression rat= io which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 20, where 0 means no compression, 1 means the b= est +# compression speed, and 20 means best compression ra= tio which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # Since: 2.4 ## @@ -769,18 +769,18 @@ # Defaults to none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 9, where 0 means no compression, 1 means the be= st +# compression speed, and 9 means best compression rat= io which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 20, where 0 means no compression, 1 means the b= est +# compression speed, and 20 means best compression ra= tio which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # Since: 2.4 ## @@ -945,18 +945,18 @@ # Defaults to none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 9, where 0 means no compression, 1 means the be= st +# compression speed, and 9 means best compression rat= io which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 20, where 0 means no compression, 1 means the b= est +# compression speed, and 20 means best compression ra= tio which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # Since: 2.4 ## --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089179; cv=none; d=zohomail.com; s=zohoarc; b=U1gNKUfjTXDJKjKFVfN+dDcBMJlYTSVU4G4LrTe3YGEh0NCVR5FHZ4wj3XZiIkm+ozWvYCD+7Sar08K1vCYYtO2ALWyhpyxQpHWYtp1BmDCgFmU3AYmZQm9Fyi/T67Fz/MngdAG9ncPjmlzEgpQHkxLTLzqjnA1KK59vq7kuWfI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089179; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=t2oLRViBghCHbdyXmGQBzzRr3hni6nS3HlY20oR/lCA=; b=OU75fV4NGAHrICpFfv7iElsFd/Qk1QfuIny2IcInl18d936gqn0hNY2KLm1e/k4WJ7CTp1lfZrQGdROQqJR9cUQrtlwGLgszn1o0K0x+cX1rXoyG9YS3sKGTBxTB4R+OHdf5GDVJVqHVh8g24xaqETfWhtPnsf/bR8v+GpKKpvY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089179106150.7657125323649; Mon, 10 Aug 2020 12:52:59 -0700 (PDT) Received: from localhost ([::1]:41144 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dqr-00055d-VH for importer@patchew.org; Mon, 10 Aug 2020 15:52:57 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51024) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5DoT-0008Rp-8c for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:29 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:38485) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5DoR-0004iu-50 for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:28 -0400 Received: by mail-wr1-x444.google.com with SMTP id a14so9318214wra.5 for ; Mon, 10 Aug 2020 12:50:26 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=t2oLRViBghCHbdyXmGQBzzRr3hni6nS3HlY20oR/lCA=; b=nnNSPh56DmulajgCy67Z51y4DF+H/Ng+6HdBphytQ94EQo2s7ghCq2w4SRaS7VWqZi 6wFcUWsttT7r+VWam+e9kYu+wTzfTrSCjBZ6APLLZE0iakPepeWCCDYQb8x2GqV+SwjD uCpJy9qTS8FA+Y5/5q/niJNDp1V9PzkcMtzNRVKu3wI5d/HY7Fj496P52L0/KJumQ06e xeEZf3OgpHSkaOlXqbCsKcjoeiTiScn2+dzJj3J4D/C46Ro7+X0OKmCzOzE3/AmEiPvI jmFL9JCXmrFRrN9d0/NxDafxtYCi3v1/3kEJA7v3iJI6jiMQzAJaDXoP9fXXdMsv7UsR UnQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=t2oLRViBghCHbdyXmGQBzzRr3hni6nS3HlY20oR/lCA=; b=SGruFx2MfLUumMyvLqWPSQEU5BOkUSPnmjzNZGWPpZFj1unltNOj/UTz1iewKCClOb zaQm+HGX85ml2pZ5R41jyIrte/yvGs3CdGvLtOlanTa5SP1RcEMcEJwSAMsd5WsGjEF2 Hg75VEJLPH5m33YfNtNcdVRanE1H4tI/rsZysTyMjE+wbJLhep2WdwecrBPog5g6wOCG w6cM5wLZ2qahVk1iukmWn/Hefr/Qb4Bx/fBFhPkRvJqlkI4jjflDIgY5NG9LMBeKSaie nA6EfO2qcIj7a/rOeN+u62c3xQHF7T5ng0J1tRw6AvEaRBPYPgEpjWfESmKsdW5jbOF/ Nqag== X-Gm-Message-State: AOAM533+Xgx3oMF9kZY6nMaqwVmZdFQQW5rjL60J+JliZnMH5nwNiiNW exosiTp+Uza9GQgcGaSUSV/Msqi4D6ITfA== X-Google-Smtp-Source: ABdhPJya6N63kaphWiBcE3NKQ+rw7GfGKRNX27v9XXAnx/ldGraST3kP1VIxPyRUdJsaRqFTDrxxyw== X-Received: by 2002:adf:fc45:: with SMTP id e5mr27860646wrs.226.1597089024831; Mon, 10 Aug 2020 12:50:24 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 02/20] qapi: Fix indentation, again Date: Mon, 10 Aug 2020 20:50:01 +0100 Message-Id: <20200810195019.25427-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::444; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x444.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" In commit 26ec4e53f2 and similar commits we fixed the indentation for doc comments in our qapi json files to follow a new stricter standard for indentation, which permits only: @arg: description line 1 description line 2 or: @arg: line 1 line 2 Unfortunately since we didn't manage to get the script changes that enforced the new style in, a variety of commits (eg df4097aeaf71, 2e4457032105) introduced new doc text which doesn't follow the new stricter rules for indentation on multi-line doc comments. Bring those into line with the new rules. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/audio.json | 12 ++++++------ qapi/block-core.json | 8 ++++---- qapi/control.json | 4 ++-- qapi/machine.json | 6 +++--- qapi/migration.json | 8 ++++---- qapi/misc.json | 4 ++-- qapi/net.json | 2 +- 7 files changed, 22 insertions(+), 22 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index f62bd0d7f6e..3b843878d23 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -159,20 +159,20 @@ # recording. # # @server-name: select from among several possible concurrent server insta= nces -# (default: environment variable $JACK_DEFAULT_SERVER if set, else "defaul= t") +# (default: environment variable $JACK_DEFAULT_SERVER if set= , else "default") # # @client-name: the client name to use. The server will modify this name to -# create a unique variant, if needed unless @exact-name is true (default: = the -# guest's name) +# create a unique variant, if needed unless @exact-name is t= rue (default: the +# guest's name) # # @connect-ports: if set, a regular expression of JACK client port name(s)= to -# monitor for and automatically connect to +# monitor for and automatically connect to # # @start-server: start a jack server process if one is not already present -# (default: false) +# (default: false) # # @exact-name: use the exact name requested otherwise JACK automatically -# generates a unique one, if needed (default: false) +# generates a unique one, if needed (default: false) # # Since: 5.1 ## diff --git a/qapi/block-core.json b/qapi/block-core.json index 197bdc1c36d..f04bb3f0dd5 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -369,7 +369,7 @@ # # Features: # @deprecated: Member @encryption_key_missing is deprecated. It is -# always false. +# always false. # # Since: 0.14.0 # @@ -504,7 +504,7 @@ # # Features: # @deprecated: Member @status is deprecated. Use @recording and -# @locked instead. +# @locked instead. # # Since: 1.3 ## @@ -614,7 +614,7 @@ # # Features: # @deprecated: Member @dirty-bitmaps is deprecated. Use @inserted -# member @dirty-bitmaps instead. +# member @dirty-bitmaps instead. # # Since: 0.14.0 ## @@ -1642,7 +1642,7 @@ # # Features: # @deprecated: Members @base and @top are deprecated. Use @base-node -# and @top-node instead. +# and @top-node instead. # # Returns: - Nothing on success # - If @device does not exist, DeviceNotFound diff --git a/qapi/control.json b/qapi/control.json index de51e9916c3..134f842bafa 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -177,8 +177,8 @@ # # Features: # @deprecated: This command is deprecated, because its output doesn't -# reflect compile-time configuration. Use 'query-qmp-schema' -# instead. +# reflect compile-time configuration. Use 'query-qmp-schema' +# instead. # # Returns: A list of @EventInfo. # diff --git a/qapi/machine.json b/qapi/machine.json index 481b1f07ecc..5aee2bbd169 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -191,8 +191,8 @@ # # Features: # @deprecated: This command is deprecated, because it interferes with -# the guest. Use 'query-cpus-fast' instead to avoid the vCPU -# interruption. +# the guest. Use 'query-cpus-fast' instead to avoid the vCPU +# interruption. # # Returns: a list of @CpuInfo for each virtual CPU # @@ -316,7 +316,7 @@ # # Features: # @deprecated: This command is deprecated. Use `device_add` instead. -# See the `query-hotpluggable-cpus` command for details. +# See the `query-hotpluggable-cpus` command for details. # # Returns: Nothing on success # diff --git a/qapi/migration.json b/qapi/migration.json index e07c9c0f1aa..66a6fbb89d8 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1264,7 +1264,7 @@ # # Features: # @deprecated: This command is deprecated. Use -# 'migrate-set-parameters' instead. +# 'migrate-set-parameters' instead. # # Returns: nothing on success # @@ -1288,7 +1288,7 @@ # # Features: # @deprecated: This command is deprecated. Use -# 'migrate-set-parameters' instead. +# 'migrate-set-parameters' instead. # # Returns: nothing on success # @@ -1312,7 +1312,7 @@ # # Features: # @deprecated: This command is deprecated. Use -# 'migrate-set-parameters' instead. +# 'migrate-set-parameters' instead. # # The size will be rounded down to the nearest power of 2. # The cache size can be modified before and during ongoing migration @@ -1338,7 +1338,7 @@ # # Features: # @deprecated: This command is deprecated. Use -# 'query-migrate-parameters' instead. +# 'query-migrate-parameters' instead. # # Returns: XBZRLE cache size in bytes # diff --git a/qapi/misc.json b/qapi/misc.json index 9d32820dc1b..8cf6ebe67cb 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -877,8 +877,8 @@ # # Features: # @deprecated: This command is deprecated. For changing block -# devices, use 'blockdev-change-medium' instead; for changing VNC -# parameters, use 'change-vnc-password' instead. +# devices, use 'blockdev-change-medium' instead; for changing= VNC +# parameters, use 'change-vnc-password' instead. # # Returns: - Nothing on success. # - If @device is not a valid block device, DeviceNotFound diff --git a/qapi/net.json b/qapi/net.json index ddb113e5e5a..a3a13360018 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -457,7 +457,7 @@ # # Since: 2.7 # -# @vhost-vdpa since 5.1 +# @vhost-vdpa since 5.1 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089093; cv=none; d=zohomail.com; s=zohoarc; b=S64267ION5KwqFgU3jeE8IU6zS7kZzKHuGIS7g4UGkuPQWWU4VeN88QInSmNfND2krX/Wg5KLCLHmy41ONT25I6K7DwhnA25Ebq59Qlq4OUwY9h1zZdlhK4GpkSd8udMkXRouh6rt+Kw8guCN5y8CbpAZqPKufzhBjLwqrcSPdc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089093; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=69oUenAIXTnbx7cTfT5bBPqb6C7oBsuKzHVSA9VIsO8=; b=Dv600zfJpa4rZgYWGgN/oz0hzeVlzeFFdYJs5cVVO5J5RhUgdCQ1J9AemQDMpvZVpG6PoUE5VpIhG6EOar9LJbl/dlezCVcTwnzegZpJOjCnkD/eO5oyKj2aKwQ/bfGwYtQ5jWdsRnoiZGseywsUofUCA88Zes8AzMK/pcw7/QM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 159708909386942.0865930854535; Mon, 10 Aug 2020 12:51:33 -0700 (PDT) Received: from localhost ([::1]:60960 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DpU-0001m6-HE for importer@patchew.org; Mon, 10 Aug 2020 15:51:32 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51034) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5DoU-0008TC-FI for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:30 -0400 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]:33976) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5DoS-0004j1-NA for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:30 -0400 Received: by mail-wm1-x331.google.com with SMTP id c19so656837wmd.1 for ; Mon, 10 Aug 2020 12:50:28 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=69oUenAIXTnbx7cTfT5bBPqb6C7oBsuKzHVSA9VIsO8=; b=quSitfKlkbwyewrc37F9wnUld5ennQHGHWvjbbdhBBPnI+N+3tj/m60zG9NIbO2f83 F9xoWf/mFEo6uuYpZGSF6NM9z6VNdYVkdbhuIWNA4VqhcC3CxG5yOrX+vNv+0d/lEFaU rNO9IZUUoxFPHTqcFRY0+dXR93Uw3rdTnYyuNIUFALq4V5WQSz2l+HQRpE+MN6Sw185n NFntNKgLNZqhlgNbJAiwYgPA85RXOm2wIORfkgcfKjK7FGIWHLensvpPC5m88GHhxbQn oO5HxS6NNtRh69ToDaNSsnGRvifjzgIigxJ7rVMWkqlIV1hplaEf9Xdzn1fK4ZfFgwv9 488A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=69oUenAIXTnbx7cTfT5bBPqb6C7oBsuKzHVSA9VIsO8=; b=SbchTg3BQrpc9gLSfx+7ofWdcMoVt3rMlkUvPIMhjMfjXZeFpvzfjmmIWsOBljhYyj 6BcISZlYwLGpMCYjXZMXAmIzFr9lAfBQJq21MF5JMRSdfQ2KaxHjmCCk5UEIh8n4jKS4 cxUgPHt4bqpAU5WbldG02sCB3vIzvr4PcXalG7C1VDsH/Tben72kCXVjUHDnXl9z/ixr da0gU1DXTr69kX8tKXBXdmbA6v65enPuaoTeVlU5M/4z1sbVD8tkZoqXbEo3pq/nmLPK tHEDYd4Lh8HdqPtZRwtAonxFtmMeBhjmWPsLK/NhX59gWpCdIrXAE6gnP/Fb/JhrMdPK RQSQ== X-Gm-Message-State: AOAM531UHVhVZlpeeA/bCYAtqPWCLHHr06MLEumKoVRmARy134eYs3TH HYcFG1TxESQrDS5ehgJsBJJS/MZqKzcnVw== X-Google-Smtp-Source: ABdhPJzzwqanvn7JT3NdQDXjuRCuPnGgSztQf76dzjCqAm8cIQ2zrp7xlWJHo25dbKDleeOcexr1SA== X-Received: by 2002:a7b:c194:: with SMTP id y20mr748807wmi.183.1597089026363; Mon, 10 Aug 2020 12:50:26 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 03/20] qapi/block-core.json: Fix nbd-server-start docs Date: Mon, 10 Aug 2020 20:50:02 +0100 Message-Id: <20200810195019.25427-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::331; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x331.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Commit eed8b6917832 added some new text to the nbd-server-start documentation in the wrong place. Since this is after the 'Returns:' line it's parsed as if it were part of the documentation of the "Returns:' information. Move it up to join the rest of the "documentation of the type as a whole" doc text. This doesn't look odd in the current HTML rendering, but the new QAPI-to-rST handling will complain about the indent level of the lines not matching up with the 'Returns:' line. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/block-core.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index f04bb3f0dd5..535b2b2e7bf 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -5206,6 +5206,9 @@ # server will present them as named exports; for example, another # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=3DNAME". # +# Keep this type consistent with the NbdServerOptions type. The only inten= ded +# difference is using SocketAddressLegacy instead of SocketAddress. +# # @addr: Address on which to listen. # @tls-creds: ID of the TLS credentials object (since 2.6). # @tls-authz: ID of the QAuthZ authorization object used to validate @@ -5216,9 +5219,6 @@ # # Returns: error if the server is already running. # -# Keep this type consistent with the NbdServerOptions type. The only inten= ded -# difference is using SocketAddressLegacy instead of SocketAddress. -# # Since: 1.3.0 ## { 'command': 'nbd-server-start', --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089177; cv=none; d=zohomail.com; s=zohoarc; b=mZTU4BLbmtJZWCBq4a2f/yHB026pkgCc5QgyvNUQ+ipkLm0/tu0Gd5Cx3JHrmf4mh1fw7ZtF6UCItni9yjZ4tQpLsKQ8AmmTqQQmEkYj43mh0yJmx61xrr8uH9U+yFXHo7940M50M57E9/Nt71oryitaf77Lk35hnmL5TclBAuU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089177; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=NK7m3uoWmCtcbXsGQreBTTuezmJYVKaA5MHLH71vKCc=; b=lwnAWzw5NCuSf0KcupcfTnhilgNnC6AQ34GcmMYMgHgkA1dx6lmP+O/xOek8qCMMtfd7Kob3K/SnxEkJQWLzcePoB5n3h4sRwm79KzZ5pWQjWs2kmBw+fvv99jTu9GWSY07lDcATAuGLcD26agUw7sMDKtZwhOTYM7YRIDnXM04= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089177370986.2728554923193; Mon, 10 Aug 2020 12:52:57 -0700 (PDT) Received: from localhost ([::1]:40972 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dqq-00051b-2R for importer@patchew.org; Mon, 10 Aug 2020 15:52:56 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51050) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5DoW-00005A-32 for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:32 -0400 Received: from mail-wr1-x42a.google.com ([2a00:1450:4864:20::42a]:46895) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5DoU-0004jF-CP for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:31 -0400 Received: by mail-wr1-x42a.google.com with SMTP id f12so9305369wru.13 for ; Mon, 10 Aug 2020 12:50:29 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=NK7m3uoWmCtcbXsGQreBTTuezmJYVKaA5MHLH71vKCc=; b=au9d957sT+BXStmJAnu0OeN23N5SDALeo4EBFOXmM5YuLP32Ql9aZapp0BGJOJaC/5 N4vou9gORHwBo0TlOmu2hexIvLFiYceWytADQtC+crT6ag8JOUWQkv1kbIeniz3gA+nG uB5T56hkv0ivD0BKHByoh+JC58ZJxkoYjCSG8mngTfYjo8AtCLrq4KGQXIApBFpoiBHM nH6T75FmNz/lH+SPplpdUi8ebhkSj8gLl2nA7z7sVOybYI8EwgUR95sp5s445oLiAdTr 9OQ1LyZLbvVl4afB+c43ncU/pB3CsZW4e/sO4kFjioTy2Ew+YwzOwtVnd19A0A6g8UMe sWCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=NK7m3uoWmCtcbXsGQreBTTuezmJYVKaA5MHLH71vKCc=; b=IgqcmEGb28/q6Sz09YDstWIrUSmPHEFd9tOcO9GBSCxNhjaIJBJAw42LJhupwzRR40 ngLPEh4L5x6tEK3hHUjg5b4joUYkv5EBNsgAa8aSveyAkzllXqyfJbzyAnuBrDWg40FX +QUmCeAKXO83lGrYuELHRHY35Spg6rJRWzefkQjS0SyhOtFR9ocHTKAJuvzwQ4vPL8XU 5Ptoa6w8A3vOoNgk4Dxc1h3xM1+a5DZthzT43o6r4EZqiBPQp6MadQy6vAxzRgZZbh3D 1VEqQWeBpzcKmpEybGHAyEnFj7DNfy30GtV5xS+yFfhctDKlaL7Hz2ythTIyxUsBlkYM jw8Q== X-Gm-Message-State: AOAM533w0EGJtoy+jQd/y6K8qwYLkZDhmFTGhZ/1ArdPLZiqmqyeK8pB bkqvAU9Us3vEFbqpeR5lGQ8xI24pkx1k+Q== X-Google-Smtp-Source: ABdhPJyZtEjJvshDEby8ed7gkF2E+UiN/S8MqGY19x5WuusiVJ2/K4i5+JmXnpL9yFW4muIVY2tx3g== X-Received: by 2002:adf:e8cc:: with SMTP id k12mr27013186wrn.2.1597089028382; Mon, 10 Aug 2020 12:50:28 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 04/20] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Date: Mon, 10 Aug 2020 20:50:03 +0100 Message-Id: <20200810195019.25427-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::42a; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42a.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Our current QAPI doc-comment markup allows section headers (introduced with a leading '=3D' or '=3D=3D') anywhere in any documentation comment. This works for texinfo because the texi generator simply prints a texinfo heading directive at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. New section headings in the middle of the documentation of a command or event would be pretty nonsensical, and in fact we only ever output new headings using 'freeform' doc comment blocks whose only content is the single line of the heading, with two exceptions, which are in the introductory freeform-doc-block at the top of qapi/qapi-schema.json. Split that doc-comment up so that the heading lines are in their own doc-comment. This will allow us to tighten the specification to insist that heading lines are always standalone, rather than requiring the rST document generator to look at every line in a doc comment block and handle headings in odd places. This change makes no difference to the generated texi. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index f03ff91ceb5..5fc0771eb04 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -2,7 +2,9 @@ # vim: filetype=3Dpython ## # =3D Introduction -# +## + +## # This document describes all commands currently supported by QMP. # # Most of the time their usage is exactly the same as in the user Monitor,= this @@ -26,9 +28,13 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# +## + +## # =3D Stability Considerations -# +## + +## # The current QMP command set (described in this file) may be useful for a # number of use cases, however it's limited and several commands have bad # defined semantics, specially with regard to command completion. --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089262; cv=none; d=zohomail.com; s=zohoarc; b=Aqs5/KBk+6SgwgEWHvuuUqZt/ets3JiCHqsqZ+AsHlmWE4DHN5zRd+C50f6JU4nQmJZNvKXvBA+2Rcn7JMAErzh92jQ/EPu6GonlKRil09etx8Uz2HzEOv8WwBKv9FoDqSH343xKwRdKlABKMO0rBKDe9jXdoPY7beGdMnr/BMk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089262; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=bCdAd7Be6DRYvzpoO8DYOlXvYCiC9pmHXI5mvLQ78DM=; b=MouEsUaBMv3grUPKdTC8dV4GNZm/G3RXyHNeTawyK2VUL3PqHJaNTeY893cQ33/gFK5hSXipIuk18s87OpoxDABmX7AfrtXWydsLo1/mPa3wjijpJWzEl3Xw+sRvSdAYPk6Z5FFb4GkWoubcJYY7R37lr7JJ//zLHxZ3TQdWOHM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089262952154.5049563424394; Mon, 10 Aug 2020 12:54:22 -0700 (PDT) Received: from localhost ([::1]:49352 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DsD-0008Lj-MV for importer@patchew.org; Mon, 10 Aug 2020 15:54:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51064) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5DoY-0000CS-Ta for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:34 -0400 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:40557) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5DoX-0004kd-0Y for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:34 -0400 Received: by mail-wm1-x341.google.com with SMTP id k20so664515wmi.5 for ; Mon, 10 Aug 2020 12:50:32 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=bCdAd7Be6DRYvzpoO8DYOlXvYCiC9pmHXI5mvLQ78DM=; b=N7GBexm7xl37M8Z6j1VuOWuswK4MAHCqBNHj65q1qUEo6JGb+p/k6AQllwQuYaBBr0 77y9Gyycxysqb2cTHA8XQbRlzrnIccLgABFf1s3J4BhdphWMQF+Y12T7jFUdRZFE6wi4 B2wIe19cX0pHOjRbHNwfB4u4kMkMp74+U8eu6y/Mznpcz0oByvn1FuWo4Un+9F/llcPb zYIrFCvaFDjzHpTdSIyASNxpZwHjUoX/d6AHongju2NR9Knw+/XHImasHqwbgE3eMM2f Bj1Yj4Y7K+gmw3cvyUqLazbPMcwnhqbr9B0+jqM5DQBJbisqUNWsGe2BLuV8FZ7VyjW1 nTxQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=bCdAd7Be6DRYvzpoO8DYOlXvYCiC9pmHXI5mvLQ78DM=; b=EBQ7ucQe/tHFXKC6Wf6u+/VwFHFbzMSCBETziSNTsd3DpZ/rgUSLUUD3ePb8NS9fQV dpHeD3QiruXLv5w1sAHS/Apw5L//vasmdLbHY/egi6A7IKH6EJX2JdnB/p/rp+otlJp2 6evVCvUlQWGRaZraxDYEQXcnM3/B5JIhKDFEC+Vba/4krCersoK1Gx+geyPu46ot5ouy vyBmibkz9bwxKGkPq8At6qy27JjTX2Sue+Jc6Ei10L0LHFtTLYO8qmUXh8D2i+CK6VXJ QBnaZc+WsKcjHODCxKZtWFajk5Deyh+Cb6HccNJGgKhfKbBNAe2WQAVdUbPBkhIVlmb3 Nj/A== X-Gm-Message-State: AOAM5328/2t/m/4e3Cu5UvuNmtuw/7bCrbilRi71qUjrbV/wt18O1Yvp hvfSsvOtuyfzX5zUw4E5n8Z0eIGP9Um8Pw== X-Google-Smtp-Source: ABdhPJz9UCYmCXiWNOaBNxg/IgYdufRwKdEJ5zOuoIDfn//q/msMHTpnKjrsoXBrGzcPOvhsJGeUzw== X-Received: by 2002:a1c:e917:: with SMTP id q23mr692273wmc.125.1597089030552; Mon, 10 Aug 2020 12:50:30 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 05/20] qapi/machine.json: Escape a literal '*' in doc comment Date: Mon, 10 Aug 2020 20:50:04 +0100 Message-Id: <20200810195019.25427-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::341; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x341.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" For rST, '*' is a kind of inline markup (for emphasis), so "*-softmmu" is a syntax error because of the missing closing '*'. Escape the '*' with a '\'. The texinfo document generator will leave the '\' in the output, which is not ideal, but that generator is going to go away in a subsequent commit. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- qapi/machine.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/machine.json b/qapi/machine.json index 5aee2bbd169..3f6ea5693d1 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -13,7 +13,7 @@ # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and -# look for the *-softmmu targets near the "--target-list" option. The +# look for the \*-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. # --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089181; cv=none; d=zohomail.com; s=zohoarc; b=j8a9i8jbqDn61bpBvpWwendfWA0PDtFcPbRbEvi5xMGdbaZunFCJbnjGWrbEIH1v1TWpc7PqgbiiHLw1qWa6uzMgBeR2jV3ckpUiAuoGYgxkz/UPaEPBT8LZtKIk/8MOj2HDxGeQG1J3NY/0AxGZviLJgwO4w2d4gKzlW9aQ64o= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089181; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=IXHFRWhIT8ijPgjKcnwuZX4OYMB2Jdnl5joMznYN9yQ=; b=lazzp0OyAr4bxee0Ph5bEMMLlXAb0x7WnTxONN7ZJz4NiSEOmevVYbsJbrH4wGz+fjwnBkZgfdpDg0CT8fZo23GL+cMRCrj+NpYwdx/mGaB8Fg71H8+ohYktymZZuJdwXV/48L+TWT/eJCFabk5p10QbWi0F5Y2JszitjJYmvq4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089181382625.2916916496706; Mon, 10 Aug 2020 12:53:01 -0700 (PDT) Received: from localhost ([::1]:41194 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dqu-00056r-8w for importer@patchew.org; Mon, 10 Aug 2020 15:53:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51082) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doa-0000HA-Pv for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:36 -0400 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]:34384) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5DoY-0004ko-OB for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:36 -0400 Received: by mail-wr1-x432.google.com with SMTP id f7so9325117wrw.1 for ; Mon, 10 Aug 2020 12:50:34 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=IXHFRWhIT8ijPgjKcnwuZX4OYMB2Jdnl5joMznYN9yQ=; b=p7z6nRyoyFFTNdzZXfHH/eI+XFfn1u/E2qs1WxAvgvcw9oa1WjS8waJmG7ft2KhvGS y2o3ANDXzBb0yZAaigXWTdGTeUQpJ48stdtEohZ6nXVfoQQCbB4lDojxbJWhKaPEsrGC nnuZozIoyYQ6jxvHMxZsure1nQs1iaF9HckDvSb4lcT/avZ4T9CxOjuMXfLnvoJxAd6B om/J9mam925GSLedf4aUXAJk4NDghLghCLfLuHpfZa0rnP9AV8kaJsGAkl0+hxMbv4he 2/J6Cf6bzfPHlfzozymNRFOgr0V9y6Vrs6Twf7A3LNe4wR25DYjz8FXJVpTNmk+3KKUC ip+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=IXHFRWhIT8ijPgjKcnwuZX4OYMB2Jdnl5joMznYN9yQ=; b=NpDMUw7CuA+kDskkQuEo0O7+uJc+l4pYCIDa8WVlDiiwPmWGPOiigBbJJ27nqbRe9B F01D9cxTIcsqbwoT6pWDn5SKKelo9oh9L/YvngXlXf02Yj6YxWhhlLp3Qt1UP4hdvhiH cFqmjQA2UhCC2WGFGNdOLnKCHd08CF2OXOXx+tUOIrGDrBq9XQ3qYeJYwr9HOsnEzWfx Az6rDHUrGimbLyTjdkDxK0EiMH5sXemTG1XLt/z4gEPK4n/9C75dFtuXB+v0czjqDdq+ u1zmffCFJOKlgcfeNHm3Wxs7yBLSrYG2JrjXitqR1dzqHRlDxRS2C9jceBCin+D8AlYj 0Rng== X-Gm-Message-State: AOAM530noRy8tkiNi9alrF8hTaWVhBpYCRFqyTdJG85b1zek1YAno6O+ MEL5jbqW73cr2vY2J2ehp/5DjPc/njbpEg== X-Google-Smtp-Source: ABdhPJwSS2wl1htKCtgIgJXZNawTsDuuA5PVlIInhWen7i451wRLDGXzU33zT8IkjcuINd/hJ0gKNA== X-Received: by 2002:a05:6000:1211:: with SMTP id e17mr2934539wrx.263.1597089032550; Mon, 10 Aug 2020 12:50:32 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 06/20] tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension Date: Mon, 10 Aug 2020 20:50:05 +0100 Message-Id: <20200810195019.25427-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::432; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x432.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" doc-good.json tests doc comment parser corner cases. We're about to largely replace it by a Sphinx extension, which will have different corner cases. Tweak the test so it passes both with the old parser and the Sphinx extension, by making it match the more restrictive rST syntax: * in a single list the bullet types must all match * lists must have leading and following blank lines * indentation is important * the '|' example syntax is going to go away entirely, so stop testing it This will avoid the tests spuriously breaking when we tighten up the parser code in the following commits. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- Changes v4->v5: improved commit message with Markus' suggested text --- tests/qapi-schema/doc-good.json | 25 +++++++++++++------------ tests/qapi-schema/doc-good.out | 12 ++++++------ tests/qapi-schema/doc-good.texi | 12 +++--------- 3 files changed, 22 insertions(+), 27 deletions(-) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.j= son index 9da72a1f556..c6822145c49 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -12,25 +12,25 @@ # # *strong* _with emphasis_ # @var {in braces} +# # * List item one -# - Two, multiple +# * Two, multiple # lines # -# 3. Three -# Still in list +# * Three +# Still in list +# +# Not in list # -# Not in list # - Second list -# Note: still in list +# Note: still in list # # Note: not in list +# # 1. Third list # is numbered # -# - another item -# -# | example -# | multiple lines +# 2. another item # # Returns: the King # Since: the first age @@ -68,7 +68,7 @@ ## # @Base: # @base1: -# the first member +# the first member ## { 'struct': 'Base', 'data': { 'base1': 'Enum' } } =20 @@ -116,7 +116,7 @@ ## # @Alternate: # @i: an integer -# @b is undocumented +# @b is undocumented # # Features: # @alt-feat: a feature @@ -134,7 +134,7 @@ # @arg1: the first argument # # @arg2: the second -# argument +# argument # # Features: # @cmd-feat1: a feature @@ -143,6 +143,7 @@ # Returns: @Object # TODO: frobnicate # Notes: +# # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam # diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 6757dd26a2f..4c24eb96486 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -74,25 +74,25 @@ doc freeform =20 *strong* _with emphasis_ @var {in braces} + * List item one -- Two, multiple +* Two, multiple lines =20 -3. Three +* Three Still in list =20 Not in list + - Second list Note: still in list =20 Note: not in list + 1. Third list is numbered =20 -- another item - -| example -| multiple lines +2. another item =20 Returns: the King Since: the first age diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.t= exi index 7f28fb7a0fb..12808989ffb 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -6,6 +6,7 @@ =20 @strong{strong} @emph{with emphasis} @code{var} @{in braces@} + @itemize @bullet @item List item one @@ -20,6 +21,7 @@ Still in list @end itemize =20 Not in list + @itemize @minus @item Second list @@ -28,6 +30,7 @@ Note: still in list @end itemize =20 Note: not in list + @enumerate @item Third list @@ -36,15 +39,6 @@ is numbered @item another item =20 -@example -example -@end example - -@example -multiple lines -@end example - - @end enumerate =20 Returns: the King --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089138; cv=none; d=zohomail.com; s=zohoarc; b=aJzZ9BYo5n11qJAFxDjAwJwJnPzXYK/9QQL12XPoTGZwE5/x7ludRmpgniL58HE/wNO9PsVBg8TrDoDOA+9dLXXTizHPRmAIxiOi1aPvns5wpgMaJGUZ0pEPr7zHbRca0pvhtPCS0cuM5THIUv12PTq/XHvWeeQYgJXL6bExaZ0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089138; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=e0cYa2LpgDtFPEx6dbDjbhZ7m+B+8SmWLGFLVWEF5JA=; b=mVLOTBbRn/lXgXgK9U3ddP/3Yj5VEZO5FHda1+6gOVpL/O1+Q9xf3ea5flSRD4H/lKYRj55p40WYZFY04l3enKXod5db2MQJWxQvIIDiqtEqgWoCG+kUwPFxfhNFAck3TM4D3Sne3KmxaJC41J2aMBcw3a73/iMLNi9D5qX6woo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089138725793.9753303345437; Mon, 10 Aug 2020 12:52:18 -0700 (PDT) Received: from localhost ([::1]:37412 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DqD-0003dd-D6 for importer@patchew.org; Mon, 10 Aug 2020 15:52:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51098) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doc-0000Kw-2y for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:38 -0400 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:45031) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Doa-0004kz-4p for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:37 -0400 Received: by mail-wr1-x441.google.com with SMTP id c15so9293830wrs.11 for ; Mon, 10 Aug 2020 12:50:35 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=e0cYa2LpgDtFPEx6dbDjbhZ7m+B+8SmWLGFLVWEF5JA=; b=qoFwy4I7lwv+KfNqEeMprNM3B5CBTEDKAzGEaq9BEcHBVUHIUXbelf85gUJdVhi71L W7uF8P9XFy4YETsxBRXONwXJ6Uc5ydg7itBPaZ+1mXhBoftWr4/Bih2BTHPyRVQsRJKQ uJcZrlpqydhjEMNUxyvQaDrUZiIMqIC7i02ypYvQKN9VBVIj/3oHb4R6VazKWs9Ex/7F ZR/j7RdLKVzT/DskaZgc9vZOKBfq4Npf+K40OI9T7BVCjPFZryGgqvsMvqw4XdRXzZ5X 6ivEBmBs8oAkhqkUyZ9lhHZniv87f2WZUsn1vb0cShsLp0AfIuO5lXYKzDIBK1RJu4DG rZKQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=e0cYa2LpgDtFPEx6dbDjbhZ7m+B+8SmWLGFLVWEF5JA=; b=RbxzIf50b8nSepOsZ3w+bWmhWsz9EHrWEvJWDTGycl7VJK8WoOEbJySuQQxhzEbKho JX0xfIZcUp544s/BgJlf0uJC5aYk9xzzaMCop5rSyexJpr+SFYrNv5XSgU+PdgJbmLHc U6m/i1b46W8fVNVpCy0hFoXrQekrygDtUVfbIUKqsmsfQSN4yNCf8sFGUQ1T0ecQD6OR zToJ22Sk4LMGNXRlEthE1PB8el1xA8V/QtpKSVutgd2upOKMWfAYAzRKzM/4OjnV48dQ n8MEMv6sQdDO1eTUCSLXqnvBN+ZaBB84TvDoB4mH9yeEsVWoRD67KWaIuiThmZU280wm zSCw== X-Gm-Message-State: AOAM533+9EXrYrMIRZyvxXmRajCTqpInbnbut9AdNJBScZtf9h9qRCGA K+Kxe1MpUVkXSudfV6sySsI8wnUUdQP/Mw== X-Google-Smtp-Source: ABdhPJyJJWeNeJSU1em6JiPRw8PNkcCgebBwIy1zbRFa0bNKPHIlgOYO1HzFozWR3k635T0D/xM0Xw== X-Received: by 2002:adf:9ed4:: with SMTP id b20mr26158582wrf.206.1597089033962; Mon, 10 Aug 2020 12:50:33 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 07/20] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Mon, 10 Aug 2020 20:50:06 +0100 Message-Id: <20200810195019.25427-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::441; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x441.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for Texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- v4->v5: just fixed the caps in 'Texinfo' in commit message --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- tests/qapi-schema/doc-good.out | 12 ++++++------ 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 92f584edcf1..7764de1e4bc 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -79,6 +79,7 @@ def texi_format(doc): inlist =3D '' lastempty =3D False for line in doc.split('\n'): + line =3D line.strip() empty =3D line =3D=3D '' =20 # FIXME: Doing this in a single if / elif chain is diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index abadacbb0e8..7fae4478d34 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -417,10 +417,10 @@ class QAPIDoc: self._append_line =3D self._append_various_line self._append_various_line(line) else: - self._append_freeform(line.strip()) + self._append_freeform(line) else: # This is a free-form documentation block - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_args_line(self, line): """ @@ -453,7 +453,7 @@ class QAPIDoc: self._append_various_line(line) return =20 - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_features_line(self, line): name =3D line.split(' ', 1)[0] @@ -472,7 +472,7 @@ class QAPIDoc: self._append_various_line(line) return =20 - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_various_line(self, line): """ @@ -495,10 +495,6 @@ class QAPIDoc: line =3D line[len(name)+1:] self._start_section(name[:-1]) =20 - if (not self._section.name or - not self._section.name.startswith('Example')): - line =3D line.strip() - self._append_freeform(line) =20 def _start_symbol_section(self, symbols_dict, name): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 4c24eb96486..0ef85d959ac 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -77,20 +77,20 @@ doc freeform =20 * List item one * Two, multiple -lines + lines =20 * Three -Still in list + Still in list =20 Not in list =20 - Second list -Note: still in list + Note: still in list =20 Note: not in list =20 1. Third list -is numbered + is numbered =20 2. another item =20 @@ -158,7 +158,7 @@ doc symbol=3DAlternate =20 arg=3Di an integer -@b is undocumented + @b is undocumented arg=3Db =20 feature=3Dalt-feat @@ -173,7 +173,7 @@ doc symbol=3Dcmd the first argument arg=3Darg2 the second -argument + argument arg=3Darg3 =20 feature=3Dcmd-feat1 --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089266; cv=none; d=zohomail.com; s=zohoarc; b=Tb8+rHYMhLkZpBtY3vXo3UtHR8IsTms95k5fJ0NYPUCfo2A4A0coMo95D1JGQgQzr/0kdWxbCCx0beghG413kntUiu+0cOPLVsunOwbFx1N9FAeC6SyRDPI0imXzn5gNbm5OqiGHy3Eij4ZjDk3zVdTKzdT0LYKQ0ShqpfhQkHU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089266; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=in8nHFzKOQegCgF8vb8hOhMAaiGbmURtCJ4Hj4NuXzg=; b=XbaomuWAWdCBhkg5FAiP1pfnrxeNMXXnacfR8Iaet4j1jaIHNtYp5HtN6ZOr9IR/yfR/s35JxL4oUuoAxoQsa+ruIzHPjOhp2P8iQ495PS8M3iURg9aJvsqflmcUz6SmHqkDs98CJwJuD0TZPXOPmvnQkOJQVJkj0dlPOa9WLbg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089266721699.6510815367701; Mon, 10 Aug 2020 12:54:26 -0700 (PDT) Received: from localhost ([::1]:49698 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DsH-0008U1-CC for importer@patchew.org; Mon, 10 Aug 2020 15:54:25 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51126) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dog-0000VF-Am for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:42 -0400 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:36425) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dob-0004l5-OB for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:41 -0400 Received: by mail-wm1-x32e.google.com with SMTP id 3so692692wmi.1 for ; Mon, 10 Aug 2020 12:50:37 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=in8nHFzKOQegCgF8vb8hOhMAaiGbmURtCJ4Hj4NuXzg=; b=oEINfCMrjNcCDNfoGaT77zm+BZJrp0tyYJNIvjAA06OSfwbf5+4gKdoKyPgiahXWTp pfMyQC/iMt1nVN4IJYZyKqRM4/cdzhH76cYT+MiQXvmwhbs5bZUyR5vYzH/oIiqreEEC DeTLiaM8EF6zQrQ/4J59qYPsHyrCEUQem7Awb7AIPzp7EB/ib7SYwIiNfC3xRumLY4QN yt6PaA8qQWKwMUrJ50fBhW3Qh/zmONMuAOnCAnXOJcBTH/iOfAFzCVQ4El1AI/6+joS8 QPzQUq/kERTMt0jSTkQR7nqCeoIiQnDxWEndvu2tEyiJg1GwqQNzsi6V//NSmtTy6Ygg S4tg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=in8nHFzKOQegCgF8vb8hOhMAaiGbmURtCJ4Hj4NuXzg=; b=tbAP0HSd9hthXBsNozdC3RUPjsyB7Ew5SnrqHI/2jf4OZzEy+QR31tQGROI3TqceKf ZKHan6ASIlDhU3VIQFLfQDaSs4UvjhmZtRij3ahf5pqTUrijNeabgnndxJRThigLFk4p pVh38gvAyyavDizm1BX595sIadP4ouANVWygSbmRowMO80vLCHicxNpAnZo7sMmKyTps c4RaSJvgWu8EqVYy/zLM3q+BDNhJsbBBkSWZ9K4HwDpXR3KlR/LMPgVPIrmg649tYDZS bSOZs7pBirvrOT3Ue5fFuSP0J1E6BVwE8YBfQzZCUZbhezPBKS6lFDoZ/2R1xqcWBjVE AlaA== X-Gm-Message-State: AOAM532cVzYj9g0cb6Xp+rqGsnxPDgDKKfn+/L7a+vCzshgbD1WJta9m dMMV96DvXwxOFI3jbBiX6D41lP5pVDtyMg== X-Google-Smtp-Source: ABdhPJzLPjoKYwq19yk3SwarDfhuwmOzgWFfI2kjgugOvqyQUN5XOAqcGI0j609qI9Y/Z7dLjWXztA== X-Received: by 2002:a1c:964b:: with SMTP id y72mr745852wmd.69.1597089035390; Mon, 10 Aug 2020 12:50:35 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 08/20] scripts/qapi/parser.py: improve doc comment indent handling Date: Mon, 10 Aug 2020 20:50:07 +0100 Message-Id: <20200810195019.25427-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32e; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32e.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. The exception is that we always retain indentation as-is for Examples sections, because these are literal text. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) The golden reference for the doc comment text is updated to remove the two 'wrong' indents; these now form a test case that we correctly stripped leading whitespace from an indented multi-line argument definition. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- v1->v2: Update doc-good.out as per final para. --- scripts/qapi/parser.py | 81 +++++++++++++++++++++++++++------- tests/qapi-schema/doc-good.out | 4 +- 2 files changed, 67 insertions(+), 18 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 7fae4478d34..d9f11eadd96 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -308,18 +308,32 @@ class QAPIDoc: """ =20 class Section: - def __init__(self, name=3DNone): + def __init__(self, parser, name=3DNone, indent=3D0): + # parser, for error messages about indentation + self._parser =3D parser # optional section name (argument/member or section name) self.name =3D name # the list of lines for this section self.text =3D '' + # the expected indent level of the text of this section + self._indent =3D indent =20 def append(self, line): + # Strip leading spaces corresponding to the expected indent le= vel + # Blank lines are always OK. + if line: + spacecount =3D len(line) - len(line.lstrip(" ")) + if spacecount > self._indent: + spacecount =3D self._indent + if spacecount < self._indent: + raise QAPIParseError(self._parser, "unexpected de-inde= nt") + line =3D line[spacecount:] + self.text +=3D line.rstrip() + '\n' =20 class ArgSection(Section): - def __init__(self, name): - super().__init__(name) + def __init__(self, parser, name, indent=3D0): + super().__init__(parser, name, indent) self.member =3D None =20 def connect(self, member): @@ -333,7 +347,7 @@ class QAPIDoc: self._parser =3D parser self.info =3D info self.symbol =3D None - self.body =3D QAPIDoc.Section() + self.body =3D QAPIDoc.Section(parser) # dict mapping parameter name to ArgSection self.args =3D OrderedDict() self.features =3D OrderedDict() @@ -438,7 +452,18 @@ class QAPIDoc: =20 if name.startswith('@') and name.endswith(':'): line =3D line[len(name)+1:] - self._start_args_section(name[1:-1]) + if not line or line.isspace(): + # Line was just the "@arg:" header; following lines + # are not indented + indent =3D 0 + line =3D '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 1, and we + # pad out this first line so it is handled the same way + indent =3D len(name) + 1 + line =3D ' ' * indent + line + self._start_args_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line =3D self._append_various_line self._append_various_line(line) @@ -460,7 +485,17 @@ class QAPIDoc: =20 if name.startswith('@') and name.endswith(':'): line =3D line[len(name)+1:] - self._start_features_section(name[1:-1]) + if not line or line.isspace(): + # Line is just the "@name:" header, no ident for following= lines + indent =3D 0 + line =3D '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 3, and we + # pad out this first line so it is handled the same way + indent =3D len(name) + 1 + line =3D ' ' * indent + line + self._start_features_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line =3D self._append_various_line self._append_various_line(line) @@ -493,11 +528,23 @@ class QAPIDoc: % (name, self.sections[0].name)) if self._is_section_tag(name): line =3D line[len(name)+1:] - self._start_section(name[:-1]) + if not line or line.isspace(): + # Line is just "SectionName:", no indent for following lin= es + indent =3D 0 + line =3D '' + elif name.startswith("Example"): + # The "Examples" section is literal-text, so preserve + # all the indentation as-is + indent =3D 0 + else: + # Line is "SectionName: some text", indent required + indent =3D len(name) + 1 + line =3D ' ' * indent + line + self._start_section(name[:-1], indent) =20 self._append_freeform(line) =20 - def _start_symbol_section(self, symbols_dict, name): + def _start_symbol_section(self, symbols_dict, name, indent): # FIXME invalid names other than the empty string aren't flagged if not name: raise QAPIParseError(self._parser, "invalid parameter name") @@ -506,21 +553,21 @@ class QAPIDoc: "'%s' parameter name duplicated" % name) assert not self.sections self._end_section() - self._section =3D QAPIDoc.ArgSection(name) + self._section =3D QAPIDoc.ArgSection(self._parser, name, indent) symbols_dict[name] =3D self._section =20 - def _start_args_section(self, name): - self._start_symbol_section(self.args, name) + def _start_args_section(self, name, indent): + self._start_symbol_section(self.args, name, indent) =20 - def _start_features_section(self, name): - self._start_symbol_section(self.features, name) + def _start_features_section(self, name, indent): + self._start_symbol_section(self.features, name, indent) =20 - def _start_section(self, name=3DNone): + def _start_section(self, name=3DNone, indent=3D0): if name in ('Returns', 'Since') and self.has_section(name): raise QAPIParseError(self._parser, "duplicated '%s' section" % name) self._end_section() - self._section =3D QAPIDoc.Section(name) + self._section =3D QAPIDoc.Section(self._parser, name, indent) self.sections.append(self._section) =20 def _end_section(self): @@ -543,7 +590,7 @@ class QAPIDoc: def connect_member(self, member): if member.name not in self.args: # Undocumented TODO outlaw - self.args[member.name] =3D QAPIDoc.ArgSection(member.name) + self.args[member.name] =3D QAPIDoc.ArgSection(self._parser, me= mber.name) self.args[member.name].connect(member) =20 def connect_feature(self, feature): @@ -551,6 +598,8 @@ class QAPIDoc: raise QAPISemError(feature.info, "feature '%s' lacks documentation" % feature.name) + self.features[feature.name] =3D QAPIDoc.ArgSection(self._parse= r, + feature.name) self.features[feature.name].connect(feature) =20 def check_expr(self, expr): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 0ef85d959ac..bbf77b08dc3 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -158,7 +158,7 @@ doc symbol=3DAlternate =20 arg=3Di an integer - @b is undocumented +@b is undocumented arg=3Db =20 feature=3Dalt-feat @@ -173,7 +173,7 @@ doc symbol=3Dcmd the first argument arg=3Darg2 the second - argument +argument arg=3Darg3 =20 feature=3Dcmd-feat1 --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089428; cv=none; d=zohomail.com; s=zohoarc; b=WlIZZK9vukK0o/sGIIqeksXoLD4p2CjepO0alezp9/Sc9MAMl9Xkxw5sykbYehtG460YjtplMk6ZcE3W2wTvO6h1g+71Y3iKbFQGDaV9g7gOTJCb5dE5v7H3oE3XoWsvttR8+eSZIAlHWugspH945ZRCk2kNljmbih9Yn7d1gNk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089428; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=z/dTzF2aEpv733HceHEozLrO8vWXaXfUqU2qDmOaLKo=; b=Yyj4GnEHzby2aqvZCcD24dDFShyEGedO8ALOS4t3NpD3tsNC1Rr7t5DNtCk3r2jajdlwikl5iKRQcACUmNl4+fL9UxQIKE7TroOhSGFqgCrpiCwjxcwwRBaGYV2Gmv3rZAU9uj9bBTZEg+du01a18IXDDeXPhv5QgLO9iq8u66Y= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089428215970.5261756927365; Mon, 10 Aug 2020 12:57:08 -0700 (PDT) Received: from localhost ([::1]:36518 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dus-000659-FZ for importer@patchew.org; Mon, 10 Aug 2020 15:57:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51158) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doi-0000a7-Ff for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:44 -0400 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]:40512) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dod-0004lO-Uh for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:44 -0400 Received: by mail-wm1-x331.google.com with SMTP id k20so664787wmi.5 for ; Mon, 10 Aug 2020 12:50:39 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=z/dTzF2aEpv733HceHEozLrO8vWXaXfUqU2qDmOaLKo=; b=ZihLP3J/KcleUK4I0C95+PUWmjfUomT5KyWRk0mfQMm2Iy/YBhOOv4YZJ51oz/C7UQ wQxDoWuSQpPa4UFB/L5k96XYJDxxwEmhgoafBNPaUmnBvKdRYMMig3WNzPwM0yMDpxSO DBTkRgCKSJko92CiGLByVMbeu1UqiMcp7L74G0WsgyaqRde6W937rsUTFviXeG4ApNx8 IjuYagxEZQ4TFarkAxB/5+89JU7obrLTol3bnTa7edOixbWiO6Rza4Xm+44F16Ntxdn9 VpXe/YQFgk9JZfjlj67Q0q6tiLgkGsaSfgFBbUfd32hmAjrnmeUVMDuwp+9QOOoDMU2m 42MA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=z/dTzF2aEpv733HceHEozLrO8vWXaXfUqU2qDmOaLKo=; b=ZOD3oPQF4E5oVJXd1MT9iPHfPpnb4wZKSTb3sbtgBQI6UsV8DurDCH6e/ZQJWposlv Terrl9yz3T5jrgQl5biSJWsshKCXc6z/Q4yew1uEYHI4Qowza1EhQiU3chmmx8KU5Ohq 98yhF97WaOPt4ajZoK0X2rkcQRbL3LuZpvmYjJQey5NUmnJb8YBHk1Lkxl8Q0Kl217Pm HSOST+veOqpWj8Ez9u4gcXaYxbkysCTTM/2Q/py3wScWoDo4tXXTCO97sdFUAo3UaGp1 0FUc9plByACv+veqv7SPE1sondh013TLA+0Upb9iuyQD7VWUtiq6QdjBHjeaXiwmBESL bSdw== X-Gm-Message-State: AOAM5311EKl7EhVRQ+PuxQ1QMENDYfcZDW+JZNMwhEQoVCvbl88XUR4G u0vhNyKkFy7y83HTKoRyC4xFKRAF7JZJaA== X-Google-Smtp-Source: ABdhPJwwfPRZJCMtmZ701QVCxP6QapxTeNzkKhG+1ueV7OsUhuKtqH7RfxrPOO3AY4WubFEitEK4LQ== X-Received: by 2002:a7b:cf29:: with SMTP id m9mr757581wmg.88.1597089037183; Mon, 10 Aug 2020 12:50:37 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 09/20] docs/sphinx: Add new qapi-doc Sphinx extension Date: Mon, 10 Aug 2020 20:50:08 +0100 Message-Id: <20200810195019.25427-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::331; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x331.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- Changes v4->v5: match the changes in parameters to the various visit_* methods from commit 7b3bc9e28f366 --- docs/conf.py | 6 +- docs/sphinx/qapidoc.py | 504 +++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 510 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapidoc.py diff --git a/docs/conf.py b/docs/conf.py index d6e173ef77b..44ec5050717 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,7 +52,10 @@ except NameError: # add these directories to sys.path here. If the directory is relative to = the # documentation root, use an absolute path starting from qemu_docdir. # +# Our extensions are in docs/sphinx; the qapidoc extension requires +# the QAPI modules from scripts/. sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) +sys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) =20 =20 # -- General configuration ------------------------------------------------ @@ -67,7 +70,7 @@ needs_sphinx =3D '1.6' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions =3D ['kerneldoc', 'qmp_lexer', 'hxtool'] +extensions =3D ['kerneldoc', 'qmp_lexer', 'hxtool', 'qapidoc'] =20 # Add any paths that contain templates here, relative to this directory. templates_path =3D ['_templates'] @@ -241,3 +244,4 @@ texinfo_documents =3D [ kerneldoc_bin =3D os.path.join(qemu_docdir, '../scripts/kernel-doc') kerneldoc_srctree =3D os.path.join(qemu_docdir, '..') hxtool_srctree =3D os.path.join(qemu_docdir, '..') +qapidoc_srctree =3D os.path.join(qemu_docdir, '..') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py new file mode 100644 index 00000000000..4f571b2f45a --- /dev/null +++ b/docs/sphinx/qapidoc.py @@ -0,0 +1,504 @@ +# coding=3Dutf-8 +# +# QEMU qapidoc QAPI file parsing extension +# +# Copyright (c) 2020 Linaro +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. +"""qapidoc is a Sphinx extension that implements the qapi-doc directive""" + +# The purpose of this extension is to read the documentation comments +# in QAPI JSON schema files, and insert them all into the current document. +# The conf.py file must set the qapidoc_srctree config value to +# the root of the QEMU source tree. +# Each qapi-doc:: directive takes one argument which is the +# path of the .json file to process, relative to the source tree. + +import os +import re + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles +import sphinx +from qapi.gen import QAPISchemaVisitor +from qapi.schema import QAPIError, QAPISchema + +# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later +# use switch_source_input. Check borrowed from kerneldoc.py. +Use_SSI =3D sphinx.__version__[:3] >=3D '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + + +__version__ =3D '1.0' + +# Function borrowed from pydash, which is under the MIT license +def intersperse(iterable, separator): + """Like join, but for arbitrary iterables, notably arrays""" + iterable =3D iter(iterable) + yield next(iterable) + for item in iterable: + yield separator + yield item + +class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which generates docutils/Sphinx nodes + + This class builds up a tree of docutils/Sphinx nodes corresponding + to documentation for the various QAPI objects. To use it, first create + a QAPISchemaGenRSTVisitor object, and call its visit_begin() method. + Then you can call one of the two methods 'freeform' (to add documentat= ion + for a freeform documentation chunk) or 'symbol' (to add documentation + for a QAPI symbol). These will cause the visitor to build up the + tree of document nodes. Once you've added all the documentation + via 'freeform' and 'symbol' method calls, you can call 'get_document_n= odes' + to get the final list of document nodes (in a form suitable for return= ing + from a Sphinx directive's 'run' method). + """ + def __init__(self, sphinx_directive): + self._cur_doc =3D None + self._sphinx_directive =3D sphinx_directive + self._top_node =3D nodes.section() + self._active_headings =3D [self._top_node] + + def _serror(self, msg): + """Raise an exception giving a user-friendly syntax error message"= "" + file =3D self._cur_doc.info.fname + line =3D self._cur_doc.info.line + raise ExtensionError('%s line %d: syntax error: %s' % (file, line,= msg)) + + def _make_dlitem(self, term, defn): + """Return a dlitem node with the specified term and definition. + + term should be a list of Text and literal nodes. + defn should be one of: + - a string, which will be handed to _parse_text_into_node + - a list of Text and literal nodes, which will be put into + a paragraph node + """ + dlitem =3D nodes.definition_list_item() + dlterm =3D nodes.term('', '', *term) + dlitem +=3D dlterm + if defn: + dldef =3D nodes.definition() + if isinstance(defn, list): + dldef +=3D nodes.paragraph('', '', *defn) + else: + self._parse_text_into_node(defn, dldef) + dlitem +=3D dldef + return dlitem + + def _make_section(self, title): + """Return a section node with optional title""" + section =3D nodes.section(ids=3D[self._sphinx_directive.new_serial= no()]) + if title: + section +=3D nodes.title(title, title) + return section + + def _nodes_for_ifcond(self, ifcond, with_if=3DTrue): + """Return list of Text, literal nodes for the ifcond + + Return a list which gives text like ' (If: cond1, cond2, cond3)', = where + the conditions are in literal-text and the commas are not. + If with_if is False, we don't return the "(If: " and ")". + """ + condlist =3D intersperse([nodes.literal('', c) for c in ifcond], + nodes.Text(', ')) + if not with_if: + return condlist + + nodelist =3D [nodes.Text(' ('), nodes.strong('', 'If: ')] + nodelist.extend(condlist) + nodelist.append(nodes.Text(')')) + return nodelist + + def _nodes_for_one_member(self, member): + """Return list of Text, literal nodes for this member + + Return a list of doctree nodes which give text like + 'name: type (optional) (If: ...)' suitable for use as the + 'term' part of a definition list item. + """ + term =3D [nodes.literal('', member.name)] + if member.type.doc_type(): + term.append(nodes.Text(': ')) + term.append(nodes.literal('', member.type.doc_type())) + if member.optional: + term.append(nodes.Text(' (optional)')) + if member.ifcond: + term.extend(self._nodes_for_ifcond(member.ifcond)) + return term + + def _nodes_for_variant_when(self, variants, variant): + """Return list of Text, literal nodes for variant 'when' clause + + Return a list of doctree nodes which give text like + 'when tagname is variant (If: ...)' suitable for use in + the 'variants' part of a definition list. + """ + term =3D [nodes.Text(' when '), + nodes.literal('', variants.tag_member.name), + nodes.Text(' is '), + nodes.literal('', '"%s"' % variant.name)] + if variant.ifcond: + term.extend(self._nodes_for_ifcond(variant.ifcond)) + return term + + def _nodes_for_members(self, doc, what, base=3DNone, variants=3DNone): + """Return doctree nodes for the table of members""" + dlnode =3D nodes.definition_list() + for section in doc.args.values(): + term =3D self._nodes_for_one_member(section.member) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn =3D section.text + elif (variants and variants.tag_member =3D=3D section.member + and not section.member.type.doc_type()): + values =3D section.member.type.member_names() + defn =3D [nodes.Text('One of ')] + defn.extend(intersperse([nodes.literal('', v) for v in val= ues], + nodes.Text(', '))) + else: + defn =3D [nodes.Text('Not documented')] + + dlnode +=3D self._make_dlitem(term, defn) + + if base: + dlnode +=3D self._make_dlitem([nodes.Text('The members of '), + nodes.literal('', base.doc_type()= )], + None) + + if variants: + for v in variants.variants: + if v.type.is_implicit(): + assert not v.type.base and not v.type.variants + for m in v.type.local_members: + term =3D self._nodes_for_one_member(m) + term.extend(self._nodes_for_variant_when(variants,= v)) + dlnode +=3D self._make_dlitem(term, None) + else: + term =3D [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode +=3D self._make_dlitem(term, None) + + if not dlnode.children: + return None + + section =3D self._make_section(what) + section +=3D dlnode + return section + + def _nodes_for_enum_values(self, doc, what): + """Return doctree nodes for the table of enum values""" + seen_item =3D False + dlnode =3D nodes.definition_list() + for section in doc.args.values(): + termtext =3D [nodes.literal('', section.member.name)] + if section.member.ifcond: + termtext.extend(self._nodes_for_ifcond(section.member.ifco= nd)) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn =3D section.text + else: + defn =3D [nodes.Text('Not documented')] + + dlnode +=3D self._make_dlitem(termtext, defn) + seen_item =3D True + + if not seen_item: + return None + + section =3D self._make_section(what) + section +=3D dlnode + return section + + def _nodes_for_arguments(self, doc, boxed_arg_type): + """Return doctree nodes for the arguments section""" + if boxed_arg_type: + assert not doc.args + section =3D self._make_section('Arguments') + dlnode =3D nodes.definition_list() + dlnode +=3D self._make_dlitem( + [nodes.Text('The members of '), + nodes.literal('', boxed_arg_type.name)], + None) + section +=3D dlnode + return section + + return self._nodes_for_members(doc, 'Arguments') + + def _nodes_for_features(self, doc): + """Return doctree nodes for the table of features""" + seen_item =3D False + dlnode =3D nodes.definition_list() + for section in doc.features.values(): + dlnode +=3D self._make_dlitem([nodes.literal('', section.name)= ], + section.text) + seen_item =3D True + + if not seen_item: + return None + + section =3D self._make_section('Features') + section +=3D dlnode + return section + + def _nodes_for_example(self, exampletext): + """Return doctree nodes for a code example snippet""" + return nodes.literal_block(exampletext, exampletext) + + def _nodes_for_sections(self, doc, ifcond): + """Return doctree nodes for additional sections following argument= s""" + nodelist =3D [] + for section in doc.sections: + snode =3D self._make_section(section.name) + if section.name and section.name.startswith('Example'): + snode +=3D self._nodes_for_example(section.text) + else: + self._parse_text_into_node(section.text, snode) + nodelist.append(snode) + if ifcond: + snode =3D self._make_section('If') + snode +=3D self._nodes_for_ifcond(ifcond, with_if=3DFalse) + nodelist.append(snode) + if not nodelist: + return None + return nodelist + + def _add_doc(self, typ, sections): + """Add documentation for a command/object/enum... + + We assume we're documenting the thing defined in self._cur_doc. + typ is the type of thing being added ("Command", "Object", etc) + + sections is a list of nodes for sections to add to the definition. + """ + + doc =3D self._cur_doc + snode =3D nodes.section(ids=3D[self._sphinx_directive.new_serialno= ()]) + snode +=3D nodes.title('', '', *[nodes.literal(doc.symbol, doc.sym= bol), + nodes.Text(' (' + typ + ')')]) + self._parse_text_into_node(doc.body.text, snode) + for s in sections: + if s is not None: + snode +=3D s + self._add_node_to_current_heading(snode) + + def visit_enum_type(self, name, info, ifcond, features, members, prefi= x): + doc =3D self._cur_doc + self._add_doc('Enum', + [self._nodes_for_enum_values(doc, 'Values'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_object_type(self, name, info, ifcond, features, + base, members, variants): + doc =3D self._cur_doc + if base and base.is_implicit(): + base =3D None + self._add_doc('Object', + [self._nodes_for_members(doc, 'Members', base, varia= nts), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_alternate_type(self, name, info, ifcond, features, variants): + doc =3D self._cur_doc + self._add_doc('Alternate', + [self._nodes_for_members(doc, 'Members'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_command(self, name, info, ifcond, features, arg_type, + ret_type, gen, success_response, boxed, allow_oob, + allow_preconfig): + doc =3D self._cur_doc + self._add_doc('Command', + [self._nodes_for_arguments(doc, + arg_type if boxed else No= ne), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_event(self, name, info, ifcond, features, arg_type, boxed): + doc =3D self._cur_doc + self._add_doc('Event', + [self._nodes_for_arguments(doc, + arg_type if boxed else No= ne), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def symbol(self, doc, entity): + """Add documentation for one symbol to the document tree + + This is the main entry point which causes us to add documentation + nodes for a symbol (which could be a 'command', 'object', 'event', + etc). We do this by calling 'visit' on the schema entity, which + will then call back into one of our visit_* methods, depending + on what kind of thing this symbol is. + """ + self._cur_doc =3D doc + entity.visit(self) + self._cur_doc =3D None + + def _start_new_heading(self, heading, level): + """Start a new heading at the specified heading level + + Create a new section whose title is 'heading' and which is placed + in the docutils node tree as a child of the most recent level-1 + heading. Subsequent document sections (commands, freeform doc chun= ks, + etc) will be placed as children of this new heading section. + """ + if len(self._active_headings) < level: + self._serror('Level %d subheading found outside a level %d hea= ding' + % (level, level - 1)) + snode =3D self._make_section(heading) + self._active_headings[level - 1] +=3D snode + self._active_headings =3D self._active_headings[:level] + self._active_headings.append(snode) + + def _add_node_to_current_heading(self, node): + """Add the node to whatever the current active heading is""" + self._active_headings[-1] +=3D node + + def freeform(self, doc): + """Add a piece of 'freeform' documentation to the document tree + + A 'freeform' document chunk doesn't relate to any particular + symbol (for instance, it could be an introduction). + + As a special case, if the freeform document is a single line + of the form '=3D Heading text' it is treated as a section or subse= ction + heading, with the heading level indicated by the number of '=3D' s= igns. + """ + + # QAPIDoc documentation says free-form documentation blocks + # must have only a body section, nothing else. + assert not doc.sections + assert not doc.args + assert not doc.features + self._cur_doc =3D doc + + if re.match(r'=3D+ ', doc.body.text): + # Section or subsection heading: must be the only thing in the= block + (heading, _, rest) =3D doc.body.text.partition('\n') + if rest !=3D '': + raise ExtensionError('%s line %s: section or subsection he= ading' + ' must be in its own doc comment bloc= k' + % (doc.info.fname, doc.info.line)) + (leader, _, heading) =3D heading.partition(' ') + self._start_new_heading(heading, len(leader)) + return + + node =3D self._make_section(None) + self._parse_text_into_node(doc.body.text, node) + self._add_node_to_current_heading(node) + self._cur_doc =3D None + + def _parse_text_into_node(self, doctext, node): + """Parse a chunk of QAPI-doc-format text into the node + + The doc comment can contain most inline rST markup, including + bulleted and enumerated lists. + As an extra permitted piece of markup, @var will be turned + into ``var``. + """ + + # Handle the "@var means ``var`` case + doctext =3D re.sub(r'@([\w-]+)', r'``\1``', doctext) + + rstlist =3D ViewList() + for line in doctext.splitlines(): + # The reported line number will always be that of the start li= ne + # of the doc comment, rather than the actual location of the e= rror. + # Being more precise would require overhaul of the QAPIDoc cla= ss + # to track lines more exactly within all the sub-parts of the = doc + # comment, as well as counting lines here. + rstlist.append(line, self._cur_doc.info.fname, + self._cur_doc.info.line) + self._sphinx_directive.do_parse(rstlist, node) + + def get_document_nodes(self): + """Return the list of docutils nodes which make up the document""" + return self._top_node.children + +class QAPIDocDirective(Directive): + """Extract documentation from the specified QAPI .json file""" + required_argument =3D 1 + optional_arguments =3D 1 + option_spec =3D { + 'qapifile': directives.unchanged_required + } + has_content =3D False + + def new_serialno(self): + """Return a unique new ID string suitable for use as a node's ID""" + env =3D self.state.document.settings.env + return 'qapidoc-%d' % env.new_serialno('qapidoc') + + def run(self): + env =3D self.state.document.settings.env + qapifile =3D env.config.qapidoc_srctree + '/' + self.arguments[0] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(qapifile)) + + try: + schema =3D QAPISchema(qapifile) + except QAPIError as err: + # Launder QAPI parse errors into Sphinx extension errors + # so they are displayed nicely to the user + raise ExtensionError(str(err)) + + vis =3D QAPISchemaGenRSTVisitor(self) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + + return vis.get_document_nodes() + + def do_parse(self, rstlist, node): + """Parse rST source lines and add them to the specified node + + Take the list of rST source lines rstlist, parse them as + rST, and add the resulting docutils nodes as children of node. + The nodes are parsed in a way that allows them to include + subheadings (titles) without confusing the rendering of + anything else. + """ + # This is from kerneldoc.py -- it works around an API change in + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use + # sphinx.util.nodes.nested_parse_with_titles() rather than the + # plain self.state.nested_parse(), and so we can drop the saving + # of title_styles and section_level that kerneldoc.py does, + # because nested_parse_with_titles() does that for us. + if Use_SSI: + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + else: + save =3D self.state.memo.reporter + self.state.memo.reporter =3D AutodocReporter(rstlist, + self.state.memo.rep= orter) + try: + nested_parse_with_titles(self.state, rstlist, node) + finally: + self.state.memo.reporter =3D save + +def setup(app): + """ Register qapi-doc directive with Sphinx""" + app.add_config_value('qapidoc_srctree', None, 'env') + app.add_directive('qapi-doc', QAPIDocDirective) + + return dict( + version=3D__version__, + parallel_read_safe=3DTrue, + parallel_write_safe=3DTrue + ) diff --git a/MAINTAINERS b/MAINTAINERS index 0886eb3d2b5..fdd38f412d7 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3116,6 +3116,7 @@ M: Peter Maydell S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/sphinx/ =20 Miscellaneous ------------- --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089348; cv=none; d=zohomail.com; s=zohoarc; b=MkDUKNQBGwOdc0NnYjlUcc2E7OeJ//Ul8DbnzIeQ6JqS1oXS1mihtLgicW15kQEHw+iybC49iSdoyAsCPMnD7L3Ob0+YuXp16qAzpBIV1grItdc3Rfb5j2ii7xXSzp4+ojpSTEDKKOGlrOw61yurUaX92EhgGfhPSKif7SDkxFo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089348; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=9f9MZL1OazmNxGdgFSs03UaW8w8TN7a6dCRj95o9ljc=; b=K5mEu7UU8xSJRNlndyC8/rtleSTeFHkFrcKb8buA4GTm9jLsbfj2hgAHYEU4vxR7QdK+7lYoiEefQssQW0ZF5elFj+Nq6s8h9fSfQVVcvR6Jrltw/yspB6M7eh5Ds2zN5vGdWlH/ybIfL7KDaMbpQUT3qXCQCXmyDrTIwCwpy0M= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089348765656.2632919810776; Mon, 10 Aug 2020 12:55:48 -0700 (PDT) Received: from localhost ([::1]:57248 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dtb-00033U-DU for importer@patchew.org; Mon, 10 Aug 2020 15:55:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51152) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doh-0000Z6-VK for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:43 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:33502) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Doe-0004lX-Ny for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:43 -0400 Received: by mail-wr1-x436.google.com with SMTP id p20so9317104wrf.0 for ; Mon, 10 Aug 2020 12:50:40 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=9f9MZL1OazmNxGdgFSs03UaW8w8TN7a6dCRj95o9ljc=; b=OmvRTpp+nYMLejdvqc3tIOO6zTj2pqfsVd+xk+tJBitEuilccljLrfJlTlQokBuCqQ yunw5VWHpMUy/mW/+N/HgE869g3B9VPQAhMpA0AMl1gFWH+uWtayBm7nsZJUQ/7aJaUD gHMadkZlCw++AcDYZYwfVW4G3NeKFfALgIjMLeqOfvfmPILl07l2mbVCTuSoJtUBH2E4 PoBp+MoBWQf+s3ZZjiEi+8/08exRWZqyovgXSyz17JK7m6EFwRD8+GLMUUgw10a4ACFA 54XFCfT6WTU82enE+BcUL23wdgyX3tYMQt5cCQXH19jXgOa4cZ2/VojC7b3pYeGXZ2SZ +K4w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=9f9MZL1OazmNxGdgFSs03UaW8w8TN7a6dCRj95o9ljc=; b=i4YaNxwQ2UmCHawsM0NHlp/Cx3niojKr7eX44PrYQtxNDY30AQogp4rgO3vQc+Oj8T DFQJu0AZ6A8en5XOUZg5FxsCGVQE6+73Qnx7MTi1bQPNK/iy+fFKb9bWS9aI18Ad59e5 f1sLvsp+Q4UfrYcH1uXpBoF64NWatm/atn463vimMPpsj2K4dbSaCYDCWeJ7DBow0dOM k+n2L41POK+OVyt2tHlj/cc4W5YNflDUcbbWOwx7aPu+HLYd6VHy/eM6KQv+mvEA0Ubw Brc7gR/m7XA3huHwq3x5pGxJ6OK/Lpmg2Gi16g7flfPwyM1sxrRU4zqi47kKSNGz8CqB fwmA== X-Gm-Message-State: AOAM531ctYfEqpivEgUl4taJk3Nwpz8UP5bObX1uAVfxZ7Se1FJy9yEO 5O3E9mqtHoBIwyNnOrV2ZIlIXDrugTrT/w== X-Google-Smtp-Source: ABdhPJyxoacmqgdGbNjb+b6MWgRSwEC2VkxJTX5UlAaldJfEJJDRA8YeLQgXOsaA0lhetqtQ+B2XOQ== X-Received: by 2002:a05:6000:1203:: with SMTP id e3mr26634978wrx.324.1597089038502; Mon, 10 Aug 2020 12:50:38 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 10/20] docs/interop: Convert qemu-ga-ref to rST Date: Mon, 10 Aug 2020 20:50:09 +0100 Message-Id: <20200810195019.25427-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::436; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x436.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Convert qemu-ga-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-ga-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. As the GA ref is now part of the Sphinx 'interop' manual, we can delete the direct link from index.html.in. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-ga-ref.rst | 4 ++ docs/interop/qemu-ga-ref.texi | 80 ----------------------------------- Makefile | 42 ++++++++---------- MAINTAINERS | 2 +- 7 files changed, 25 insertions(+), 107 deletions(-) create mode 100644 docs/interop/qemu-ga-ref.rst delete mode 100644 docs/interop/qemu-ga-ref.texi diff --git a/docs/index.html.in b/docs/index.html.in index 6736fa4360c..99d4d8075fc 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -13,7 +13,6 @@
  • System Emulation Management= and Interoperability Guide
  • System Emulation Guest Hardwa= re Specifications
  • QMP Reference Manual=
    • -
  • Guest Agent Protocol = Reference
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index 42ce7e3d365..e83632e0108 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -19,4 +19,6 @@ html_theme_options['description'] =3D u'System Emulation = Management and Interopera man_pages =3D [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', ['Michael Roth '], 8), + ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 006f9864208..738cdbe185e 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,6 +18,7 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-ga-ref vhost-user vhost-user-gpu vhost-vdpa diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst new file mode 100644 index 00000000000..013eac0bb53 --- /dev/null +++ b/docs/interop/qemu-ga-ref.rst @@ -0,0 +1,4 @@ +QEMU Guest Agent Protocol Reference +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. qapi-doc:: qga/qapi-schema.json diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi deleted file mode 100644 index ddb76ce1c2a..00000000000 --- a/docs/interop/qemu-ga-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-ga-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU Guest Agent Protocol Reference - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU Guest Agent Protocol reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference -@end direntry - -@titlepage -@title Guest Agent Protocol Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU Guest Agent protocol reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qemu-ga-qapi.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye diff --git a/Makefile b/Makefile index 13dd708c4af..f0cca10b427 100644 --- a/Makefile +++ b/Makefile @@ -371,7 +371,7 @@ DOCS+=3D$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 DOCS+=3Ddocs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/= interop/qemu-qmp-ref.7 -DOCS+=3Ddocs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/in= terop/qemu-ga-ref.7 +DOCS+=3D$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 DOCS+=3D$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS @@ -800,11 +800,11 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-ga-qapi.texi docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 docs/interop/qemu-ga-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html + rm -f docs/interop/qemu-qmp-qapi.texi + rm -f docs/interop/qemu-qmp-ref.7 + rm -f docs/interop/qemu-qmp-ref.txt + rm -f docs/interop/qemu-qmp-ref.pdf + rm -f docs/interop/qemu-qmp-ref.html rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -858,7 +858,7 @@ endif # and also any sphinx-built manpages. define install-manual =3D for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "= $(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_= DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTAL= L_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done endef =20 # Note that we deliberately do not install the "devel" manual: it is @@ -894,10 +894,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP endif ifneq (,$(findstring qemu-ga,$(TOOLS))) $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)= /man8" - $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/interop" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)/i= nterop" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)/in= terop" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 "$(DESTDIR)$(man= dir)/man7" endif endif ifdef CONFIG_VIRTFS @@ -1090,7 +1087,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) =20 -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_P= ATH)/qga/qapi-schema.json $(qapi-py) $(call build-manual,interop,html) =20 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1105,7 +1102,10 @@ $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-d= eps,tools) $(SRC_PATH)/qemu- $(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user) $(call build-manual,user,html) =20 -$(call define-manpage-rule,interop,qemu-ga.8) +$(call define-manpage-rule,interop,\ + qemu-ga.8 qemu-ga-ref.7,\ + $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ + $(qapi-py)) =20 $(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-mod= els.7) =20 @@ -1122,18 +1122,10 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/ind= ex.html.in qemu-version.h docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ =20 -docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi - @cp -p $< $@ - -html: docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxd= ocs -info: docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info -pdf: docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf -txt: docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt - -docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ - docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \ - docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7: \ - docs/interop/qemu-ga-ref.texi docs/interop/qemu-ga-qapi.texi +html: docs/interop/qemu-qmp-ref.html sphinxdocs +info: docs/interop/qemu-qmp-ref.info +pdf: docs/interop/qemu-qmp-ref.pdf +txt: docs/interop/qemu-qmp-ref.txt =20 docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ diff --git a/MAINTAINERS b/MAINTAINERS index fdd38f412d7..6eae3625733 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2394,9 +2394,9 @@ M: Michael Roth S: Maintained F: qga/ F: docs/interop/qemu-ga.rst +F: docs/interop/qemu-ga-ref.rst F: scripts/qemu-guest-agent/ F: tests/test-qga.c -F: docs/interop/qemu-ga-ref.texi T: git https://github.com/mdroth/qemu.git qga =20 QOM --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089259; cv=none; d=zohomail.com; s=zohoarc; b=QCD5fqru9+7GdCToh/VQ+JMonA2Fwu/F0Wg6mcnBikfgOHAiLL9dAKaLQX5DHEKWU6NiyZbxNPBRr34kfdiojXvnSqJvIOuTANkJnv3xPWZH927wB2vk0qvh/Fm34hgoFNn/NWwLWc+71XppmpKFdgpDcH0gUsNkzgZdPLQoTls= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089259; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=hz+PeEHoMI/nagWK3QJjMZ7m/nxfdy6vnQlqCbPtmqA=; b=Dn10uXbSeVvOWqp7z8E85kiHU0hsC7lLGNjem3N3Nu248XYDykbEPQu3QrWjuaULa+GXl9Tqb9DWasJaCC5mdG7WnpokGhDoNlsjMt2bycZ0EgHheqaoC2piTiMeBYL+8EkRJgQVpLUYKJ9xiTgQ46jpHH4TiOSUTLEkvJ0B/2w= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089259856434.56358253134124; Mon, 10 Aug 2020 12:54:19 -0700 (PDT) Received: from localhost ([::1]:48936 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DsA-0008Bg-5T for importer@patchew.org; Mon, 10 Aug 2020 15:54:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51184) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doj-0000cL-Dv for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:45 -0400 Received: from mail-wm1-x329.google.com ([2a00:1450:4864:20::329]:40505) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dog-0004mW-Lz for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:45 -0400 Received: by mail-wm1-x329.google.com with SMTP id k20so664917wmi.5 for ; Mon, 10 Aug 2020 12:50:42 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hz+PeEHoMI/nagWK3QJjMZ7m/nxfdy6vnQlqCbPtmqA=; b=XTVLVkknVZHsgycss2KhFCHJ9NlQZufEQVEi5s8y4K7IHZYReABpAd0sFJkgWTVZWG aXpXC1GgoRSYXSVdKo32WE3jlwO7CoeKAQGkUYaJAYHkcd6Wgg4yMOQZNttXDf1qAI81 c4ZF9EwK8B0LVdz2UjG96KsX13VYH1uSDMXovffLNcWAkE1UPesjiAENaLqmTvEYJhVq O9wcQbB6DgX+opF81yXbDT7909i+DZKRcLTucwUVwSKVdUppzSxhs7bwWpsgnOubm3KH +/KpyhTUe8GDkXpGp4x7nZaYDxrqju7TUp7pMidsYFlpr4w1v8dJpIah6X8Oysc8skZ0 ip/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hz+PeEHoMI/nagWK3QJjMZ7m/nxfdy6vnQlqCbPtmqA=; b=mjbng3m/RpeE5WEuiVD58Fc6Swo33YwQdCrtb0d2N/Qz9u+kh6A7AUmCp6NH8G+O5n DakDoylsrknYnoHu+EN88Tg5l1UM2J523LwgJ1pcMRsM1WOmQz6ehSsv834wFORYrGS0 Z8RZVcAxJ6fLmMqI3UGa8pI+W+OgX72XRLuktFzZ1I59gr79kgYcy0tcSNunhpaf2/kC OUd0y3mzZvn5ica95895yFJO3fVBPXRMzwycKabXmXgxdv5+JTXXODMZi33dpuAW4A2K VAabpYyQ5rOZprPVG4Z3EpqcPnStlbTeznxNQuc9ryNR22/6DhmtdGJ4IIGwkqD/4L6M onBA== X-Gm-Message-State: AOAM533jSCuXXDEt3hUu720MGCtUdNKwbDCV1CV6E7dO36RTcIWr1WNJ w5Nd2Thx+T1SfsFdKxL2zfg+gNjFkzaNyg== X-Google-Smtp-Source: ABdhPJw2naqw7uCv91t60VQE39pqW7j3LMWxmuEonGlXxAPo6T911d2qlvcrxoQM5OxATBSH4AXZDQ== X-Received: by 2002:a1c:32c3:: with SMTP id y186mr735586wmy.15.1597089040395; Mon, 10 Aug 2020 12:50:40 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 11/20] docs/interop: Convert qemu-qmp-ref to rST Date: Mon, 10 Aug 2020 20:50:10 +0100 Message-Id: <20200810195019.25427-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::329; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x329.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Convert qemu-qmp-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-qmp-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. Again, we drop the direct link from index.html.in now that the QMP ref is part of the interop manual. This commit removes the 'info', 'txt' and 'pdf' Makefile targets, because we no longer generate any documentation except for the Sphinx HTML manuals and the manpages. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-qmp-ref.rst | 4 ++ docs/interop/qemu-qmp-ref.texi | 80 ---------------------------------- Makefile | 38 ++++------------ 6 files changed, 15 insertions(+), 111 deletions(-) create mode 100644 docs/interop/qemu-qmp-ref.rst delete mode 100644 docs/interop/qemu-qmp-ref.texi diff --git a/docs/index.html.in b/docs/index.html.in index 99d4d8075fc..b3dfb7a4611 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -12,7 +12,6 @@
  • Tools Guide
  • System Emulation Management= and Interoperability Guide
  • System Emulation Guest Hardwa= re Specifications
    • -
  • QMP Reference Manual=
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index e83632e0108..43de386d33d 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -21,4 +21,6 @@ man_pages =3D [ ['Michael Roth '], 8), ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', [], 7), + ('qemu-qmp-ref', 'qemu-qmp-ref', u'QEMU QMP Reference Manual', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 738cdbe185e..cd78d679d82 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -19,6 +19,7 @@ Contents: pr-helper qemu-ga qemu-ga-ref + qemu-qmp-ref vhost-user vhost-user-gpu vhost-vdpa diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst new file mode 100644 index 00000000000..e640903abaf --- /dev/null +++ b/docs/interop/qemu-qmp-ref.rst @@ -0,0 +1,4 @@ +QEMU QMP Reference Manual +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +.. qapi-doc:: qapi/qapi-schema.json diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi deleted file mode 100644 index bb25758bd02..00000000000 --- a/docs/interop/qemu-qmp-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-qmp-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU QMP Reference Manual - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU QMP reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual -@end direntry - -@titlepage -@title QMP Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU QMP reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qemu-qmp-qapi.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye diff --git a/Makefile b/Makefile index f0cca10b427..3df1cf68333 100644 --- a/Makefile +++ b/Makefile @@ -123,7 +123,6 @@ GENERATED_QAPI_FILES +=3D qapi/qapi-events.h qapi/qapi-= events.c GENERATED_QAPI_FILES +=3D $(QAPI_MODULES:%=3Dqapi/qapi-events-%.h) GENERATED_QAPI_FILES +=3D $(QAPI_MODULES:%=3Dqapi/qapi-events-%.c) GENERATED_QAPI_FILES +=3D qapi/qapi-introspect.c qapi/qapi-introspect.h -GENERATED_QAPI_FILES +=3D qapi/qapi-doc.texi =20 # The following list considers only the storage daemon main module. All ot= her # modules are currently shared with the main schema, so we don't actually @@ -370,7 +369,6 @@ ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_N= G),yyy) DOCS+=3D$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 -DOCS+=3Ddocs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/= interop/qemu-qmp-ref.7 DOCS+=3D$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 DOCS+=3D$(MANUAL_BUILDDIR)/index.html @@ -644,8 +642,7 @@ $(SRC_PATH)/scripts/qapi-gen.py qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h \ qga/qapi-generated/qga-qapi-visit.c qga/qapi-generated/qga-qapi-visit.h \ qga/qapi-generated/qga-qapi-commands.h qga/qapi-generated/qga-qapi-command= s.c \ -qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-in= it-commands.c \ -qga/qapi-generated/qga-qapi-doc.texi: \ +qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-in= it-commands.c: \ qga/qapi-generated/qapi-gen-timestamp ; qga/qapi-generated/qapi-gen-timestamp: $(SRC_PATH)/qga/qapi-schema.json $(= qapi-py) $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ @@ -800,11 +797,6 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -858,7 +850,7 @@ endif # and also any sphinx-built manpages. define install-manual =3D for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "= $(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTAL= L_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' -name '*.[0-9]= '); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$= $f"; done endef =20 # Note that we deliberately do not install the "devel" manual: it is @@ -874,14 +866,11 @@ install-sphinxdocs: sphinxdocs install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/interop" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)/= interop" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)/i= nterop" ifdef CONFIG_POSIX $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu.1 "$(DESTDIR)$(mandir)/man= 1" $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-qmp-ref.7 "$(DESTDIR)$(ma= ndir)/man7" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR= )$(mandir)/man7" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 "$(DESTDIR)$(= mandir)/man7" ifeq ($(CONFIG_TOOLS),y) @@ -1087,7 +1076,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) =20 -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_P= ATH)/qga/qapi-schema.json $(qapi-py) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_P= ATH)/qga/qapi-schema.json $(qapi-modules) $(qapi-py) $(call build-manual,interop,html) =20 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1103,9 +1092,9 @@ $(MANUAL_BUILDDIR)/user/index.html: $(call manual-dep= s,user) $(call build-manual,user,html) =20 $(call define-manpage-rule,interop,\ - qemu-ga.8 qemu-ga-ref.7,\ + qemu-ga.8 qemu-ga-ref.7 qemu-qmp-ref.7,\ $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ - $(qapi-py)) + $(qapi-modules) $(qapi-py)) =20 $(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-mod= els.7) =20 @@ -1119,18 +1108,7 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/inde= x.html.in qemu-version.h $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \ "GEN","$@") =20 -docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi - @cp -p $< $@ - -html: docs/interop/qemu-qmp-ref.html sphinxdocs -info: docs/interop/qemu-qmp-ref.info -pdf: docs/interop/qemu-qmp-ref.pdf -txt: docs/interop/qemu-qmp-ref.txt - -docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ - docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ - docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ - docs/interop/qemu-qmp-ref.texi docs/interop/qemu-qmp-qapi.texi +html: sphinxdocs =20 $(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl =20 @@ -1271,7 +1249,7 @@ endif $(call print-help,vm-help,Help about targets running tests inside VM) @echo '' @echo 'Documentation targets:' - $(call print-help,html info pdf txt,Build documentation in specified form= at) + $(call print-help,html,Build HTML documentation) ifdef CONFIG_GCOV $(call print-help,coverage-report,Create code coverage report) endif --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089265; cv=none; d=zohomail.com; s=zohoarc; b=Eq2uilft/yOxBjNRpRCYbaq922mxXlJ7eC4MRaYNR8FAIDP6RutWg5NB5XvDT2RHFYAY251yHg1Io/5KrUqnJ/IX6V6aLQboKejPEbznudzRJGokawWxfA8bZe6m66m+J1K26hkYrVkixrvM/ybBVk0RLWdCAu6xo7lhuIuPLZw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089265; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=5W1KknFp9KSiL5Xfv87WpKM4kTEKJloaAztwVUv2s+w=; b=W3Zj5bMojGakZXF3WSoLD9WCNyBKh/b/JgIbE6z4W6Nll5jvcKGq2vKcNSrhni1Yfd0u3FSwEygADh9vEABE+dCNEq63kceVq1FZLlwxCbAm6QKvLMDF8NzfJB7rQj7DsK6k8zRhzB555o+Zsw4Vx086d706uV8/YGK/I8Z+jy4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089265352189.2844343207322; Mon, 10 Aug 2020 12:54:25 -0700 (PDT) Received: from localhost ([::1]:49644 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DsG-0008Sq-3V for importer@patchew.org; Mon, 10 Aug 2020 15:54:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51206) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dol-0000gF-Dt for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:47 -0400 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:37860) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Doi-0004nA-IC for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:47 -0400 Received: by mail-wr1-x42c.google.com with SMTP id y3so9308381wrl.4 for ; Mon, 10 Aug 2020 12:50:44 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=5W1KknFp9KSiL5Xfv87WpKM4kTEKJloaAztwVUv2s+w=; b=anPA1VU9T62Gre5BAwyOOrmr0YIxTqPjID6zid6XgdLGi4kiRTfh/SBdg4gvJhH2V3 //LCST1IaSwmx3ukvSezdEZeNxIwYzSQZT1OLP9Yg9ZaF9KnJDjUfWXug33uc+NdxY+Y 4jpQq4iBz5BJ1HeZgTRpniqdUBosKshg/mXellYxY8wgINny5PA3lAGsmzFYir/T3aVT jzC7rragwMmrToNxOfWZ21nVjDlFAu20wHCU00TgZwaGy3mUBpPP+D8kVqTUfNe5F1E9 K6JZFcas4QhitE6gNC6wLREqvEcoQX1pQjMfQJ9i35xWau9uDyamjm4hZ3VJSAmu5Gvj PwFw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=5W1KknFp9KSiL5Xfv87WpKM4kTEKJloaAztwVUv2s+w=; b=bo6yrAAFLGB0r+VYiegLMIoPXz+bFtcBtKDpL2z5MYs3q4hV4SImoTH2XJsRaYshNE mw70DPk8HfdBDUETUwcXORU+tJbB6GczAVBfPVyS/QS7blFBXYV8YUiIOKUV4zIxZ0CL qaSt42mX1lOR4JPOdpZ1cqs36HB4lBBGfput9uGQJetp/h0M/2CRl8YvR99yXsVVhtjD YtdyO1u76eXuqIh9zsILJrJG3lokCS5OE3yFX1ow0rvCL32NuHouhkVmvolluYpsUJxv 45hB3HxuvEeSzPQyq8V3glOcbr/mER0BrhEsWgWs6erMO2/zUd0LjTYgos5lzN1oRSbt jUnw== X-Gm-Message-State: AOAM533+St+jG715SbDzqLoijNQcsP1juTQ2IYtOch043sxA5fEZhn+P eB9GiYiZtOcTnqFz7xUTqpWSQcI93aQa+g== X-Google-Smtp-Source: ABdhPJzoy34koVCaL7/g8Ne5LQ8Q4LiJJ7HdyjuDfyRrPvkUKjLwIJf1m3iAqpT+mVLmIhaZsqKHTQ== X-Received: by 2002:adf:efcc:: with SMTP id i12mr2916747wrp.308.1597089042336; Mon, 10 Aug 2020 12:50:42 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 12/20] qapi: Use rST markup for literal blocks Date: Mon, 10 Aug 2020 20:50:11 +0100 Message-Id: <20200810195019.25427-13-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::42c; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42c.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" There are exactly two places in our json doc comments where we use the markup accepted by the texi doc generator where a '|' in the first line of a doc comment means the line should be emitted as a literal block (fixed-width font, whitespace preserved). Since we use this syntax so rarely, instead of making the rST generator support it, instead just convert the two uses to rST-format literal blocks, which are indented and introduced with '::'. (The rST generator doesn't complain about the old style syntax, it just emits it with the '|' and with the whitespace not preserved, which looks odd, but means we can safely leave this change until after we've stopped generating texinfo.) Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- qapi/block-core.json | 16 +++++++++------- qapi/qapi-schema.json | 6 ++++-- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 535b2b2e7bf..12758116e85 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -566,13 +566,15 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# | 5| * -# | 4| * -# | 3| * * -# | 2| * * * -# | 1| * * * * -# | +------------------ -# | 10 50 100 +# :: +# +# 5| * +# 4| * +# 3| * * +# 2| * * * +# 1| * * * * +# +------------------ +# 10 50 100 # # Since: 4.0 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 5fc0771eb04..c19b4267058 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -23,8 +23,10 @@ # # Example: # -# | -> data issued by the Client -# | <- Server data response +# :: +# +# -> data issued by the Client +# <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089490; cv=none; d=zohomail.com; s=zohoarc; b=gz6W0LkByyP2yOpaBvrYZ4/ZA62m15VLVFwNERXqs8a/woxcML6mgDsh+5DQXU4hrBFDbZDMP1xBXhfB8/wk9AB/AQ5X7a2bYt62ApM06eQItpVs3B4qYYi6Y9CSRqYmjuKKK9GAGffH0rZsiKvoJEVZbOWyaWsvYsHsYzxPdcE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089490; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=PgKydQ283kCxKymfkeo9fXBKb+pwyveUlMS1tfRsFkw=; b=hDze/sT1HmLm2iKtEHMb0jzP4PeMYNdyF45GzPLHIl3/wF4X228w5pUmui7xtp69HIdjFBShMXnmw7GshZFjf748zF0c7/tx9dg3gNHAg4zNS/6jpH1NTQnR20XPybHOESyb66hbInYcypQEWls6ibTyPO6olsDejLv2UZd++SA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089490573649.3431681680546; Mon, 10 Aug 2020 12:58:10 -0700 (PDT) Received: from localhost ([::1]:40876 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dvt-0007qb-9W for importer@patchew.org; Mon, 10 Aug 2020 15:58:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51208) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dom-0000hh-0c for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:48 -0400 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:50988) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dok-0004o9-89 for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:47 -0400 Received: by mail-wm1-x344.google.com with SMTP id c80so615298wme.0 for ; Mon, 10 Aug 2020 12:50:45 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=PgKydQ283kCxKymfkeo9fXBKb+pwyveUlMS1tfRsFkw=; b=NmgetztG8+no4e2Yy3erL3ZXfh/D8KDHPRvA+g+74sph/Bn8X3rrQHA5HrKY4sVxnT 2oA6cbcJ/qWyJfDmm4Y3zosY3cCanu9ER1WyZts0P8sOR/vsTnvpZVZxdz8EfjvKjxpn 9Vl3ATJazq3QQiWsadEtdItIystg+d5azQMxp5npoFNvT2qEa2rrlsCb2RFc1uhOjLj/ RcAfIJq6qCHl+Xau8gRoxqcE0AO6CDI+lH9cR7mn4zKbUeugofr7kctB1nuzb1IylCa0 GV65Xg7+e7/tPD5d3USznZ9DUmgEcrJLkqlQNIxDI13LPxEY45LdsdrUktkf98Bxkdim tX6Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=PgKydQ283kCxKymfkeo9fXBKb+pwyveUlMS1tfRsFkw=; b=V3qn0Gj+i1gXSAnKk4S7VPdAP8/XW3fVGcKmnAdK7UIhBCrLgTnHAYi4toaOhRqc34 NqQ9URYyB5FZK1Dyp2+QCUAEQJOTyyqY4bT7sdW02m+4y7Xo0zJgn88f23nOZ/0pkPiK sHE+U646L/SCywageg4E/tNIXpr+q98/OyHAuLx/YXt6lfpeIcHYeELxJNgKl/vewveA w28bcIvYt55KUk9XiJ4oKZgdptErrac4pzLol1yui3GQ5+QXZizDQkNOHLDApmKmI+7i 4f7CYczKpYpqOVIxJhb4AE0G+ICp3yi+uiqghmxolL2qqeUyWrFl2M2X4K6Vve/5gt/X 03Kw== X-Gm-Message-State: AOAM5337GOXf7AGCy+djXVvuT6V8koJDnBu9Vka4YHsGYdPOElmabUUd PKD9SBLqm0JRlwveGmEoPMQrfYKSEI1/UQ== X-Google-Smtp-Source: ABdhPJwoQY2bUhtM+FLWY3WoV/3cGLuMc0QmiCcwheIBt69C3ts4dFhq0JQZLWyUx//OKlnOuzUzKA== X-Received: by 2002:a7b:c0d3:: with SMTP id s19mr759190wmh.84.1597089044037; Mon, 10 Aug 2020 12:50:44 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 13/20] qga/qapi-schema.json: Add some headings Date: Mon, 10 Aug 2020 20:50:12 +0100 Message-Id: <20200810195019.25427-14-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::344; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x344.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Add some section headings to the QGA json; this is purely so that we have some H1 headings, as otherwise each command ends up being visible in the interop/ manual's table of contents. In an ideal world there might be a proper 'Introduction' section the way there is in qapi/qapi-schema.json. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- qga/qapi-schema.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index b1e9ed836de..401467860a7 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,14 +2,18 @@ # vim: filetype=3Dpython =20 ## -# -# General note concerning the use of guest agent interfaces: -# +# =3D General note concerning the use of guest agent interfaces +## + +## # "unsupported" is a higher-level error than the errors that individual # commands might document. The caller should always be prepared to receive # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn= 't # document any failure mode at all. -# +## + +## +# =3D QEMU guest agent protocol commands and structs ## =20 { 'pragma': { 'doc-required': true } } --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089568; cv=none; d=zohomail.com; s=zohoarc; b=QQPBanInJLKIVqC3UHRZjl7UGNuk0jN5GyFqs51F0V3pdLHKdrUPpLwB6M67ZPaYPN9QBZ2M0wjmaYpeUsIrU06uZ0pMfNfArocQ+cFEM9jkzp03Jm07y0e447ue2X3gOTRtKHAVsT6DOXPSQlqpXpvJz3YdovxySGUEtz4lEvo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089568; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=ul05RQOEBEfTMdEpHtLX0A67yI0APyniOjyDQ7PDnTY=; b=IF1V+J4aAnnhe5Gd8mHcAeTx+11pj84PmcBWwk2IIRqET8bnwkOI1u+Dn3raIFUnL2dzcjmkjYWgRceeZJe4jAuh2K64NEdPaEK0IM0k9TX0Fcw/+CsYbHA6bhvffK3po59TdZO6wzO0I+Ud09JbjaPuomx0hsRNuZGpTI3xAQQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089568605389.6784840869774; Mon, 10 Aug 2020 12:59:28 -0700 (PDT) Received: from localhost ([::1]:45234 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dx8-0001Ao-Sh for importer@patchew.org; Mon, 10 Aug 2020 15:59:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51252) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dor-0000vx-NX for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:53 -0400 Received: from mail-wr1-x443.google.com ([2a00:1450:4864:20::443]:40167) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Don-0004sR-9h for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:53 -0400 Received: by mail-wr1-x443.google.com with SMTP id l2so9308651wrc.7 for ; Mon, 10 Aug 2020 12:50:48 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=ul05RQOEBEfTMdEpHtLX0A67yI0APyniOjyDQ7PDnTY=; b=InJvmFMmQoU8GfWzIpI/9BJ5/NsnzcTwiuBeLmc294ykZDArzZNnvDMJQY9j9yn9Zb x8i7Rpz9EbihR/ghvVpu/cQ30cc5ZYLFzpTa9UNDDhQLl9XJBsIQKJU0adiV93BEFJ1p PAczKpWEo6lN3eN4V4Qx3PCR6amvVbl1YueYgDxofuSb+jcFRUX5OlDwI+albg9EXlnA mZMQ/6MnRW8aB3szlpGkk/iA7MmOUAdep0Cz9rcWmhz3upimyzkIo5C6vo8Xbi6j3To+ cxS08D4doNqIMSIL1G3Bs1sJpuPZ0vVCI+xthvO537PRa77u83zMhVL1R3dB9lkVBUnv RlFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=ul05RQOEBEfTMdEpHtLX0A67yI0APyniOjyDQ7PDnTY=; b=Pj5kbbH9tTTn8diHil5ga2yOWYLgwqnt7+WI8LN5o8255pNHIO+BMVqSl+CSV4pKzS glZVP8PUoj0Z8kmqBLdKQ1iPQ//kwUuj0JHtn2e/tn51eZrp5NEi5PQEEJyw9bZEd4VV DzEwUKuSTmxKxCpHWeKXVAJIPpziNIbReVlSG/R9BHqk9baHEl32B1+8ulc6piTNNa9u K9Pnd1Cp55ZWZKvo1jzHhymvdAmLlygdZRzPvIVfmp73z02KmH9sQ0Q0oyzZXYq5iEVm mRV01OCx1X5jyOt7lcfodk9c+BB7oPC9UVPv5Aj+oFGoDyicAJHMx9M16yU2ITbK2ljb QlQg== X-Gm-Message-State: AOAM530hhsxXwaBS3h/Wc1pC4sV+6qyJi2vVNZf/JetMKGzQrnvHsHUR 4HgI7msWhAUsa66qEA8jXgsv3mouGDdC0A== X-Google-Smtp-Source: ABdhPJweocpKR71/Yb7bJ3YgyOyBhVL4ZYjjwBjFgl+Vu4sBKQMxLGrH1A33eUMwY/OlVfAgZOZAHQ== X-Received: by 2002:adf:fc45:: with SMTP id e5mr27861778wrs.226.1597089046347; Mon, 10 Aug 2020 12:50:46 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 14/20] scripts/qapi: Remove texinfo generation support Date: Mon, 10 Aug 2020 20:50:13 +0100 Message-Id: <20200810195019.25427-15-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::443; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x443.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" We no longer use the generated texinfo format documentation, so delete the code that generates it, and the test case for the generation. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- Makefile | 1 - scripts/qapi-gen.py | 2 - scripts/qapi/doc.py | 302 ------------------------------ scripts/qapi/gen.py | 7 - tests/Makefile.include | 15 +- tests/qapi-schema/doc-good.texi | 313 -------------------------------- 6 files changed, 1 insertion(+), 639 deletions(-) delete mode 100644 scripts/qapi/doc.py delete mode 100644 tests/qapi-schema/doc-good.texi diff --git a/Makefile b/Makefile index 3df1cf68333..fc3ccc15030 100644 --- a/Makefile +++ b/Makefile @@ -626,7 +626,6 @@ qemu-keymap$(EXESUF): QEMU_CFLAGS +=3D $(XKBCOMMON_CFLA= GS) qapi-py =3D $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py index 4b03f7d53be..541e8c1f55d 100755 --- a/scripts/qapi-gen.py +++ b/scripts/qapi-gen.py @@ -10,7 +10,6 @@ import re import sys =20 from qapi.commands import gen_commands -from qapi.doc import gen_doc from qapi.events import gen_events from qapi.introspect import gen_introspect from qapi.schema import QAPIError, QAPISchema @@ -51,7 +50,6 @@ def main(argv): gen_commands(schema, args.output_dir, args.prefix) gen_events(schema, args.output_dir, args.prefix) gen_introspect(schema, args.output_dir, args.prefix, args.unmask) - gen_doc(schema, args.output_dir, args.prefix) =20 =20 if __name__ =3D=3D '__main__': diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py deleted file mode 100644 index 7764de1e4bc..00000000000 --- a/scripts/qapi/doc.py +++ /dev/null @@ -1,302 +0,0 @@ -# QAPI texi generator -# -# This work is licensed under the terms of the GNU LGPL, version 2+. -# See the COPYING file in the top-level directory. -"""This script produces the documentation of a qapi schema in texinfo form= at""" - -import re -from qapi.gen import QAPIGenDoc, QAPISchemaVisitor - - -MSG_FMT =3D """ -@deftypefn {type} {{}} {name} - -{body}{members}{features}{sections} -@end deftypefn - -""".format - -TYPE_FMT =3D """ -@deftp {{{type}}} {name} - -{body}{members}{features}{sections} -@end deftp - -""".format - -EXAMPLE_FMT =3D """@example -{code} -@end example -""".format - - -def subst_strong(doc): - """Replaces *foo* by @strong{foo}""" - return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) - - -def subst_emph(doc): - """Replaces _foo_ by @emph{foo}""" - return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) - - -def subst_vars(doc): - """Replaces @var by @code{var}""" - return re.sub(r'@([\w-]+)', r'@code{\1}', doc) - - -def subst_braces(doc): - """Replaces {} with @{ @}""" - return doc.replace('{', '@{').replace('}', '@}') - - -def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, = we - # need to delay it until after subst_vars() in texi_format(). - doc =3D subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=3Ddoc) - - -def texi_format(doc): - """ - Format documentation - - Lines starting with: - - |: generates an @example - - =3D: generates @section - - =3D=3D: generates @subsection - - 1. or 1): generates an @enumerate @item - - */-: generates an @itemize list - """ - ret =3D '' - doc =3D subst_braces(doc) - doc =3D subst_vars(doc) - doc =3D subst_emph(doc) - doc =3D subst_strong(doc) - inlist =3D '' - lastempty =3D False - for line in doc.split('\n'): - line =3D line.strip() - empty =3D line =3D=3D '' - - # FIXME: Doing this in a single if / elif chain is - # problematic. For instance, a line without markup terminates - # a list if it follows a blank line (reaches the final elif), - # but a line with some *other* markup, such as a =3D title - # doesn't. - # - # Make sure to update section "Documentation markup" in - # docs/devel/qapi-code-gen.txt when fixing this. - if line.startswith('| '): - line =3D EXAMPLE_FMT(code=3Dline[2:]) - elif line.startswith('=3D '): - line =3D '@section ' + line[2:] - elif line.startswith('=3D=3D '): - line =3D '@subsection ' + line[3:] - elif re.match(r'^([0-9]*\.) ', line): - if not inlist: - ret +=3D '@enumerate\n' - inlist =3D 'enumerate' - ret +=3D '@item\n' - line =3D line[line.find(' ')+1:] - elif re.match(r'^[*-] ', line): - if not inlist: - ret +=3D '@itemize %s\n' % {'*': '@bullet', - '-': '@minus'}[line[0]] - inlist =3D 'itemize' - ret +=3D '@item\n' - line =3D line[2:] - elif lastempty and inlist: - ret +=3D '@end %s\n\n' % inlist - inlist =3D '' - - lastempty =3D empty - ret +=3D line + '\n' - - if inlist: - ret +=3D '@end %s\n\n' % inlist - return ret - - -def texi_body(doc): - """Format the main documentation body""" - return texi_format(doc.body.text) - - -def texi_if(ifcond, prefix=3D'\n', suffix=3D'\n'): - """Format the #if condition""" - if not ifcond: - return '' - return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix) - - -def texi_enum_value(value, desc, suffix): - """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n%s%s' % ( - value.name, desc, texi_if(value.ifcond, prefix=3D'@*')) - - -def texi_member(member, desc, suffix): - """Format a table of members item for an object type member""" - typ =3D member.type.doc_type() - membertype =3D ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n%s%s' % ( - member.name, membertype, - ' (optional)' if member.optional else '', - suffix, desc, texi_if(member.ifcond, prefix=3D'@*')) - - -def texi_members(doc, what, base=3DNone, variants=3DNone, - member_func=3Dtexi_member): - """Format the table of members""" - items =3D '' - for section in doc.args.values(): - # TODO Drop fallbacks when undocumented members are outlawed - if section.text: - desc =3D texi_format(section.text) - elif (variants and variants.tag_member =3D=3D section.member - and not section.member.type.doc_type()): - values =3D section.member.type.member_names() - members_text =3D ', '.join(['@t{"%s"}' % v for v in values]) - desc =3D 'One of ' + members_text + '\n' - else: - desc =3D 'Not documented\n' - items +=3D member_func(section.member, desc, suffix=3D'') - if base: - items +=3D '@item The members of @code{%s}\n' % base.doc_type() - if variants: - for v in variants.variants: - when =3D ' when @code{%s} is @t{"%s"}%s' % ( - variants.tag_member.name, v.name, texi_if(v.ifcond, " (", = ")")) - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - items +=3D member_func(m, desc=3D'', suffix=3Dwhen) - else: - items +=3D '@item The members of @code{%s}%s\n' % ( - v.type.doc_type(), when) - if not items: - return '' - return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) - - -def texi_arguments(doc, boxed_arg_type): - if boxed_arg_type: - assert not doc.args - return ('\n@b{Arguments:} the members of @code{%s}\n' - % boxed_arg_type.name) - return texi_members(doc, 'Arguments') - - -def texi_features(doc): - """Format the table of features""" - items =3D '' - for section in doc.features.values(): - desc =3D texi_format(section.text) - items +=3D '@item @code{%s}\n%s' % (section.name, desc) - if not items: - return '' - return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items) - - -def texi_sections(doc, ifcond): - """Format additional sections following arguments""" - body =3D '' - for section in doc.sections: - if section.name: - # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body +=3D '\n@b{%s:}\n' % section.name - if section.name and section.name.startswith('Example'): - body +=3D texi_example(section.text) - else: - body +=3D texi_format(section.text) - body +=3D texi_if(ifcond, suffix=3D'') - return body - - -def texi_type(typ, doc, ifcond, members): - return TYPE_FMT(type=3Dtyp, - name=3Ddoc.symbol, - body=3Dtexi_body(doc), - members=3Dmembers, - features=3Dtexi_features(doc), - sections=3Dtexi_sections(doc, ifcond)) - - -def texi_msg(typ, doc, ifcond, members): - return MSG_FMT(type=3Dtyp, - name=3Ddoc.symbol, - body=3Dtexi_body(doc), - members=3Dmembers, - features=3Dtexi_features(doc), - sections=3Dtexi_sections(doc, ifcond)) - - -class QAPISchemaGenDocVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._prefix =3D prefix - self._gen =3D QAPIGenDoc(self._prefix + 'qapi-doc.texi') - self.cur_doc =3D None - - def write(self, output_dir): - self._gen.write(output_dir) - - def visit_enum_type(self, name, info, ifcond, features, members, prefi= x): - doc =3D self.cur_doc - self._gen.add(texi_type('Enum', doc, ifcond, - texi_members(doc, 'Values', - member_func=3Dtexi_enum_value= ))) - - def visit_object_type(self, name, info, ifcond, features, - base, members, variants): - doc =3D self.cur_doc - if base and base.is_implicit(): - base =3D None - self._gen.add(texi_type('Object', doc, ifcond, - texi_members(doc, 'Members', base, variant= s))) - - def visit_alternate_type(self, name, info, ifcond, features, variants): - doc =3D self.cur_doc - self._gen.add(texi_type('Alternate', doc, ifcond, - texi_members(doc, 'Members'))) - - def visit_command(self, name, info, ifcond, features, - arg_type, ret_type, gen, success_response, boxed, - allow_oob, allow_preconfig): - doc =3D self.cur_doc - self._gen.add(texi_msg('Command', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None)= )) - - def visit_event(self, name, info, ifcond, features, arg_type, boxed): - doc =3D self.cur_doc - self._gen.add(texi_msg('Event', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None)= )) - - def symbol(self, doc, entity): - if self._gen._body: - self._gen.add('\n') - self.cur_doc =3D doc - entity.visit(self) - self.cur_doc =3D None - - def freeform(self, doc): - assert not doc.args - if self._gen._body: - self._gen.add('\n') - self._gen.add(texi_body(doc) + texi_sections(doc, None)) - - -def gen_doc(schema, output_dir, prefix): - vis =3D QAPISchemaGenDocVisitor(prefix) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - vis.write(output_dir) diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py index bf5552a4e7f..ca66c82b5b8 100644 --- a/scripts/qapi/gen.py +++ b/scripts/qapi/gen.py @@ -178,13 +178,6 @@ def ifcontext(ifcond, *args): arg.end_if() =20 =20 -class QAPIGenDoc(QAPIGen): - - def _top(self): - return (super()._top() - + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') - - class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor): =20 def __init__(self, prefix, what, blurb, pydoc): diff --git a/tests/Makefile.include b/tests/Makefile.include index c7e4646ded7..ec83efeaa63 100644 --- a/tests/Makefile.include +++ b/tests/Makefile.include @@ -38,7 +38,6 @@ export SRC_PATH qapi-py =3D $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ @@ -501,16 +500,8 @@ tests/test-qapi-gen-timestamp: \ $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ -o tests -p "test-" $<, \ "GEN","$(@:%-timestamp=3D%)") - @rm -f tests/test-qapi-doc.texi @>$@ =20 -tests/qapi-schema/doc-good.test.texi: $(SRC_PATH)/tests/qapi-schema/doc-go= od.json $(qapi-py) - $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ - -o tests/qapi-schema -p "doc-good-" $<, \ - "GEN","$@") - @mv tests/qapi-schema/doc-good-qapi-doc.texi $@ - @rm -f tests/qapi-schema/doc-good-qapi-*.[ch] tests/qapi-schema/doc-good-= qmp-*.[ch] - tests/qtest/dbus-vmstate1.h tests/qtest/dbus-vmstate1.c: tests/qtest/dbus-= vmstate1-gen-timestamp ; tests/qtest/dbus-vmstate1-gen-timestamp: $(SRC_PATH)/tests/qtest/dbus-vmst= ate1.xml $(call quiet-command,$(GDBUS_CODEGEN) $< \ @@ -891,10 +882,6 @@ check-tests/qapi-schema/frontend: $(addprefix $(SRC_PA= TH)/, $(check-qapi-schema- PYTHONIOENCODING=3Dutf-8 $(PYTHON) $(SRC_PATH)/tests/qapi-schema/test-q= api.py $^, \ TEST, check-qapi-schema) =20 -.PHONY: check-tests/qapi-schema/doc-good.texi -check-tests/qapi-schema/doc-good.texi: tests/qapi-schema/doc-good.test.texi - @diff -u $(SRC_PATH)/tests/qapi-schema/doc-good.texi $< - .PHONY: check-decodetree check-decodetree: $(call quiet-command, \ @@ -956,7 +943,7 @@ check-acceptance: check-venv $(TESTS_RESULTS_DIR) get-v= m-images # Consolidated targets =20 .PHONY: check-block check-qapi-schema check-qtest check-unit check check-c= lean get-vm-images -check-qapi-schema: check-tests/qapi-schema/frontend check-tests/qapi-schem= a/doc-good.texi +check-qapi-schema: check-tests/qapi-schema/frontend check-qtest: $(patsubst %,check-qtest-%, $(QTEST_TARGETS)) ifeq ($(CONFIG_TOOLS),y) check-block: $(patsubst %,check-%, $(check-block-y)) diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.t= exi deleted file mode 100644 index 12808989ffb..00000000000 --- a/tests/qapi-schema/doc-good.texi +++ /dev/null @@ -1,313 +0,0 @@ -@c AUTOMATICALLY GENERATED, DO NOT MODIFY - -@section Section - -@subsection Subsection - -@strong{strong} @emph{with emphasis} -@code{var} @{in braces@} - -@itemize @bullet -@item -List item one -@item -Two, multiple -lines - -@item -Three -Still in list - -@end itemize - -Not in list - -@itemize @minus -@item -Second list -Note: still in list - -@end itemize - -Note: not in list - -@enumerate -@item -Third list -is numbered - -@item -another item - -@end enumerate - -Returns: the King -Since: the first age -Notes: - -@enumerate -@item -Lorem ipsum dolor sit amet - -@item -Ut enim ad minim veniam - -@end enumerate - -Duis aute irure dolor - -Example: - --> in -<- out -Examples: -@itemize @minus -@item -@strong{verbatim} -@item -@{braces@} -@end itemize - - - -@deftp {Enum} Enum - - - -@b{Values:} -@table @asis -@item @code{one} -The @emph{one} @{and only@} -@*@b{If:} @code{defined(IFONE)} -@item @code{two} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{enum-feat} -Also @emph{one} @{and only@} -@end table -@code{two} is undocumented - -@b{If:} @code{defined(IFCOND)} -@end deftp - - - -@deftp {Object} Base - - - -@b{Members:} -@table @asis -@item @code{base1: Enum} -the first member -@end table - -@end deftp - - - -@deftp {Object} Variant1 - -A paragraph - -Another paragraph (but no @code{var}: line) - -@b{Members:} -@table @asis -@item @code{var1: string} -Not documented -@*@b{If:} @code{defined(IFSTR)} -@end table - -@b{Features:} -@table @asis -@item @code{variant1-feat} -a feature -@item @code{member-feat} -a member feature -@end table - -@end deftp - - - -@deftp {Object} Variant2 - - - -@end deftp - - - -@deftp {Object} Object - - - -@b{Members:} -@table @asis -@item The members of @code{Base} -@item The members of @code{Variant1} when @code{base1} is @t{"one"} -@item The members of @code{Variant2} when @code{base1} is @t{"two"} (@b{If= :} @code{IFTWO}) -@end table - -@b{Features:} -@table @asis -@item @code{union-feat1} -a feature -@end table - -@end deftp - - - -@deftp {Object} SugaredUnion - - - -@b{Members:} -@table @asis -@item @code{type} -One of @t{"one"}, @t{"two"} -@item @code{data: Variant1} when @code{type} is @t{"one"} -@item @code{data: Variant2} when @code{type} is @t{"two"} (@b{If:} @code{I= FTWO}) -@end table - -@b{Features:} -@table @asis -@item @code{union-feat2} -a feature -@end table - -@end deftp - - - -@deftp {Alternate} Alternate - - - -@b{Members:} -@table @asis -@item @code{i: int} -an integer -@code{b} is undocumented -@item @code{b: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{alt-feat} -a feature -@end table - -@end deftp - - -@subsection Another subsection - - -@deftypefn Command {} cmd - - - -@b{Arguments:} -@table @asis -@item @code{arg1: int} -the first argument -@item @code{arg2: string} (optional) -the second -argument -@item @code{arg3: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Note:} -@code{arg3} is undocumented - -@b{Returns:} -@code{Object} - -@b{TODO:} -frobnicate - -@b{Notes:} -@itemize @minus -@item -Lorem ipsum dolor sit amet -@item -Ut enim ad minim veniam - -@end itemize - -Duis aute irure dolor - -@b{Example:} -@example --> in -<- out -@end example - -@b{Examples:} -@example -- *verbatim* -- @{braces@} -@end example - -@b{Since:} -2.10 - -@end deftypefn - - - -@deftypefn Command {} cmd-boxed - -If you're bored enough to read this, go see a video of boxed cats - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Example:} -@example --> in - -<- out -@end example - -@end deftypefn - - - -@deftypefn Event {} EVT-BOXED - - - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{feat3} -a feature -@end table - -@end deftypefn - --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089349; cv=none; d=zohomail.com; s=zohoarc; b=FVAulcHcrOgLJHn8D/Qg187fXjfZC+rWmr47mz5+7iYDNqbqtvAV2biOvyp6u4yDA/9Tyb4wJaUaCjgYL/sRCr+z+gz2WMPzgac6cK7LvMOqCU+QIv6YYJxixYp9tD658fcmRhE/Ii/1G+gOKGgeut7U+WJABKa8zuhteTzzM7s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089349; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=cp52Tz1lECqYI3uEVQbbG4Lu/4PnK1R1by9RglA8G/g=; b=dsWZxHLrFiqawLmJxPdu9AEaFAWPKfWicHku+806BH74DvGknjZvKmqsloevSdPG+eMeN7OpWbYnOZUpkrION15FQm5dyHdxOpyCoNMSKGSuqOnlg6B482bCYu9UZURugVIuKqv2OAgGszAgHrK8ULceN4AAeeXhyOerRrzwtLk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089349905991.0844802612825; Mon, 10 Aug 2020 12:55:49 -0700 (PDT) Received: from localhost ([::1]:57446 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dtc-00039p-Lt for importer@patchew.org; Mon, 10 Aug 2020 15:55:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51240) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doq-0000sO-8V for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:52 -0400 Received: from mail-wm1-x32c.google.com ([2a00:1450:4864:20::32c]:52422) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Don-0004tG-VB for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:51 -0400 Received: by mail-wm1-x32c.google.com with SMTP id x5so606191wmi.2 for ; Mon, 10 Aug 2020 12:50:49 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cp52Tz1lECqYI3uEVQbbG4Lu/4PnK1R1by9RglA8G/g=; b=zLSxyn2lgqXet73mPvGJK+Yi84f3FsWZcQSRGfjvGHe8BNBMvyp/cOf96+pIyUk2sB DIXItBkcyIFGZ50H24jTGL+P8uumiNnIvXYlz1/0xbIQpCnsEXIaXcZRRfjq8ri1u0v9 0OSra/3UyNq1gmJm6XrtoFcIbv8Grzjf9u3d7u9NolIY3mk/EsyxG5p1yLDeUu21jUw9 wlOhok6emZubW5p5Q7WfHji9YY0+w/4ZmOafuzfrc9byfwc672k5jIUv0z1m1H58Yp+4 s4b6b9uglprNjJJ2yul4a8phM130aksvHn9rsP3pOurLn+gL48haNU6jUUGPtlsjl9oA 1F3w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cp52Tz1lECqYI3uEVQbbG4Lu/4PnK1R1by9RglA8G/g=; b=UdWp4VG81sn44rVX3q0P9GG6seOGrqeClYOG6tTnvJyz+9woareFkWsi1dc0sSIbMS WGqIyNN7BGdz4Iz3o68DCrfrneS99zKdvovy55pqbpY+ftEw0059MM4sXyIv2YBkmHKR 0PQY2cNY9CCnHizJWDXsO1pJzJFnZfYDLyH4bGMDEw1NgYbiSoL8W36S9ipxMFlfH3Xn xrmlkZ5CC0iCuT2V45hiP2xeQdYHqkSNYUgkk7HPpmGbNI/Y1UDg/MlxOyt/AsRB9FHG IA1L88QzK4PEqnABuPCbV7cJQYhIDdkXXh7qeibtjd8WbZKDJoLxGfLlOXp4pc9D1wIt MvRA== X-Gm-Message-State: AOAM532NzMiiVDCyM49ltODO5NVWoWPFIsgUSBHs8FQ7GtsGP0xiZeuw 8JdD984k4JXPvspbLUp9OLGgdIMXjjs+1g== X-Google-Smtp-Source: ABdhPJxlDBFgmzwgzRHu1GHLAFG2KcqjaPdVn2Gu4K6ndq8gNfiUAZ3oVtljK4Q9UUmDknIKb1C4IA== X-Received: by 2002:a05:600c:2888:: with SMTP id g8mr802278wmd.118.1597089047684; Mon, 10 Aug 2020 12:50:47 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Mon, 10 Aug 2020 20:50:14 +0100 Message-Id: <20200810195019.25427-16-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32c; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32c.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Update the documentation of QAPI document comment syntax to match the new rST backend requirements. The principal changes are: * whitespace is now significant, and multiline definitions must have their second and subsequent lines indented to match the first line * general rST format markup is permitted, not just the small set of markup the old texinfo generator handled. For most things (notably bulleted and itemized lists) the old format is the same as rST was. * Specific things that might trip people up: - instead of *bold* and _italic_ rST has **bold** and *italic* - lists need a preceding and following blank line - a lone literal '*' will need to be backslash-escaped to avoid a rST syntax error * the old leading '|' for example (literal text) blocks is replaced by the standard rST '::' literal block. * headings and subheadings must now be in a freeform documentation comment of their own * we support arbitrary levels of sub- and sub-sub-heading, not just a main and sub-heading like the old texinfo generator Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 69eede6c283..263f1c0b44c 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -824,21 +824,39 @@ See below for more on definition documentation. Free-form documentation may be used to provide additional text and structuring content. =20 +=3D=3D=3D=3D Headings and subheadings =3D=3D=3D=3D + +A free-form documentation comment containing a single line +which starts with some '=3D' symbols and then a space defines +a section heading: + + ## + # =3D This is a top level heading + ## + + ## + # This is a free-form comment which will go under the + # top level heading. + ## + + ## + # =3D=3D This is a second level heading + ## + +Section headings must always be correctly nested, so you can only +define a third-level heading inside a second-level heading, and so +on. The documentation generator will catch nesting mistakes and report +a syntax error. =20 =3D=3D=3D=3D Documentation markup =3D=3D=3D=3D =20 -Comment text starting with '=3D' is a section title: +Documentation comments can use most rST markup. In particular, +a '::' literal block can be used for examples: =20 - # =3D Section title - -Double the '=3D' for a subsection title: - - # =3D=3D Subsection title - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines =20 '*' starts an itemized list: =20 @@ -854,37 +872,35 @@ A decimal number followed by '.' starts a numbered li= st: # multiple lines # 2. Second item =20 -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. +The actual number doesn't matter. =20 -Lists can't be nested. Blank lines are currently not supported within -lists. +Lists of either kind must be preceded and followed by a blank line. +If a list item's text spans multiple lines, then the second and +subsequent lines must be correctly indented to line up with the +first character of the first line. =20 -Additional whitespace between the initial '#' and the comment text is -permitted. - -*foo* and _foo_ are for strong and emphasis styles respectively (they -do not work over multiple lines). @foo is used to reference a name in -the schema. +The usual '**strong**', '*emphasised*' and '``literal``' markup should +be used. If you need a single literal '*' you will need to backslash-escap= e it. +As an extension beyond the usual rST syntax, you can also +use '@foo' to reference a name in the schema; this is rendered +the same way as '``foo``'. =20 Example: =20 ## -# =3D Section -# =3D=3D Subsection -# -# Some text foo with *strong* and _emphasis_ +# Some text foo with **bol** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## =20 - =3D=3D=3D=3D Definition documentation =3D=3D=3D=3D =20 Definition documentation, if present, must immediately precede the @@ -899,6 +915,12 @@ commands and events), member (for structs and unions),= branch (for alternates), or value (for enums), and finally optional tagged sections. =20 +Descriptions of arguments can span multiple lines; if they +do then the second and subsequent lines must be indented +to line up with the first character of the first line of the +description. The parser will report a syntax error if there +is insufficient indentation. + FIXME: the parser accepts these things in almost any order. FIXME: union branches should be described, too. =20 @@ -912,6 +934,16 @@ The section ends with the start of a new section. A 'Since: x.y.z' tagged section lists the release that introduced the definition. =20 +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first. + +An 'Example' or 'Examples' section is automatically rendered +entirely as literal fixed-width text. In other sections, +the text is formatted, and rST markup can be used. + For example: =20 ## --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089646; cv=none; d=zohomail.com; s=zohoarc; b=PTMjA30vwJtfOtpdBT4/7NkszOaTeZCwEQOSCIf1FzGNL7W75bI9xvNibMDT0aT/AGJ1GG2JAXtmNpa0EZ8a4ffRtZBGppaDxeiBgE+xhEmi7oFVL4ONphZNSad1CHdRzywHjamGgnY/Z/rHHJqNDfu745L73uXdepMqYGWhnYs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089646; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=4PyfQa7ahU945SxQ17WhvHpJu4ijwLrsrnt3XXoa7zs=; b=nwZ5XZKz7g/DYslFTL3J8Gs3MiEm0URCG65ugqF5T+pFIwXUzuHptE13QRuyRhudznZCGVaZ+jfLIQhv9j+QALX6vdM7LiZDHuh4h8cE0BCcu8alDZ608UkvSDNCeAIEBtyi6OU5m/SNXCBn8Y7mfSfjiVVbCFDAGLxF2U1wNXg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089645761323.47027148201664; Mon, 10 Aug 2020 13:00:45 -0700 (PDT) Received: from localhost ([::1]:49276 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DyM-0002wA-Hy for importer@patchew.org; Mon, 10 Aug 2020 16:00:42 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51262) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dot-0000z1-0P for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:55 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:45366) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Doq-0004uv-Rw for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:54 -0400 Received: by mail-wr1-x444.google.com with SMTP id z18so9297904wrm.12 for ; Mon, 10 Aug 2020 12:50:52 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=4PyfQa7ahU945SxQ17WhvHpJu4ijwLrsrnt3XXoa7zs=; b=FgJM1Jy9C1ig1fGoH+pMZIRzN3e75IH2TckgsHj9aKpRKDd8yyF9m9jCaOXfkQZua8 0L2GmqeF2EJvogAMEilz+Es6F4Bim7OH30qJsNOFla89OTc+dINiXOqK2N3gcHdqjPg0 ArIzPBSVujv7GU5fT4NM7Yx+y8UV1YlO/Uudc9MrfD0pWqSR6c3lC/vO+6CQt1zXuvqf zg+gbKtq2/r30CvHL7Vlj8/0n0j+9PmCSVDgDc3/Dsrudz0KNe5QsYqEGO4HjfMrJjc7 Co/sY/JLtpOC9iWsEe9luzei8wcKlgJlhiSIVH8YCBcyetkYgOBWv9CJ1yKUeZnnoyrf Zkaw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=4PyfQa7ahU945SxQ17WhvHpJu4ijwLrsrnt3XXoa7zs=; b=iGs0qDm8LGr7YzFwJrVTb2pGCQ+PFC6t6m0Lnd94QqM38ASNo8HyYjT0sqZvt4UVb6 Y4vQ1e5JnWwXmbUrktQZRaleasxN00LJAi3+V7mXa5LA7pR/QrE7tP8m1JWJ3ulnh2+r pSZldRumyYM74IQb3gQcOXw9ZOdvPuyTJQ+v4x/nafaNciQaMu5fXzlRx10tvVtHrakl Xant4elycnd7ShrTQKg/TUwMMBpYblG0AmuoltWTJG2sm52Or76vCVVRg00uBlRBWppJ hy6V3aYuBwhpkOFyaW9e/oATaexszE2Q31B4V/EP7+VePdKFeUlE3u4y4rid7SVibjG+ 845A== X-Gm-Message-State: AOAM530MMbQ6+RD7igrGw/4g0TwDE17dNiOm/U8uSlQhWp16herm8ddi XePYCONZh7yykx950EGFkAnAtTNo+w4u6g== X-Google-Smtp-Source: ABdhPJxTgoILl2GusDc29acGF0+QwedND82L+3/InJ5HGSrf5HQCgjib3gRenbtqxO4IAflw9PJqRA== X-Received: by 2002:a5d:5273:: with SMTP id l19mr25808161wrc.257.1597089049283; Mon, 10 Aug 2020 12:50:49 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 16/20] Makefile: Remove redundant Texinfo related rules Date: Mon, 10 Aug 2020 20:50:15 +0100 Message-Id: <20200810195019.25427-17-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::444; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x444.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" We now don't build anything from Texinfo, so we can remove some redundant Makefile pattern rules and the rule for generating the version.texi file that used to be included from many Texinfo source files. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- Makefile | 31 +------------------------------ rules.mak | 14 +------------- 2 files changed, 2 insertions(+), 43 deletions(-) diff --git a/Makefile b/Makefile index fc3ccc15030..1bc0f4f1d5c 100644 --- a/Makefile +++ b/Makefile @@ -759,8 +759,7 @@ clean: recurse-clean ! -path ./roms/edk2/BaseTools/Source/Python/UPT/Dll/sqlite3.dll \ -exec rm {} + rm -f $(edk2-decompressed) - rm -f $(filter-out %.tlb,$(TOOLS)) $(HELPERS-y) TAGS cscope.* *.pod *~ */= *~ - rm -f fsdev/*.pod scsi/*.pod + rm -f $(filter-out %.tlb,$(TOOLS)) $(HELPERS-y) TAGS cscope.* *~ */*~ rm -f qemu-img-cmds.h rm -f ui/shader/*-vert.h ui/shader/*-frag.h @# May not be present in generated-files-y @@ -795,7 +794,6 @@ distclean: clean rm -f qemu-plugins-ld.symbols qemu-plugins-ld64.symbols rm -f config.log rm -f linux-headers/asm - rm -f docs/version.texi rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -1015,31 +1013,6 @@ ui/shader.o: $(SRC_PATH)/ui/shader.c \ ui/shader/texture-blit-frag.h =20 # documentation -MAKEINFO=3Dmakeinfo -MAKEINFOINCLUDES=3D -I docs -I $( $@,"GEN","$@") - -%.html: %.texi docs/version.texi - $(call quiet-command,LC_ALL=3DC $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers= \ - --html $< -o $@,"GEN","$@") - -%.info: %.texi docs/version.texi - $(call quiet-command,$(MAKEINFO) $(MAKEINFOFLAGS) $< -o $@,"GEN","$@") - -%.txt: %.texi docs/version.texi - $(call quiet-command,LC_ALL=3DC $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers= \ - --plaintext $< -o $@,"GEN","$@") - -%.pdf: %.texi docs/version.texi - $(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@") =20 # Sphinx builds all its documentation at once in one invocation # and handles "don't rebuild things unless necessary" itself. @@ -1109,8 +1082,6 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index= .html.in qemu-version.h =20 html: sphinxdocs =20 -$(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl - # Reports/Analysis =20 %/coverage-report.html: diff --git a/rules.mak b/rules.mak index 694865b63ee..1dc2a353ee6 100644 --- a/rules.mak +++ b/rules.mak @@ -144,7 +144,7 @@ cc-option =3D $(if $(shell $(CC) $1 $2 -S -o /dev/null = -xc /dev/null \ cc-c-option =3D $(if $(shell $(CC) $1 $2 -c -o /dev/null -xc /dev/null \ >/dev/null 2>&1 && echo OK), $2, $3) =20 -VPATH_SUFFIXES =3D %.c %.h %.S %.cc %.cpp %.m %.mak %.texi %.sh %.rc Kconf= ig% %.json.in +VPATH_SUFFIXES =3D %.c %.h %.S %.cc %.cpp %.m %.mak %.sh %.rc Kconfig% %.j= son.in set-vpath =3D $(if $1,$(foreach PATTERN,$(VPATH_SUFFIXES),$(eval vpath $(P= ATTERN) $1))) =20 # install-prog list, dir @@ -381,18 +381,6 @@ define unnest-vars $(eval $v :=3D $(filter-out %/,$($v)))) endef =20 -TEXI2MAN =3D $(call quiet-command, \ - perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $(TEXI2PODFLAGS) $< $@.pod &&= \ - $(POD2MAN) --section=3D$(subst .,,$(suffix $@)) --center=3D" " --release= =3D" " $@.pod > $@, \ - "GEN","$@") - -%.1: - $(call TEXI2MAN) -%.7: - $(call TEXI2MAN) -%.8: - $(call TEXI2MAN) - GEN_SUBST =3D $(call quiet-command, \ sed -e "s!@libexecdir@!$(libexecdir)!g" < $< > $@, \ "GEN","$@") --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089428; cv=none; d=zohomail.com; s=zohoarc; b=lzBzJ2Pl6QKwqQLfVVfuLHPYrG8bhYTRqWEwWAc3La4vUUUrFePdwakHezqlrYnB0UbT0DdL6EZS6dAmjMCeoFBxBhJydEm60xDT+uY+H6NLAMojhbYt3O6PqFfQxgLvIfUfJvBf5VRkS/TV8klt1r5i02//WosZjAamdPTef5I= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089428; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=cfaupfHHa4V+s23hG9/Bjmpg/wW2cFKWyH8VgXgZUPI=; b=O21KVohm6wCLe/hQfek61PFeEjie5UfEj3IJT4Yi1UynnG+/KDW2yS8mKUPR3cMWJNY+lJ6Od9ocBWzCRV9Ij3sPQqlZCmH8nrZv+Fqmf7LIA2Sr8fPcGOWjfRxDMMCzL8VRFLMkGx/X29ceGsPPkN4h5L3de6LkVjuqEQvG7qg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089428070698.8019207235507; Mon, 10 Aug 2020 12:57:08 -0700 (PDT) Received: from localhost ([::1]:36542 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5Dus-00066C-IZ for importer@patchew.org; Mon, 10 Aug 2020 15:57:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51284) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dou-00013D-M8 for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:56 -0400 Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]:36076) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dor-0004wt-Pu for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:56 -0400 Received: by mail-wr1-x430.google.com with SMTP id 88so9309675wrh.3 for ; Mon, 10 Aug 2020 12:50:53 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cfaupfHHa4V+s23hG9/Bjmpg/wW2cFKWyH8VgXgZUPI=; b=WISLvgOM1ZpOeTM/icunBwx0KRE1jZ4jtRRV7TylQ5qVd6kksMD0XYvaCdG/LvjSpH mn9n6TwgwsFiwU8JiXH65pfC/DyXTDDtRFXbuDTCXqGRNvJ/QmsQEbXyCl/D7AdQVDM2 W4AfCG7o51NbIraKLR59igWDAEBYrORfNoZZV6Ce+cyrbV1E8cOk+snAJBrWV62Z3Ty2 ulAVD6US7XiRLxEGDR5zUcs26ZmPfyB81dihz33OJmulcVPQCBZd3e8pQNWy3o9yQnEg /rCuxAmBbFaA9WrDysPqMcIeTpJxtyd4udp59U0hjvnejz+wvU7cXciJ90QVAlv9pTPL ruOA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cfaupfHHa4V+s23hG9/Bjmpg/wW2cFKWyH8VgXgZUPI=; b=Ey+RohszxXWPiBvtr2IblkuyULQp7Jxxzciuktga9OM2yUM+0NTmmTWQmYzErIlpYO a1g5LqWiwOUtSKFR2s8jyfEWnZYvK3b8pD691mTuO8wGblkxrUww2nymOoEr0pjTXN7F kFYjR5ao8fh4uFrta08I8Jy9upBjwpRk9KmCGIwY47Fbqa4qmEXXAkIO4k9osQAUX+OI doJJ2caLD74cqtpbUv3HZ3ULw2MmyQhuehvUj0jyxa3nDLwBvvkb2RCzy+CC9ZE499MO sDLsWZrj7qU0n84ZfBOzmXirG4WoaVC4FSM349fJyi0bo5ro1mfo8qNy8p7zPrLt1GYq 05kg== X-Gm-Message-State: AOAM5326XQnuM4JPjbBhFeKQ25qd1mV2MgieKVuvWJnHNPFhrSl8Bxkm VFLLDhFcnaKa8XsrZt/1NfAegdpqxANrAg== X-Google-Smtp-Source: ABdhPJyiM91moPGSZvw9q92dsVOhlK9w/K10HgTl+Hf5Fjc5M+kmXumuQqjtMGT0oCPbyXKMDX0PZg== X-Received: by 2002:a5d:4604:: with SMTP id t4mr2820928wrq.417.1597089051073; Mon, 10 Aug 2020 12:50:51 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 17/20] scripts/texi2pod: Delete unused script Date: Mon, 10 Aug 2020 20:50:16 +0100 Message-Id: <20200810195019.25427-18-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::430; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x430.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" We no longer need the texi2pod script, so we can delete it, and the special-casing it had in the checkpatch script. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- scripts/checkpatch.pl | 2 +- scripts/texi2pod.pl | 536 ------------------------------------------ 2 files changed, 1 insertion(+), 537 deletions(-) delete mode 100755 scripts/texi2pod.pl diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index bd3faa154c3..b9935e0b650 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -1659,7 +1659,7 @@ sub process { # tabs are only allowed in assembly source code, and in # some scripts we imported from other projects. next if ($realfile =3D~ /\.(s|S)$/); - next if ($realfile =3D~ /(checkpatch|get_maintainer|texi2pod)\.pl$/); + next if ($realfile =3D~ /(checkpatch|get_maintainer)\.pl$/); =20 if ($rawline =3D~ /^\+.*\t/) { my $herevet =3D "$here\n" . cat_vet($rawline) . "\n"; diff --git a/scripts/texi2pod.pl b/scripts/texi2pod.pl deleted file mode 100755 index 8bfc6f6f4c4..00000000000 --- a/scripts/texi2pod.pl +++ /dev/null @@ -1,536 +0,0 @@ -#! /usr/bin/env perl - -# Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc. - -# This file is part of GCC. - -# GCC is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# GCC is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GCC; see the file COPYING. If not, -# see . - -# This does trivial (and I mean _trivial_) conversion of Texinfo -# markup to Perl POD format. It's intended to be used to extract -# something suitable for a manpage from a Texinfo document. - -use warnings; - -$output =3D 0; -$skipping =3D 0; -%sects =3D (); -$section =3D ""; -@icstack =3D (); -@endwstack =3D (); -@skstack =3D (); -@instack =3D (); -$shift =3D ""; -%defs =3D (); -$fnno =3D 1; -$inf =3D ""; -$ibase =3D ""; -@ipath =3D (); -$encoding =3D undef; -@args =3D (); - -while ($_ =3D shift) { - if (/^-D(.*)$/) { - if ($1 ne "") { - $flag =3D $1; - } else { - $flag =3D shift; - } - $value =3D ""; - ($flag, $value) =3D ($flag =3D~ /^([^=3D]+)(?:=3D(.+))?/); - die "no flag specified for -D\n" - unless $flag ne ""; - die "flags may only contain letters, digits, hyphens, dashes and undersco= res\n" - unless $flag =3D~ /^[a-zA-Z0-9_-]+$/; - $defs{$flag} =3D $value; - } elsif (/^-I(.*)$/) { - if ($1 ne "") { - $flag =3D $1; - } else { - $flag =3D shift; - } - push (@ipath, $flag); - } elsif (/^-/) { - usage(); - } else { - $in =3D $_, next unless defined $in; - $out =3D $_, next unless defined $out; - usage(); - } -} - -if (defined $in) { - $inf =3D gensym(); - open($inf, "<$in") or die "opening \"$in\": $!\n"; - $ibase =3D $1 if $in =3D~ m|^(.+)/[^/]+$|; -} else { - $inf =3D \*STDIN; -} - -if (defined $out) { - open(STDOUT, ">$out") or die "opening \"$out\": $!\n"; -} - -while(defined $inf) { -while(<$inf>) { - # Certain commands are discarded without further processing. - /^\@(?: - [a-z]+index # @*index: useful only in complete manual - |need # @need: useful only in printed manual - |(?:end\s+)?group # @group .. @end group: ditto - |page # @page: ditto - |node # @node: useful only in .info file - |(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents - )\b/x and next; - - chomp; - - # Look for filename and title markers. - /^\@setfilename\s+([^.]+)/ and $fn =3D $1, next; - /^\@settitle\s+([^.]+)/ and $tl =3D postprocess($1), next; - - # Look for document encoding - /^\@documentencoding\s+([^.]+)/ and do { - $encoding =3D $1 unless defined $encoding; - next; - }; - - # Identify a man title but keep only the one we are interested in. - /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do { - if (exists $defs{$1}) { - $fn =3D $1; - $tl =3D postprocess($2); - } - next; - }; - - # Look for blocks surrounded by @c man begin SECTION ... @c man end. - # This really oughta be @ifman ... @end ifman and the like, but such - # would require rev'ing all other Texinfo translators. - /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do { - $output =3D 1 if exists $defs{$2}; - $sect =3D $1; - next; - }; - /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect =3D $1, $output =3D 1, next; - /^\@c\s+man\s+end/ and do { - $sects{$sect} =3D "" unless exists $sects{$sect}; - $sects{$sect} .=3D postprocess($section); - $section =3D ""; - $output =3D 0; - next; - }; - - # handle variables - /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do { - $defs{$1} =3D $2; - next; - }; - /^\@clear\s+([a-zA-Z0-9_-]+)/ and do { - delete $defs{$1}; - next; - }; - - # Single line command handlers. - - /^\@include\s+(.+)$/ and do { - push @instack, $inf; - $inf =3D gensym(); - $file =3D postprocess($1); - - # Try cwd and $ibase, then explicit -I paths. - $done =3D 0; - foreach $path ("", $ibase, @ipath) { - $mypath =3D $file; - $mypath =3D $path . "/" . $mypath if ($path ne ""); - open($inf, "<" . $mypath) and ($done =3D 1, last); - } - die "cannot find $file" if !$done; - next; - }; - - next unless $output; - - # Discard comments. (Can't do it above, because then we'd never see - # @c man lines.) - /^\@c\b/ and next; - - # End-block handler goes up here because it needs to operate even - # if we are skipping. - /^\@end\s+([a-z]+)/ and do { - # Ignore @end foo, where foo is not an operation which may - # cause us to skip, if we are presently skipping. - my $ended =3D $1; - next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex|copyi= ng)$/; - - die "\@end $ended without \@$ended at line $.\n" unless defined $endw; - die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw; - - $endw =3D pop @endwstack; - - if ($ended =3D~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) { - $skipping =3D pop @skstack; - next; - } elsif ($ended =3D~ /^(?:example|smallexample|display - |quotation|deftp|deftypefn)$/x) { - $shift =3D ""; - $_ =3D ""; # need a paragraph break - } elsif ($ended =3D~ /^(?:itemize|enumerate|[fv]?table)$/) { - $_ =3D "\n=3Dback\n"; - $ic =3D pop @icstack; - } elsif ($ended eq "multitable") { - $_ =3D "\n=3Dback\n"; - } else { - die "unknown command \@end $ended at line $.\n"; - } - }; - - # We must handle commands which can cause skipping even while we - # are skipping, otherwise we will not process nested conditionals - # correctly. - /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw =3D "ifset"; - $skipping =3D 1 unless exists $defs{$1}; - next; - }; - - /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw =3D "ifclear"; - $skipping =3D 1 if exists $defs{$1}; - next; - }; - - /^\@(ignore|menu|iftex|copying)\b/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw =3D $1; - $skipping =3D 1; - next; - }; - - next if $skipping; - - # Character entities. First the ones that can be replaced by raw text - # or discarded outright: - s/\@copyright\{\}/(c)/g; - s/\@dots\{\}/.../g; - s/\@enddots\{\}/..../g; - s/\@([.!? ])/$1/g; - s/\@[:-]//g; - s/\@bullet(?:\{\})?/*/g; - s/\@TeX\{\}/TeX/g; - s/\@pounds\{\}/\#/g; - s/\@minus(?:\{\})?/-/g; - s/\\,/,/g; - - # Now the ones that have to be replaced by special escapes - # (which will be turned back into text by unmunge()) - s/&/&/g; - s/\@\{/{/g; - s/\@\}/}/g; - s/\@\@/&at;/g; - - # Inside a verbatim block, handle @var specially. - if ($shift ne "") { - s/\@var\{([^\}]*)\}/<$1>/g; - } - - # POD doesn't interpret E<> inside a verbatim block. - if ($shift eq "") { - s//>/g; - } else { - s//>/g; - } - - /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ - and $_ =3D "\n=3Dhead2 $1\n"; - /^\@subsection\s+(.+)$/ - and $_ =3D "\n=3Dhead3 $1\n"; - /^\@subsubsection\s+(.+)$/ - and $_ =3D "\n=3Dhead4 $1\n"; - - # Block command handlers: - /^\@itemize(?:\s+(\@[a-z]+|\*|-))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic =3D $1; - } else { - $ic =3D '*'; - } - $_ =3D "\n=3Dover 4\n"; - $endw =3D "itemize"; - }; - - /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic =3D $1 . "."; - } else { - $ic =3D "1."; - } - $_ =3D "\n=3Dover 4\n"; - $endw =3D "enumerate"; - }; - - /^\@multitable\s.*/ and do { - push @endwstack, $endw; - $endw =3D "multitable"; - $_ =3D "\n=3Dover 4\n"; - }; - - /^\@([fv]?table)\s+(\@[a-z]+)/ and do { - push @endwstack, $endw; - push @icstack, $ic; - $endw =3D $1; - $ic =3D $2; - $ic =3D~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/; - $ic =3D~ s/\@(?:code|kbd)/C/; - $ic =3D~ s/\@(?:dfn|var|emph|cite|i)/I/; - $ic =3D~ s/\@(?:file)/F/; - $ic =3D~ s/\@(?:asis)//; - $_ =3D "\n=3Dover 4\n"; - }; - - /^\@((?:small)?example|display)/ and do { - push @endwstack, $endw; - $endw =3D $1; - $shift =3D "\t"; - $_ =3D ""; # need a paragraph break - }; - - /^\@item\s+(.*\S)\s*$/ and $endw eq "multitable" and do { - @columns =3D (); - for $column (split (/\s*\@tab\s*/, $1)) { - # @strong{...} is used a @headitem work-alike - $column =3D~ s/^\@strong\{(.*)\}$/$1/; - push @columns, $column; - } - $_ =3D "\n=3Ditem ".join (" : ", @columns)."\n"; - }; - - /^\@(quotation)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw =3D $1; - $_ =3D "\n$2:" - }; - - /^{(.*)}$|^(.*)$/ and $#args > 0 and do { - $kind =3D $args[0]; - $arguments =3D $1 // ""; - if ($endw eq "deftypefn") { - $ret =3D $args[1]; - $fname =3D "B<$args[2]>"; - $_ =3D $ret ? "$ret " : ""; - $_ .=3D "$fname $arguments ($kind)"; - } else { - $_ =3D "B<$args[1]> ($kind)\n\n$arguments"; - } - @args =3D (); - }; - - /^\@(deftp)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw =3D $1; - $arg =3D $2; - $arg =3D~ s/{([^}]*)}/$1/g; - $arg =3D~ s/\@$//; - @args =3D split (/ /, $arg); - $_ =3D ""; - }; - - /^\@(deftypefn)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw =3D $1; - $arg =3D $2; - $arg =3D~ s/{([^}]*)}/$1/g; - $arg =3D~ s/\@$//; - @args =3D split (/ /, $arg); - $_ =3D ""; - }; - - /^\@itemx?\s*(.+)?$/ and do { - if (defined $1) { - if ($ic eq "") { - $_ =3D "\n=3Ditem $1\n"; - } else { - # Entity escapes prevent munging by the <> processing belo= w. - $_ =3D "\n=3Ditem $ic\<$1\>\n"; - } - } else { - $_ =3D "\n=3Ditem $ic\n"; - $ic =3D~ y/A-Ya-y/B-Zb-z/; - $ic =3D~ s/(\d+)/$1 + 1/eg; - } - }; - - $section .=3D $shift.$_."\n"; -} -# End of current file. -close($inf); -$inf =3D pop @instack; -} - -die "No filename or title\n" unless defined $fn && defined $tl; - -print "=3Dencoding $encoding\n\n" if defined $encoding; - -$sects{NAME} =3D "$fn \- $tl\n"; -$sects{FOOTNOTES} .=3D "=3Dback\n" if exists $sects{FOOTNOTES}; - -for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES - BUGS NOTES FOOTNOTES EXAMPLES SEEALSO AUTHOR COPYRIGHT)) { - if(exists $sects{$sect}) { - $head =3D $sect; - $head =3D~ s/SEEALSO/SEE ALSO/; - print "=3Dhead1 $head\n\n"; - print scalar unmunge ($sects{$sect}); - print "\n"; - } -} - -sub usage -{ - die "usage: $0 [-D toggle...] [infile [outfile]]\n"; -} - -sub postprocess -{ - local $_ =3D $_[0]; - - # @value{foo} is replaced by whatever 'foo' is defined as. - while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) { - if (! exists $defs{$2}) { - print STDERR "Option $2 not defined\n"; - s/\Q$1\E//; - } else { - $value =3D $defs{$2}; - s/\Q$1\E/$value/; - } - } - - # Formatting commands. - # Temporary escape for @r. - s/\@r\{([^\}]*)\}/R<$1>/g; - s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; - s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; - s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<= $1>/g; - s/\@sc\{([^\}]*)\}/\U$1/g; - s/\@file\{([^\}]*)\}/F<$1>/g; - s/\@w\{([^\}]*)\}/S<$1>/g; - s/\@t\{([^\}]*)\}/$1/g; - s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; - - # keep references of the form @ref{...}, print them bold - s/\@(?:ref)\{([^\}]*)\}/B<$1>/g; - - # Change double single quotes to double quotes. - s/''/"/g; - s/``/"/g; - - # Cross references are thrown away, as are @noindent and @refill. - # (@noindent is impossible in .pod, and @refill is unnecessary.) - # @* is also impossible in .pod; we discard it and any newline that - # follows it. Similarly, our macro @gol must be discarded. - - s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; - s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; - s/;\s+\@pxref\{(?:[^\}]*)\}//g; - s/\@noindent\s*//g; - s/\@refill//g; - s/\@gol//g; - s/\@\*\s*\n?//g; - - # Anchors are thrown away - s/\@anchor\{(?:[^\}]*)\}//g; - - # @uref can take one, two, or three arguments, with different - # semantics each time. @url and @email are just like @uref with - # one argument, for our purposes. - s/\@(?:uref|url|email)\{([^\},]*)\}/<B<$1>>/g; - s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; - s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; - - # Un-escape <> at this point. - s/<//g; - - # Now un-nest all B<>, I<>, R<>. Theoretically we could have - # indefinitely deep nesting; in practice, one level suffices. - 1 while s/([BIR])<([^<>]*)([BIR])<([^<>]*)>/$1<$2>$3<$4>$1 with bare ...; eliminate empty markup, B<>; - # shift white space at the ends of [BI]<...> expressions outside - # the expression. - s/R<([^<>]*)>/$1/g; - s/[BI]<>//g; - s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g; - s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g; - - # Extract footnotes. This has to be done after all other - # processing because otherwise the regexp will choke on formatting - # inside @footnote. - while (/\@footnote/g) { - s/\@footnote\{([^\}]+)\}/[$fnno]/; - add_footnote($1, $fnno); - $fnno++; - } - - return $_; -} - -sub unmunge -{ - # Replace escaped symbols with their equivalents. - local $_ =3D $_[0]; - - s/</E/g; - s/>/E/g; - s/{/\{/g; - s/}/\}/g; - s/&at;/\@/g; - s/&/&/g; - return $_; -} - -sub add_footnote -{ - unless (exists $sects{FOOTNOTES}) { - $sects{FOOTNOTES} =3D "\n=3Dover 4\n\n"; - } - - $sects{FOOTNOTES} .=3D "=3Ditem $fnno.\n\n"; $fnno++; - $sects{FOOTNOTES} .=3D $_[0]; - $sects{FOOTNOTES} .=3D "\n\n"; -} - -# stolen from Symbol.pm -{ - my $genseq =3D 0; - sub gensym - { - my $name =3D "GEN" . $genseq++; - my $ref =3D \*{$name}; - delete $::{$name}; - return $ref; - } -} --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089345; cv=none; d=zohomail.com; s=zohoarc; b=QpzR0UIUVZvsKO0KRW9AqRPnODy2OpfVZyGVwI0Br0hlAjj4EfbahznxRShxMfMmZys8lLzGRdqFQmhf3Na7SbyF9cYrkSMZf/DLI2+1nIcH4t3iRv40iw2I9jw8llfC/gl9/pgC9tIlKf1FpMVXlZ95xtYthiK5sdH94z/MAzE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089345; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=gvLkpu8rW3JTmQqRZmEUsHrF4uVAVJ/B/J8K9PNu4Yo=; b=MoOpY5QT4EwmIlJZlp+9kDrLpNHpmj53zQxnsIoy/JZBi1egWoicsUrbIW5nU92WEsudcF/l81zzaIuXwSRVciE9jZejfhlvpbKcaZse3CUTI+plqsLc8VKfxyuND/3vBQ02R8rGwUR+gVmGb/rPskKWwZ484YvsPdJWxO3pF1o= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089345421105.81872591099318; Mon, 10 Aug 2020 12:55:45 -0700 (PDT) Received: from localhost ([::1]:56856 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DtX-0002t4-5v for importer@patchew.org; Mon, 10 Aug 2020 15:55:43 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51286) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dov-00014N-3N for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:57 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:32803) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dot-0004xo-8m for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:56 -0400 Received: by mail-wr1-x444.google.com with SMTP id p20so9317706wrf.0 for ; Mon, 10 Aug 2020 12:50:54 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=gvLkpu8rW3JTmQqRZmEUsHrF4uVAVJ/B/J8K9PNu4Yo=; b=EvYj0WuQVSdDqdNVEJYS0z2xnxcGJH/pb1Y/SQpRjoeToQZCIR5XXJg2vUb0NF+AAz tVoGy6XtUc3Wh5/FN8VG643CarFvBy1HozVR7uORvc5ucIoKlmk1f3fbp6LDI6nLhOHn aTo9nK/GvgMcGxwG3Htx5pSM+knTOdakKO2JF5Krm/J6jpZKHrIC/kIOoQnu5O1/X5C9 V/PSwMyEwMmayJVVBkYHEebG4jNKLcN9/iMpLIOmPytSxTQqtTJHzt9PftGhXX33FJBZ 6E8LAIDtl0vK2KaYEpalo7TvleT8GtWHY5gG5m3UGLJ1Q6gLNGihZk9vC3QRyWJhCgnV ZAIA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=gvLkpu8rW3JTmQqRZmEUsHrF4uVAVJ/B/J8K9PNu4Yo=; b=AKBDcNfNcGC/jMaIKMrbEx/xMKV6VUjrw+XoYGJ2iOiIzKyyw06+RErbbG5E+BzYKx hi6EKs/T9Dz/isCiV2OKcjlb+UOvcd/475fiYWzlRAuBmzdL9bRt14qsikYltc/NPHRw ngfHwwpMmirIWnR9+T8kmLHUXTO6P7c8euL6KISfBwBJyHA5g70DPL2iBRsMivIhTsFi EYOUJFNhoKlupexlsRBcv0OGWPDCqNAA7lW4QrnD6zKuHLvHEAcFF3v9nbQlM7DYgNYz 34n5mrY2Lt/NMSmg8l3ypYlaigJaHVtJIcRzGNy99RxFFiAIWDv4R5AbNn9aUN/nwjN9 6Tww== X-Gm-Message-State: AOAM531eHm82NrU4vrHc+00ea+DBqFox+Svf+qndcjS9Sv8pN/XA8Pif SxmF+2sk8a6La9Wj7d86f/hXi/qJjFtNdQ== X-Google-Smtp-Source: ABdhPJyZ2/eECkxs7L25sLHdkqePdo7ZNQshU9FfExJwLZ9IwB46Civ0T5HYc/YZ8CmEZbPHTVoatA== X-Received: by 2002:adf:f207:: with SMTP id p7mr28159033wro.292.1597089053348; Mon, 10 Aug 2020 12:50:53 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 18/20] Remove Texinfo related files from .gitignore and git.orderfile Date: Mon, 10 Aug 2020 20:50:17 +0100 Message-Id: <20200810195019.25427-19-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::444; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x444.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" We don't use Texinfo any more; we can remove the references to the .texi source files and the generated output files from our .gitignore and git.orderfile. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- .gitignore | 15 --------------- scripts/git.orderfile | 1 - 2 files changed, 16 deletions(-) diff --git a/.gitignore b/.gitignore index 2992d15931a..6a3e335f6a7 100644 --- a/.gitignore +++ b/.gitignore @@ -45,20 +45,15 @@ /qapi/qapi-visit-*.[ch] !/qapi/qapi-visit-core.c **/qapi/qapi-visit.[ch] -**/qapi/qapi-doc.texi /qemu-edid /qemu-img /qemu-nbd /qemu-options.def -/qemu-options.texi -/qemu-img-cmds.texi /qemu-img-cmds.h /qemu-io /qemu-ga /qemu-bridge-helper /qemu-keymap -/qemu-monitor.texi -/qemu-monitor-info.texi /qemu-storage-daemon /qemu-version.h /qemu-version.h.tmp @@ -83,7 +78,6 @@ *.ky *.log *.pdf -*.pod *.cps *.fns *.kys @@ -126,15 +120,6 @@ /pc-bios/s390-ccw/s390-ccw.elf /pc-bios/s390-ccw/s390-ccw.img /docs/built -/docs/interop/qemu-ga-qapi.texi -/docs/interop/qemu-ga-ref.html -/docs/interop/qemu-ga-ref.info* -/docs/interop/qemu-ga-ref.txt -/docs/interop/qemu-qmp-qapi.texi -/docs/interop/qemu-qmp-ref.html -/docs/interop/qemu-qmp-ref.info* -/docs/interop/qemu-qmp-ref.txt -/docs/version.texi /contrib/vhost-user-gpu/50-qemu-gpu.json *.tps .stgit-* diff --git a/scripts/git.orderfile b/scripts/git.orderfile index 73fd818d7f3..de276d6c8de 100644 --- a/scripts/git.orderfile +++ b/scripts/git.orderfile @@ -12,7 +12,6 @@ # Documentation docs/* *.rst -*.texi =20 # build system configure --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089513; cv=none; d=zohomail.com; s=zohoarc; b=QdjuNymXceEFvjdFXNeBqCmaS+nVesLdj+LPPr18TQDEW+fCspMW/vGPy0t4ovvrNWbS2diCsQAltR74oqYgLSPXe7lBOgx9rJSZYxkUujRREYUDcvBw1DYE2ZWEaWK1/kN7YaGoFddAGDGPHtcVBfTei69F6vw9oHlb4zb/NYQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089513; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=OiS7jf9/E4jzfaL7m5CjkFMwe4+1gVTXRlsOG3FVJ2Q=; b=KCDS9ATnpVORcdzOgVzGC3tJl+yLCMnLDUyAJSQx93fakM3g6U/4IclvFGLVzuQDum/qChYBq+m39qC1c/owfd9NLIZ6BVWtSC3GWJJnbW4vVwA/d5ISjPzCp//pDo+uwy2bADOo3Ay511OGNPuyVZbtppps3WXlQEHXprsrN4s= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089513804876.7533924622237; Mon, 10 Aug 2020 12:58:33 -0700 (PDT) Received: from localhost ([::1]:42530 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DwG-0008VK-Lv for importer@patchew.org; Mon, 10 Aug 2020 15:58:32 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51300) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Dow-00018Y-RR for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:58 -0400 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:45366) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dov-0004yC-5D for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:58 -0400 Received: by mail-wr1-x442.google.com with SMTP id z18so9298060wrm.12 for ; Mon, 10 Aug 2020 12:50:56 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=OiS7jf9/E4jzfaL7m5CjkFMwe4+1gVTXRlsOG3FVJ2Q=; b=uUuPW5X9VJgTOhuyrS43fEgnW75PjzRUK/wBPtydElNt6/uNIMQ27wy6gHL/OqVHch PnAZtGJuJX/GcPF9lhiANfuV9FE2LhOWtbM7AxG2waCLQrV3PhGAefDnOjGvk0ENBsi6 qA1dGxcaO6H6H09ht22hOxSFOKup5Rbb1YYkZGNUK+7V5LZ1hjzvPcvf56/BPYYjpWRD 5N7YFh4Hklor3SY0I/E1Bv5o3SQoGylFtorienkn+rFdEGhQT3200ooNdeteQvRMKJYJ crUI8zvmwLpt2li8dVMSKZOY1IHTT2EhAnT9xT0hrLIwcocHXICIlMzlR0vE84kg5MzZ ztpg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=OiS7jf9/E4jzfaL7m5CjkFMwe4+1gVTXRlsOG3FVJ2Q=; b=SjKtp4tvy4lWJHWoktNQs3gpIdYAKWPSBiIxpVvG/M+vNkujz3SFrIrorQQMI2h1+m GHAt1/s0C1Nufqb5NjVGedeEVou3wT4UtBWz9a+ud4sPkenDelxt8FCKVOVMyNK5fz8Y t6U8UBsKvWGqx/9YUB9plpGlVr66fJWvjFCEGFJxDaqbZldIit2u9MI1i/xHdNEF6cIw CdLIED1yXB/R4p+8ZgQNBXlW4QYQsfRBV0zbEmd7FSCfpAlWitOVIRmeEZ2rMjIHcaXc UesrleyEAf8FnM/Oq0xnza6cr41kNxrVCh8R8YTUMbtJaPqADV0Vg2WQ3iDKgcE2XYTd NrRA== X-Gm-Message-State: AOAM5311Z4h1bfXbdz1j71Ea75rYGqjMCsZi+ZBG3BbsVmzsLzjhlUqg SesiZzsL5zWH6sQUH/XibrBThSsH5hmuUg== X-Google-Smtp-Source: ABdhPJxaiMlRkFmKhkDYwhrHDVAHRbKGlSWILzzOi1ulMIlNk7odXKK5djKsCmib5LOpVURdG02cpQ== X-Received: by 2002:a5d:544f:: with SMTP id w15mr2897757wrv.208.1597089055109; Mon, 10 Aug 2020 12:50:55 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 19/20] configure: Drop texinfo requirement Date: Mon, 10 Aug 2020 20:50:18 +0100 Message-Id: <20200810195019.25427-20-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::442; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x442.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" We don't need the texinfo and pod2man programs to build our documentation any more, so remove them from configure's tests. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- configure | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/configure b/configure index 2acc4d1465f..ae66ceeeaae 100755 --- a/configure +++ b/configure @@ -5105,14 +5105,14 @@ if test "$docs" !=3D "no" ; then else sphinx_ok=3Dno fi - if has makeinfo && has pod2man && test "$sphinx_ok" =3D "yes"; then + if test "$sphinx_ok" =3D "yes"; then docs=3Dyes else if test "$docs" =3D "yes" ; then if has $sphinx_build && test "$sphinx_ok" !=3D "yes"; then echo "Warning: $sphinx_build exists but it is either too old or us= es too old a Python version" >&2 fi - feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a= Python 3 version of python-sphinx" + feature_not_found "docs" "Install a Python 3 version of python-sphin= x" fi docs=3Dno fi @@ -6593,13 +6593,6 @@ if test "$solaris" =3D "no" && test "$tsan" =3D "no"= ; then fi fi =20 -# test if pod2man has --utf8 option -if pod2man --help | grep -q utf8; then - POD2MAN=3D"pod2man --utf8" -else - POD2MAN=3D"pod2man" -fi - # Use ASLR, no-SEH and DEP if available if test "$mingw32" =3D "yes" ; then for flag in --dynamicbase --no-seh --nxcompat; do @@ -8008,7 +8001,6 @@ echo "LDFLAGS_SHARED=3D$LDFLAGS_SHARED" >> $config_ho= st_mak echo "LIBS_QGA+=3D$libs_qga" >> $config_host_mak echo "TASN1_LIBS=3D$tasn1_libs" >> $config_host_mak echo "TASN1_CFLAGS=3D$tasn1_cflags" >> $config_host_mak -echo "POD2MAN=3D$POD2MAN" >> $config_host_mak if test "$gcov" =3D "yes" ; then echo "CONFIG_GCOV=3Dy" >> $config_host_mak echo "GCOV=3D$gcov_tool" >> $config_host_mak --=20 2.20.1 From nobody Fri May 17 17:50:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089591; cv=none; d=zohomail.com; s=zohoarc; b=eKk4DHOJwR8WGfZPxbgjCm9xRsxDa7tJ9M2P3VLTbQYBbVo8ZSWGGZeF4f97XUuJvG+27LS4i4/LUA2iuv5c1xAQDlbHTzGJ1+dP03h4YNKn8AVxURNG9PEcXhUeFvvHlQ6taJ6KCdnkAPsruHZlPa/8VJK01C+675Vj82ayejc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089591; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=LSVn2WKQmCMQEFWwav2YKrRxyoiYWkDAUAzH6RvFEtY=; b=gmhcV7Vnia71WLWZelZLG3RXEfajYxGo3bODusxrMaKBzilnLsIRZ3hubO6auV8OMtxfOd9n133SwO1AHwGJKsTjvZzCdKA2s/Iptp+cciCsooxqJ68RySSRZ+boPwlUoTuaJlatm4oSO6IBBWXWzmWp9bnRqMGy/tfCnpYJyYc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089591733733.2084892064679; Mon, 10 Aug 2020 12:59:51 -0700 (PDT) Received: from localhost ([::1]:46824 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DxW-0001pS-Gs for importer@patchew.org; Mon, 10 Aug 2020 15:59:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51316) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doy-0001Cs-KI for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:51:00 -0400 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:40168) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Dow-0004yN-R6 for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:51:00 -0400 Received: by mail-wr1-x442.google.com with SMTP id l2so9309034wrc.7 for ; Mon, 10 Aug 2020 12:50:58 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=LSVn2WKQmCMQEFWwav2YKrRxyoiYWkDAUAzH6RvFEtY=; b=DoiMkcr4OfPIGRdqayTkzUkRgiX0WKQq46v5fIjtCejtCoZs+uEYAUSKT0pJbXgTs3 LQ5Jdz5EV+s6aRYaP5LFmWgH1+qVKrQEk10jl+jzaM+lKYP4yYOyI7DReFQrq8fOi2vb QTkdZSL1OytZM3KA8oPsMaBFpV3M4dkmbgyEOK4QOMIZ4YWenaw6Z9rdZgm741ze988d htiQ+iLcKtzkzaPtCQeTAK50xt9lrGlL3LJIbi3AUh9cC/+YuTaoazlKJlDffl8gab3r kcv1e2zr5H6dizZewRsmxCVl623f6Z3chTDGwurPdMfR8KUAiH73vvsrp6unM0+VJvEI USHA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=LSVn2WKQmCMQEFWwav2YKrRxyoiYWkDAUAzH6RvFEtY=; b=c7ANHg2w9ZjwgstNzbf6QE41xbiUz+DzZ6EMlz63DSeAxlaj9UJ1H3rgCX4JKIfVCB +myJzdIGEgHU7DE5ZekZhlyqD7AWHIyjA31p6YrlAhKeCbmVdJ5XWaGBD5to8KI4MgiS AdtRPhwxnZOgbdo/ylMV2LAZY25mNMxMRutMKgVlKVl0crypo0NCA3ImqZXJ98tZZyVk SvfmdNDyx2E1IxwoGi5ELHs2sRJRWZiKf6ohUhFOCwpp+eKkKCkvVGMwNN1pXqjYJgav CJwBDqozCBPowopx1cKPj6LQkp3m4Q4EGBtBBHUWJFfOwwy3MGPXQFHFFXRpDGM/RLlY 4gWw== X-Gm-Message-State: AOAM533WbMTQYaqZdu32lPsOi+iXkNLphsW82EMpgJv1AFkIQJ324Bn1 vZEOJkAVPU4rmjokGbUl7ll7uk00r7oKdw== X-Google-Smtp-Source: ABdhPJzfTgnWP9rLvsLny7LOwWyRFDNYDgtLJluK4P/OOJ2g/ovqWOIA0xKvFjYNb90xPrAXQB5ndQ== X-Received: by 2002:adf:e7c9:: with SMTP id e9mr26767912wrn.10.1597089056932; Mon, 10 Aug 2020 12:50:56 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 20/20] Remove texinfo dependency from docker and CI configs Date: Mon, 10 Aug 2020 20:50:19 +0100 Message-Id: <20200810195019.25427-21-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::442; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x442.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" We don't need texinfo to build the docs any more, so we can drop that dependency from our docker and other CI configs. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- Changes v4->v5: remove texinfo from ubuntu2004.docker too --- .travis.yml | 1 - tests/docker/dockerfiles/debian10.docker | 1 - tests/docker/dockerfiles/debian9.docker | 1 + tests/docker/dockerfiles/fedora.docker | 1 - tests/docker/dockerfiles/ubuntu.docker | 1 - tests/docker/dockerfiles/ubuntu1804.docker | 1 - tests/docker/dockerfiles/ubuntu2004.docker | 1 - 7 files changed, 1 insertion(+), 6 deletions(-) diff --git a/.travis.yml b/.travis.yml index 6695c0620fc..ff4361079f3 100644 --- a/.travis.yml +++ b/.travis.yml @@ -198,7 +198,6 @@ jobs: apt: packages: - python3-sphinx - - texinfo - perl =20 =20 diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/docker= files/debian10.docker index bcdff04ddfe..e5dbfa8fe95 100644 --- a/tests/docker/dockerfiles/debian10.docker +++ b/tests/docker/dockerfiles/debian10.docker @@ -30,7 +30,6 @@ RUN apt update && \ psmisc \ python3 \ python3-sphinx \ - texinfo \ $(apt-get -s build-dep qemu | egrep ^Inst | fgrep '[all]' | cut -d= \ -f2) =20 ENV FEATURES docs diff --git a/tests/docker/dockerfiles/debian9.docker b/tests/docker/dockerf= iles/debian9.docker index 0f0ebe530af..7e4b8a672fc 100644 --- a/tests/docker/dockerfiles/debian9.docker +++ b/tests/docker/dockerfiles/debian9.docker @@ -28,4 +28,5 @@ RUN apt update && \ pkg-config \ psmisc \ python3 \ + python3-sphinx \ $(apt-get -s build-dep qemu | egrep ^Inst | fgrep '[all]' | cut -d= \ -f2) diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfi= les/fedora.docker index 70b6186bd3e..71e4b569770 100644 --- a/tests/docker/dockerfiles/fedora.docker +++ b/tests/docker/dockerfiles/fedora.docker @@ -96,7 +96,6 @@ ENV PACKAGES \ tar \ tesseract \ tesseract-langpack-eng \ - texinfo \ usbredir-devel \ virglrenderer-devel \ vte291-devel \ diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfi= les/ubuntu.docker index 161806e6b8c..b556ed17d29 100644 --- a/tests/docker/dockerfiles/ubuntu.docker +++ b/tests/docker/dockerfiles/ubuntu.docker @@ -63,7 +63,6 @@ ENV PACKAGES \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=3Dnoninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dock= erfiles/ubuntu1804.docker index a10ea2850b6..a6a7617da67 100644 --- a/tests/docker/dockerfiles/ubuntu1804.docker +++ b/tests/docker/dockerfiles/ubuntu1804.docker @@ -49,7 +49,6 @@ ENV PACKAGES \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=3Dnoninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu2004.docker b/tests/docker/dock= erfiles/ubuntu2004.docker index 8d10934a2a7..cafe8443fbf 100644 --- a/tests/docker/dockerfiles/ubuntu2004.docker +++ b/tests/docker/dockerfiles/ubuntu2004.docker @@ -57,7 +57,6 @@ ENV PACKAGES flex bison \ sparse \ tesseract-ocr \ tesseract-ocr-eng \ - texinfo \ xfslibs-dev\ vim RUN apt-get update && \ --=20 2.20.1