From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 29D2AC021B3 for ; Fri, 21 Feb 2025 18:09:30 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tlXRx-0006RK-LL; Fri, 21 Feb 2025 13:08:33 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tlXRv-0006Qx-DU for qemu-devel@nongnu.org; Fri, 21 Feb 2025 13:08:31 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tlXRs-0004UO-Ie for qemu-devel@nongnu.org; Fri, 21 Feb 2025 13:08:31 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740161306; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=/ADBYFikQt863PC4d6YHBTn0dvcMx7pnQUrFKjyIZlI=; b=IbVz5i5ZKtU4oYW/qmx2f4KAKKGJfuKdSu/NwjvWGBreVWgTolSS4uNfrbmSti4diBT4jn GGz+PFUNBoyTAX9yodV2kpEFk4sDZpJmBvg/QVhjLcqUQwellVYz/qPi0Mw+J++ij7X2ut PVito76uAfAU68IJoE5TwP5fK76GIiU= Received: from mail-pj1-f71.google.com (mail-pj1-f71.google.com [209.85.216.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-456-bN-hJeYdNJ-cbFdPYu5oXA-1; Fri, 21 Feb 2025 13:08:24 -0500 X-MC-Unique: bN-hJeYdNJ-cbFdPYu5oXA-1 X-Mimecast-MFC-AGG-ID: bN-hJeYdNJ-cbFdPYu5oXA_1740161304 Received: by mail-pj1-f71.google.com with SMTP id 98e67ed59e1d1-2fc1a70935fso5390516a91.1 for ; Fri, 21 Feb 2025 10:08:24 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1740161303; x=1740766103; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=/ADBYFikQt863PC4d6YHBTn0dvcMx7pnQUrFKjyIZlI=; b=OOz+lifA04WYX+p9aZighAm8gK0JjOfasEMn3pJu+1/y7XfaCE9NpFHR9dLlfHPPIT Zsq5SC4okThr4k9+xPNPvewHNwVLqRkgYqMIFFWBEJ1yVMAUAMpvVICrj9xpBSBzxWNe H+irKbkIchjPP4N7u7BFwvGql04eR6TOnFfw3z070hABJywT6UMg6GxPXW87kLLdNh0q TScGgQ0OE63i6f38Nz6p1zXGqMvjbq2esadsGazlc61MGjexEM8Ubi2PsDuzhz0C/lQN fsHIc6u2o7N3qBUS1oJBfJ/FeXo2NFLG+QlGMaPUFslApVa3357fg3LcEMacDgvaKO0C VkZg== X-Gm-Message-State: AOJu0YzNb7Lw9zInbCxcyk7klQlz8keFCFGnreqpkXul3mJgZVXL+ATc ZvoKsZdcbkvYVrILh/MpVtXH1uzQ011f+31/qg3qOStpo5a67a9Apx5O/0IS3MNUaWrH0SiPKr9 odzLgDYT9xNK6GaHG547gvJweQzSzy+I1/U1bloJM6kiweIdrgBwyp3Y7qg6Ls3UPOHV41FswZ8 48YB1Y1GH/MtGgz+UBuiiNgP5gd60= X-Gm-Gg: ASbGncthToXhWUVDnB35LOQshCLFKgw8D5T53FhFLYZgcq+Qs3ePCZJCOgBUskKxSwQ pSBQYjHuG4Mn+lBAyvVBB/cmJKawDMT9+aFTwI8KYczqCma4aRpY4g/t9xy/KeOLwyo35ey1KYL P26DiDFo3WDGYsuItiYFEnq3fYUwF3 X-Received: by 2002:a17:90b:4c8e:b0:2ee:e113:815d with SMTP id 98e67ed59e1d1-2fce78aeaeamr6579951a91.8.1740161303518; Fri, 21 Feb 2025 10:08:23 -0800 (PST) X-Google-Smtp-Source: AGHT+IGX5l1XO/W7tNFhvSXjyrOsrogTYm9yj6XQsOpF8u9HljIY1GJ+4s9mIkXvJMe/XsFcDBmFGXbIiRYTTI1DsNo= X-Received: by 2002:a17:90b:4c8e:b0:2ee:e113:815d with SMTP id 98e67ed59e1d1-2fce78aeaeamr6579827a91.8.1740161302173; Fri, 21 Feb 2025 10:08:22 -0800 (PST) MIME-Version: 1.0 References: <20250205231208.1480762-1-jsnow@redhat.com> <87wmds4tpk.fsf@pond.sub.org> <874j0q2hof.fsf@pond.sub.org> <87o6yvn6iy.fsf@pond.sub.org> In-Reply-To: <87o6yvn6iy.fsf@pond.sub.org> From: John Snow Date: Fri, 21 Feb 2025 13:08:10 -0500 X-Gm-Features: AWEUYZnD3VeZQjdcqF25NsMpOVJU5ih0qZEBwHwgIUyZjRQng-tsYkmN3n93jvw Message-ID: Subject: Re: [PATCH 00/42] docs: add sphinx-domain rST generator to qapidoc To: Markus Armbruster Cc: qemu-devel@nongnu.org, Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?Q?Daniel_P=2E_Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , =?UTF-8?B?QWxleCBCZW5uw6ll?= , Jason Wang , Paolo Bonzini , =?UTF-8?Q?Philippe_Mathieu=2DDaud=C3=A9?= Content-Type: multipart/alternative; boundary="00000000000044b778062eaae07a" Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.424, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, 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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org --00000000000044b778062eaae07a Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Fri, Feb 21, 2025 at 1:42=E2=80=AFAM Markus Armbruster wrote: > John Snow writes: > > > On Wed, Feb 19, 2025 at 8:22=E2=80=AFAM Markus Armbruster > wrote: > > > >> John Snow writes: > >> > >> > "The text handler you add looks just like the existing latex handler= . > Does > >> > LaTeX output lack "little headings", too?" > >> > > >> > Yes, almost certainly. Can you let me know which output formats we > actually > >> > "care about"? I'll have to test them all. > >> > >> As far as I can tell, our build system runs sphinx-build -b html and -= b > >> man. > >> > >> I run it with -b text manually all the time to hunt for and review > >> changes in output. I'd prefer to keep it working if practical. > >> > >> For what it's worth, there is a bit of LaTeX configuration in > >> docs/conf.py. > >> > >> > In the meantime, I upgrade= d > my > >> > patch so that the text translator properly handles branches with > headings > >> > that delineate the different branches so that the text output is ful= ly > >> > reasonable. I will need to do the same for any format we care about. > >> > > >> > I've re-pushed as of "about 30 minutes before I wrote this email" -- > >> > https://gitlab.com/jsnow/qemu/-/commits/sphinx-domain-blergh2 > >> > > >> > This branch includes the text generator fixes (which technically > belong > >> > with the predecessor series we skipped, but I'll refactor that later= .) > >> > it also includes fixes to the branch inliner, generated return > statements, > >> > and generated out-of-band feature sections. > >> > >> I'll fetch it, thanks! > >> > >> > (Long story short: inserting new sections in certain spots was broke= n > >> > because of cache. Oops. We can discuss more why I wrote that part of > the > >> > code like I did in review for the patch that introduced that problem= . > It's > >> > the "basic inliner" patch.) > >> > > >> > Below, I'm going to try a new communication approach where I > explicitly say > >> > if I have added something to my tasklist or not so that it's clear t= o > you > >> > what I believe is actionable (and what I am agreeing to change) and > what I > >> > believe needs stronger input from you before I do anything. Apologie= s > if it > >> > seems a little robotic, just trying new things O:-) > >> > > >> > On that note: not added to tasklist: do we need the LaTeX handler? D= o > we > >> > need any others? Please confirm O:-) > >> > >> See above. > >> > > > > I've got html and text working, text wasn't hard. I will give it a good > > college try on the LaTeX and man formats. Might be easy. The issue here > is > > the custom node I introduced for the collapsible details sections which > has > > no default handler in the generators. I'll have to learn more about tha= t > > part of the API, I haven't interfaced with it much yet. > > Understand. > > Have you considered cutting the series in half before the inliner? > First part emits "The members of ..." like the old doc generator. > Second part replaces that with inlined material. > > We could totally release with just the first half! Inlining is great, > but even without it, your work looks so much better and is so much more > usable. > I may indeed just do that... though we still need to solve "where to put the ifcond data?" question. The documentation culling also must be held back in this case too, which I am fine with. Let me fork my work (again) and see how complicated an inlinerless version would be... maybe that's a great way to flush the queue. maybe. > > >> > On Fri, Feb 14, 2025 at 7:05=E2=80=AFAM Markus Armbruster > wrote: > >> > > >> >> I started to eyeball old and new generated output side by side. > >> >> > >> >> New table of contents shows one level, old two. No objection; the > >> >> navigation thingie on the left is more useful anyway. > >> >> > >> > > >> > Unintentional, but if you like it, it's fine by me. Nothing added to > my > >> > tasklist. > >> > >> Mention in a commit message. > >> > > > > Sure. I... just need to figure out which commit to mention it in. Added > to > > my list, anyway. > It turns out this happens in the "example" doc patch, it's just a setting in index.rst. I didn't even intend to commit that patch anyway. So this is a nothing-burger. > > > > > >> > >> >> The new generator elides unreferenced types. Generally good, but t= wo > >> >> observations: > >> >> > >> >> * QapiErrorClass is unreferenced, but its members are mentioned in > >> >> Errors sections. QapiErrorClass serves as better than nothing > error > >> >> code documentation, but it's gone in the new doc. So this is a > minor > >> >> regression. We can figure out what to do about it later. > >> >> > >> > > >> > Right. I debated making the members references to that class, but > recalled > >> > that you disliked this class and figured you'd not like such a > change, so I > >> > just left it alone. I do not have cross-references for individual > members > >> > of objects at all yet anyway, so this is definitely more work > regardless. > >> > > >> > We could always create a pragma of some sort (or just hardcode a > list) of > >> > items that must be documented regardless of if they're referenced or > not. > >> > Please let me know your preference and I will add a "ticket" on my > personal > >> > tasklist for this project to handle that at /some point/. Nothing > added to > >> > my tasklist just yet. > >> > >> Suggest to add something like "compensate for the loss of QapiErrorCla= ss > >> documentation in the QEMU QMP Reference Manual". > >> > > > > Got it. Possibly a "for later" task but not much later. It can always > come > > after this first series, but before we "turn on" the new generator, if > that > > makes sense. Just so we reach a quiescent point and flush the > staggeringly > > large queue. > > I think we could even do it after "turn on". Yes, it's a small > regression, but I believe the improvements are big enough to outweigh > small regressions like this one. > OK. > > > I guess what I mean is: "Let's make sure what I've got here so far is > good > > first, and then I'll start adding stuff." > > [...] > > >> >> The new doc's headings use "Struct" or "Union" where the old one us= es > >> >> just "Object". Let's keep "Object", please. > >> >> > >> > > >> > I was afraid you'd ask for this. OK, I think it's an easy change. Ca= n > I > >> > keep the index page segmented by object type still, though? > >> > > >> > I do find knowing the *type* of object to be helpful as a developer, > >> > >> Can you explain why and how struct vs. union matters to you as a > >> developer? > >> > > > > I suppose it's just internal details that I like to know, but tend to > find > > the HTML reference easier to work with than grepping through the qapi > > files. I'm gonna change it for you anyway because I agree it's not > > consistent with the philosophy of "end user QMP reference". Just feels > like > > a tiny shame somehow. > > > > > >> > >> > though > >> > I understand that from the point of view of a QMP user, they're all > just > >> > objects, so your request makes sense. > >> > >> I'd prefer a single index. > >> > > > > So ... structs, unions, alternates all condensed down to "Object", is > that > > right? We get to keep command/enum/event separate, I assume. > > No, only structs and unions are "Object", alternates are "Alternate". > > For me, the separation between struct and union is an unfortunate > remnant of somewhat winding development history. > > A union is has common members, one of them is the tag, and for each tag > value, it may have variant members. > > A struct is a degenerate union: no variants. > > This is as old as the hills: Pascal records are just like this. > > QMP introspection doesn't show structs and unions, just objects, which > may or may not have variants. > > The schema language syntax, however, is still rooted (stuck?) in a past > when unions could not have common members other than the tag. > OK, I can combine these two easily then. I see why you feel it isn't worth knowing the difference for developers either under this view. > > [...] > > >> >> The new doc doesn't show non-definition conditionals, as mentioned = in > >> >> the cover letter. It shows definition conditionals twice. Once > should > >> >> suffice. > >> >> > >> > > >> > Known/intentional issue. I couldn't decide where I wanted it, so I > put it > >> > in both places. If you have a strong opinion right now, please let m= e > know > >> > what it is and I'll take care of it, it's easy - but it's code in th= e > >> > predecessor series and nothing to do with qapidoc, so please put it > out of > >> > mind for now. > >> > > >> > If you don't have strong feelings, or you feel that the answer may > depend > >> > on how we solve other glaring issues (non-definition conditionals), > let's > >> > wait a little bit before making a decision. > >> > > >> > Added to tasklist: "Remove the duplication of definition > conditionals"; > >> > left unspecified is how or in what direction :) > >> > >> ACK > >> > >> I'll try to make up my mind :) > >> > > > > I should also point out, this is an issue in the domain and not the > > generator; the generated rst document doesn't have this duplication. So > > it's kind of a no-op while we look and consider this specific series, b= ut > > it's still on my list when we go to look at the predecessor series. > > Understood. > > [...] > > --00000000000044b778062eaae07a Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Fri, Feb 21,= 2025 at 1:42=E2=80=AFAM Markus Armbruster <armbru@redhat.com> wrote:
John Snow <jsnow@redhat.com> writes:

> On Wed, Feb 19, 2025 at 8:22=E2=80=AFAM Markus Armbruster <armbru@redhat.com> w= rote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > "The text handler you add looks just like the existing l= atex handler. Does
>> > LaTeX output lack "little headings", too?"
>> >
>> > Yes, almost certainly. Can you let me know which output forma= ts we actually
>> > "care about"? I'll have to test them all.
>>
>> As far as I can tell, our build system runs sphinx-build -b html a= nd -b
>> man.
>>
>> I run it with -b text manually all the time to hunt for and review=
>> changes in output.=C2=A0 I'd prefer to keep it working if prac= tical.
>>
>> For what it's worth, there is a bit of LaTeX configuration in<= br> >> docs/conf.py.
>>
>> >=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0In the meantime, I upgraded my
>> > patch so that the text translator properly handles branches w= ith headings
>> > that delineate the different branches so that the text output= is fully
>> > reasonable. I will need to do the same for any format we care= about.
>> >
>> > I've re-pushed as of "about 30 minutes before I wrot= e this email" --
>> > https://gitlab.com/jsnow/= qemu/-/commits/sphinx-domain-blergh2
>> >
>> > This branch includes the text generator fixes (which technica= lly belong
>> > with the predecessor series we skipped, but I'll refactor= that later.)
>> > it also includes fixes to the branch inliner, generated retur= n statements,
>> > and generated out-of-band feature sections.
>>
>> I'll fetch it, thanks!
>>
>> > (Long story short: inserting new sections in certain spots wa= s broken
>> > because of cache. Oops. We can discuss more why I wrote that = part of the
>> > code like I did in review for the patch that introduced that = problem. It's
>> > the "basic inliner" patch.)
>> >
>> > Below, I'm going to try a new communication approach wher= e I explicitly say
>> > if I have added something to my tasklist or not so that it= 9;s clear to you
>> > what I believe is actionable (and what I am agreeing to chang= e) and what I
>> > believe needs stronger input from you before I do anything. A= pologies if it
>> > seems a little robotic, just trying new things O:-)
>> >
>> > On that note: not added to tasklist: do we need the LaTeX han= dler? Do we
>> > need any others? Please confirm O:-)
>>
>> See above.
>>
>
> I've got html and text working, text wasn't hard. I will give = it a good
> college try on the LaTeX and man formats. Might be easy. The issue her= e is
> the custom node I introduced for the collapsible details sections whic= h has
> no default handler in the generators. I'll have to learn more abou= t that
> part of the API, I haven't interfaced with it much yet.

Understand.

Have you considered cutting the series in half before the inliner?
First part emits "The members of ..." like the old doc generator.=
Second part replaces that with inlined material.

We could totally release with just the first half!=C2=A0 Inlining is great,=
but even without it, your work looks so much better and is so much more
usable.

I may indeed just do that... th= ough we still need to solve "where to put the ifcond data?" quest= ion. The documentation culling also must be held back in this case too, whi= ch I am fine with.

Let me fork my work (again) and= see how complicated an inlinerless version would be... maybe that's a = great way to flush the queue. maybe.
=C2=A0

>> > On Fri, Feb 14, 2025 at 7:05=E2=80=AFAM Markus Armbruster <= ;armbru@redhat.com> wrote:
>> >
>> >> I started to eyeball old and new generated output side by= side.
>> >>
>> >> New table of contents shows one level, old two.=C2=A0 No = objection; the
>> >> navigation thingie on the left is more useful anyway.
>> >>
>> >
>> > Unintentional, but if you like it, it's fine by me. Nothi= ng added to my
>> > tasklist.
>>
>> Mention in a commit message.
>>
>
> Sure. I... just need to figure out which commit to mention it in. Adde= d to
> my list, anyway.

>
>
>>
>> >> The new generator elides unreferenced types.=C2=A0 Genera= lly good, but two
>> >> observations:
>> >>
>> >> * QapiErrorClass is unreferenced, but its members are men= tioned in
>> >>=C2=A0 =C2=A0Errors sections.=C2=A0 QapiErrorClass serves = as better than nothing error
>> >>=C2=A0 =C2=A0code documentation, but it's gone in the = new doc.=C2=A0 So this is a minor
>> >>=C2=A0 =C2=A0regression.=C2=A0 We can figure out what to d= o about it later.
>> >>
>> >
>> > Right. I debated making the members references to that class,= but recalled
>> > that you disliked this class and figured you'd not like s= uch a change, so I
>> > just left it alone. I do not have cross-references for indivi= dual members
>> > of objects at all yet anyway, so this is definitely more work= regardless.
>> >
>> > We could always create a pragma of some sort (or just hardcod= e a list) of
>> > items that must be documented regardless of if they're re= ferenced or not.
>> > Please let me know your preference and I will add a "tic= ket" on my personal
>> > tasklist for this project to handle that at /some point/. Not= hing added to
>> > my tasklist just yet.
>>
>> Suggest to add something like "compensate for the loss of Qap= iErrorClass
>> documentation in the QEMU QMP Reference Manual".
>>
>
> Got it. Possibly a "for later" task but not much later. It c= an always come
> after this first series, but before we "turn on" the new gen= erator, if that
> makes sense. Just so we reach a quiescent point and flush the staggeri= ngly
> large queue.

I think we could even do it after "turn on".=C2=A0 Yes, it's = a small
regression, but I believe the improvements are big enough to outweigh
small regressions like this one.

OK.
=C2=A0

> I guess what I mean is: "Let's make sure what I've got he= re so far is good
> first, and then I'll start adding stuff."

[...]

>> >> The new doc's headings use "Struct" or &quo= t;Union" where the old one uses
>> >> just "Object".=C2=A0 Let's keep "Objec= t", please.
>> >>
>> >
>> > I was afraid you'd ask for this. OK, I think it's an = easy change. Can I
>> > keep the index page segmented by object type still, though? >> >
>> > I do find knowing the *type* of object to be helpful as a dev= eloper,
>>
>> Can you explain why and how struct vs. union matters to you as a >> developer?
>>
>
> I suppose it's just internal details that I like to know, but tend= to find
> the HTML reference easier to work with than grepping through the qapi<= br> > files. I'm gonna change it for you anyway because I agree it's= not
> consistent with the philosophy of "end user QMP reference". = Just feels like
> a tiny shame somehow.
>
>
>>
>> > though
>> > I understand that from the point of view of a QMP user, they&= #39;re all just
>> > objects, so your request makes sense.
>>
>> I'd prefer a single index.
>>
>
> So ... structs, unions, alternates all condensed down to "Object&= quot;, is that
> right? We get to keep command/enum/event separate, I assume.

No, only structs and unions are "Object", alternates are "Al= ternate".

For me, the separation between struct and union is an unfortunate
remnant of somewhat winding development history.

A union is has common members, one of them is the tag, and for each tag
value, it may have variant members.

A struct is a degenerate union: no variants.

This is as old as the hills: Pascal records are just like this.

QMP introspection doesn't show structs and unions, just objects, which<= br> may or may not have variants.

The schema language syntax, however, is still rooted (stuck?) in a past
when unions could not have common members other than the tag.

OK, I can combine these two easily then. I see why y= ou feel it isn't worth knowing the difference for developers either und= er this view.
=C2=A0

[...]

>> >> The new doc doesn't show non-definition conditionals,= as mentioned in
>> >> the cover letter.=C2=A0 It shows definition conditionals = twice.=C2=A0 Once should
>> >> suffice.
>> >>
>> >
>> > Known/intentional issue. I couldn't decide where I wanted= it, so I put it
>> > in both places. If you have a strong opinion right now, pleas= e let me know
>> > what it is and I'll take care of it, it's easy - but = it's code in the
>> > predecessor series and nothing to do with qapidoc, so please = put it out of
>> > mind for now.
>> >
>> > If you don't have strong feelings, or you feel that the a= nswer may depend
>> > on how we solve other glaring issues (non-definition conditio= nals), let's
>> > wait a little bit before making a decision.
>> >
>> > Added to tasklist: "Remove the duplication of definition= conditionals";
>> > left unspecified is how or in what direction :)
>>
>> ACK
>>
>> I'll try to make up my mind :)
>>
>
> I should also point out, this is an issue in the domain and not the > generator; the generated rst document doesn't have this duplicatio= n. So
> it's kind of a no-op while we look and consider this specific seri= es, but
> it's still on my list when we go to look at the predecessor series= .

Understood.

[...]

--00000000000044b778062eaae07a--