From: John Snow <jsnow@redhat.com>
To: Eduardo Habkost <ehabkost@redhat.com>
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Daniel P. Berrangé" <berrange@redhat.com>,
"QEMU Developers" <qemu-devel@nongnu.org>,
"Paolo Bonzini" <pbonzini@redhat.com>
Subject: Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
Date: Wed, 4 Aug 2021 20:26:10 -0400 [thread overview]
Message-ID: <CAFn=p-bBK=LRG0u8dr_AqgMAzH3+KotRkRUZOLZP_cXFYkAa1g@mail.gmail.com> (raw)
In-Reply-To: <20210804210034.2dp6b2uqlfxkhjjo@habkost.net>
[-- Attachment #1: Type: text/plain, Size: 3024 bytes --]
On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost <ehabkost@redhat.com> wrote:
> On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote:
> > On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost <ehabkost@redhat.com>
> wrote:
> > >
> > > On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote:
> > > > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost <ehabkost@redhat.com>
> wrote:
> > > > > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > > > > index e5fe3597cd8..9c1be5d7fc2 100644
> > > > > --- a/docs/devel/qom.rst
> > > > > +++ b/docs/devel/qom.rst
> > > > > @@ -3,6 +3,7 @@ The QEMU Object Model (QOM)
> > > > > ===========================
> > > > >
> > > > > .. highlight:: c
> > > > > +.. default-role:: any
> > > > >
> > > > > The QEMU Object Model provides a framework for registering user
> creatable
> > > > > types and instantiating objects from those types. QOM provides
> the following
> > > > > @@ -42,8 +43,8 @@ features:
> > > > >
> > > > > type_init(my_device_register_types)
> > > > >
> > > > > -In the above example, we create a simple type that is described
> by #TypeInfo.
> > > > > -#TypeInfo describes information about the type including what it
> inherits
> > > > > +In the above example, we create a simple type that is described
> by `TypeInfo`.
> > > > > +`TypeInfo` describes information about the type including what it
> inherits
> > > >
> > > > I've just gone through all of docs/ finding the places where we had
> `foo` and
> > > > probably meant ``foo``, so please don't add any new ones. I would
> suggest
> > > > that you either use the ``double-backtick`` syntax to render as
> fixed-width
> > > > font, or use an explicit role tag so readers of the rST source can
> tell that
> > > > that's what you meant to use, ie avoid "default-role".
> > >
> > > I don't understand why that would be a reason to not use
> > > default-role. With default-role, we get an error when misusing
> > > `foo`. Without default-role, misuse won't be detected at all
> > > (except by manual inspection).
> >
> > Ah, I didn't realize that we got an error if we set the default-role
> > to 'any'. That certainly makes it nicer than the default default
> > of 'cite'.
> >
> > Is there a sensible default-role we can use as the default for the whole
> manual,
> > rather than only declaring it in individual .rst files ? One of the
> > things I don't
> > like about the change here is that it means that `thing` in this
> individual .rst
> > file is different from `thing` in every other .rst file in our docs.
>
> I believe "any" would be a very sensible default role for all
> documents, but I don't know how to set default-role globally.
> I'll try to find out.
>
> --
> Eduardo
>
Oh, I actually fixed that issue I referenced there back in May -- I keep a
patchset up to date whenever I work on modernizing the QAPI python code
that actually DOES switch our default role to "any" ... I updated it just
today, in fact. I will send it to the list if there's an appetite for it
now.
--js
[-- Attachment #2: Type: text/html, Size: 4119 bytes --]
next prev parent reply other threads:[~2021-08-05 0:27 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-29 17:55 [PATCH for-6.2 00/10] QOM documentation updates Eduardo Habkost
2021-07-29 17:55 ` [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol` Eduardo Habkost
2021-08-02 12:14 ` Peter Maydell
2021-08-04 20:31 ` Eduardo Habkost
2021-08-04 20:42 ` Peter Maydell
2021-08-04 21:00 ` Eduardo Habkost
2021-08-05 0:26 ` John Snow [this message]
2021-08-05 16:36 ` Eduardo Habkost
2021-08-05 19:07 ` Eduardo Habkost
2021-07-29 17:55 ` [PATCH for-6.2 02/10] docs: qom: Use Sphinx cross references more often Eduardo Habkost
2021-07-29 17:55 ` [PATCH for-6.2 03/10] docs: qom: Fix autoptr expansion example Eduardo Habkost
2021-08-02 12:16 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level Eduardo Habkost
2021-08-02 12:16 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section Eduardo Habkost
2021-07-30 13:15 ` Philippe Mathieu-Daudé
2021-08-02 12:17 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example Eduardo Habkost
2021-07-30 8:16 ` Markus Armbruster
2021-07-30 8:43 ` Peter Maydell
2021-07-30 9:19 ` Daniel P. Berrangé
2021-08-02 12:19 ` Peter Maydell
2021-08-04 20:40 ` Eduardo Habkost
2021-08-04 20:45 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 07/10] docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation Eduardo Habkost
2021-08-02 12:24 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 08/10] docs: qom: Show actual typecast functions in examples Eduardo Habkost
2021-08-02 12:25 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples Eduardo Habkost
2021-08-02 12:27 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 10/10] MAINTAINERS: Add qom.rst to QOM section Eduardo Habkost
2021-08-02 12:28 ` Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAFn=p-bBK=LRG0u8dr_AqgMAzH3+KotRkRUZOLZP_cXFYkAa1g@mail.gmail.com' \
--to=jsnow@redhat.com \
--cc=berrange@redhat.com \
--cc=ehabkost@redhat.com \
--cc=pbonzini@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).