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 X-Spam-Level: X-Spam-Status: No, score=-7.7 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_2 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2F644C48BD1 for ; Tue, 8 Jun 2021 07:28:36 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 162D86127A for ; Tue, 8 Jun 2021 07:28:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230329AbhFHHaW (ORCPT ); Tue, 8 Jun 2021 03:30:22 -0400 Received: from mail.kernel.org ([198.145.29.99]:40350 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229518AbhFHHaU (ORCPT ); Tue, 8 Jun 2021 03:30:20 -0400 Received: by mail.kernel.org (Postfix) with ESMTPSA id B3D5C61073; Tue, 8 Jun 2021 07:28:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1623137307; bh=O/zMXaiejHSPpLDrpWoLj5vApKw6co+rXXxeAdTs0fQ=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=nLlyZlZD273F402k83SpAE2/yTCnSoxOmIHbl9CNTcXkiOIJIwbU4EIxQMSt2a4ml qYAZ7+GRyFby1j7J/b6Qdg0ngb9aWUorA3LUTEzB/o7nAxtpl99tYE56SX6c/L7cnq JkQNkQc+kckZEP6v8MtI7gBXthqAyHNA2ro1bRHL944hNLYqFQNYNtkG14YdEsbCz8 WiPAfikei2ZlyE9DmtO+G5LcsEimR8Zt3bf/sh+4dSJxaQew1IHT6LAPnPOy5G3d1V 9RKb6ljsgqP02St+w9CxWqyTHfLgCquU2TvIEjFpSrPZM71r6hel2yJmUWm39106ZP ITZzuhEQ/FbwA== Date: Tue, 8 Jun 2021 09:28:19 +0200 From: Mauro Carvalho Chehab To: "=?UTF-8?B?TsOtY29sYXM=?= F. R. A. Prado" Cc: Jonathan Corbet , Linux Doc Mailing List , linux-kernel@vger.kernel.org, bpf@vger.kernel.org, coresight@lists.linaro.org, devicetree@vger.kernel.org, kunit-dev@googlegroups.com, kvm@vger.kernel.org, linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-gpio@vger.kernel.org, linux-hwmon@vger.kernel.org, linux-i2c@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-media@vger.kernel.org, linux-pci@vger.kernel.org, linux-pm@vger.kernel.org, linux-security-module@vger.kernel.org, netdev@vger.kernel.org Subject: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Message-ID: <20210608092819.3f4191b3@coco.lan> In-Reply-To: <20210608003458.kwhbn6mraekcutlt@notapiano> References: <20210605151109.axm3wzbcstsyxczp@notapiano> <20210605210836.540577d4@coco.lan> <20210606225225.fz4dsyz6im4bqena@notapiano> <20210607093422.0a369909@coco.lan> <20210608003458.kwhbn6mraekcutlt@notapiano> X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.33; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-hwmon@vger.kernel.org Em Mon, 7 Jun 2021 21:34:58 -0300 N=C3=ADcolas F. R. A. Prado escreveu: > Hi Mauro, >=20 > On Mon, Jun 07, 2021 at 09:34:22AM +0200, Mauro Carvalho Chehab wrote: > > Em Sun, 6 Jun 2021 19:52:25 -0300 > > N=C3=ADcolas F. R. A. Prado escreveu: > > =20 > > > On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote= : =20 > > > > Em Sat, 5 Jun 2021 12:11:09 -0300 > > > > N=C3=ADcolas F. R. A. Prado escreveu: > > > > =20 > > > > > Hi Mauro, > > > > >=20 > > > > > On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab w= rote: =20 > > > > > > As discussed at: > > > > > > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > > > > >=20 > > > > > > It is better to avoid using :doc:`foo` to refer to Documentatio= n/foo.rst, as the > > > > > > automarkup.py extension should handle it automatically, on most= cases. > > > > > >=20 > > > > > > There are a couple of exceptions to this rule: > > > > > >=20 > > > > > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > > > > > > 2. when it is used with a named tag, e. g. :doc:`some name `; > > > > > >=20 > > > > > > It should also be noticed that automarkup.py has currently an i= ssue: > > > > > > if one use a markup like: > > > > > >=20 > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > > > - documents all of the standard testing API excluding mocking > > > > > > or mocking related features. > > > > > >=20 > > > > > > or, even: > > > > > >=20 > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > > > documents all of the standard testing API excluding mocking > > > > > > or mocking related features. > > > > > > =09 > > > > > > The automarkup.py will simply ignore it. Not sure why. This pat= ch series > > > > > > avoid the above patterns (which is present only on 4 files), bu= t it would be > > > > > > nice to have a followup patch fixing the issue at automarkup.py= . =20 > > > > >=20 > > > > > What I think is happening here is that we're using rST's syntax f= or definition > > > > > lists [1]. automarkup.py ignores literal nodes, and perhaps a def= inition is > > > > > considered a literal by Sphinx. Adding a blank line after the Doc= umentation/... > > > > > or removing the additional indentation makes it work, like you di= d in your > > > > > 2nd and 3rd patch, since then it's not a definition anymore, alth= ough then the > > > > > visual output is different as well. =20 > > > >=20 > > > > A literal has a different output. I think that this is not the case= , but I=20 > > > > didn't check the python code from docutils/Sphinx. =20 > > >=20 > > > Okay, I went in deeper to understand the issue and indeed it wasn't w= hat I > > > thought. The reason definitions are ignored by automarkup.py is becau= se the main > > > loop iterates only over nodes that are of type paragraph: > > >=20 > > > for para in doctree.traverse(nodes.paragraph): > > > for node in para.traverse(nodes.Text): > > > if not isinstance(node.parent, nodes.literal): > > > node.parent.replace(node, markup_refs(name, app, node= )) > > >=20 > > > And inspecting the HTML output from your example, the definition name= is inside > > > a
tag, and it doesn't have a

inside. So in summary, automark= up.py will > > > only work on elements which are inside a

in the output. =20 > >=20 > >=20 > > Yeah, that's what I was suspecting, based on the comments. > >=20 > > Maybe something similar to the above could be done also for some > > non-paragraph data. By looking at: > >=20 > > https://docutils.sourceforge.io/docs/ref/doctree.html > >=20 > > It says that the body elements are: > >=20 > > admonition, attention, block_quote, bullet_list, caution, citation,=20 > > comment, compound, container, danger, definition_list, doctest_block,= =20 > > enumerated_list, error, field_list, figure, footnote, hint, image,=20 > > important, line_block, literal_block, note, option_list, paragraph,=20 > > pending, raw, rubric, substitution_definition, system_message,=20 > > table, target, tip, warning =20 >=20 > Ok, I went through each one by searching the term on [1] and inspecting t= he > element to see if it contained a

or not. The vast majority did. These= are > the ones I didn't find there or didn't make sense: >=20 > comment > container > image > pending > raw > substitution_definition > system_message > target >=20 > We can safely ignore them. And these are the ones that matter and don't h= ave > paragraphs: >=20 > 1. literal_block > 2. doctest_block > 3. definition_list > 4. field_list > 5. option_list > 6. line_block >=20 > 1 and 2 are literals, so we don't care about them. >=20 > 3 is the one you noticed the issue with. It's worth mentioning that the > definition term doesn't have a paragraph, but its definition does (as can= be > checked by inspecting [2]). >=20 > 4 is basically the same as 3, the rst syntax is different but the output = is the > same. That said, I believe we only use those to set options at the top of= the > file, like in translations, and I can't see automarkup being useful in th= ere. >=20 > 5 is similar to 3 and 4, but the term is formatted using , so it's l= ike a > literal and therefore not relevant. >=20 > 6 is useful just to preserve indentation, and I'm pretty sure we don't us= e it in > the docs. >=20 > So in the end, I think the only contenders to be added to automarkup are > definition lists, and even then I still think we should just substitute t= hose > definition lists with alternatives like you did in your patches. Personal= ly I > don't see much gain in using definitions instead of a simple paragraph. B= ut if > you really think it's an improvement in some way, it could probably be ad= ded to > automarkup in the way you described. Thank you for checking this! Kernel docs use a lot definition lists. At the initial versions, it was equivalent to: **Something to be written with emphasis** Some description Sphinx later changed the look-and-feel for the term, on html output, but the thing is that: Something to be written with emphasis Some description looks a lot better when read as a text file. Also, on some cases, the first notation doesn't work. The definition-list was the only way I know that would allow to apply an emphasis to a literal block. We can avoid using Documentation/foo on description lists: the current 4=20 cases where doc:`foo` are already addressed in this series, and the output is acceptable. Yet, I have a couple of concerns: 1. It might have some unknown places where a description list is used for Documentation/foo; 2. It is not trivial to identify if someone add Documentation/foo in the future; 3. I suspect that there are several places where functions and structs appear at the definition lists. (1) can probably be checked with a multi-line grep. So, not a big problem; (2) is something that would require someone to verify from time to time; but (3) are harder to check and seems to be a valid use-case. Due to (3), I think we should let automarkup to parse non-literal terms on description lists. At very least it should emit a warning when it won't be doing auto-conversions for known patterns at definition lists (if doing that would generate false-positives). Thanks, Mauro 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 X-Spam-Level: X-Spam-Status: No, score=-5.7 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS, URIBL_BLOCKED,USER_AGENT_SANE_2 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7CAE9C47082 for ; Tue, 8 Jun 2021 07:30:42 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 3D5B161184 for ; Tue, 8 Jun 2021 07:30:42 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 3D5B161184 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-ID:Subject:Cc:To:From:Date:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=nvtJ3Ewd0jnMWNLhTOMShhD3IZuU7OkXkCA7l6TfiQQ=; b=lNWy9AZ8cbkoqS /KXC+lB7p0uRc7+6sg1kM9Zy6+oHohEn/OGo5rCjLyARMRjFfMjvrihGzsLiKt/YC1lR0KjZpE6pU W2NBB+HaqCD1toVItnkPMD67fX7kFC0ianoIQU53hqKA5aykTwgUm+9Xqn54iXrFNAy8vIhXRGn6n +Q2SIyAsZ0xXBEPZX/piD10WHiSReqrBhPnRD+nubi+E67jh+EORfRtcChGzgpwpMIW+a7RVTQinj 3EjIT5XLxPvGXYoByzsM3x7QoYLbK6YKWhJeWO5WrjddsZdjvnykMptlgGjP13xDHthzENTsPTznW +FQg4Yfen+iCJAVngLAQ==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1lqWA3-006r53-NP; Tue, 08 Jun 2021 07:28:31 +0000 Received: from mail.kernel.org ([198.145.29.99]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1lqW9z-006r4a-Vs for linux-arm-kernel@lists.infradead.org; Tue, 08 Jun 2021 07:28:29 +0000 Received: by mail.kernel.org (Postfix) with ESMTPSA id B3D5C61073; Tue, 8 Jun 2021 07:28:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1623137307; bh=O/zMXaiejHSPpLDrpWoLj5vApKw6co+rXXxeAdTs0fQ=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=nLlyZlZD273F402k83SpAE2/yTCnSoxOmIHbl9CNTcXkiOIJIwbU4EIxQMSt2a4ml qYAZ7+GRyFby1j7J/b6Qdg0ngb9aWUorA3LUTEzB/o7nAxtpl99tYE56SX6c/L7cnq JkQNkQc+kckZEP6v8MtI7gBXthqAyHNA2ro1bRHL944hNLYqFQNYNtkG14YdEsbCz8 WiPAfikei2ZlyE9DmtO+G5LcsEimR8Zt3bf/sh+4dSJxaQew1IHT6LAPnPOy5G3d1V 9RKb6ljsgqP02St+w9CxWqyTHfLgCquU2TvIEjFpSrPZM71r6hel2yJmUWm39106ZP ITZzuhEQ/FbwA== Date: Tue, 8 Jun 2021 09:28:19 +0200 From: Mauro Carvalho Chehab To: "=?UTF-8?B?TsOtY29sYXM=?= F. R. A. Prado" Cc: Jonathan Corbet , Linux Doc Mailing List , linux-kernel@vger.kernel.org, bpf@vger.kernel.org, coresight@lists.linaro.org, devicetree@vger.kernel.org, kunit-dev@googlegroups.com, kvm@vger.kernel.org, linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-gpio@vger.kernel.org, linux-hwmon@vger.kernel.org, linux-i2c@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-media@vger.kernel.org, linux-pci@vger.kernel.org, linux-pm@vger.kernel.org, linux-security-module@vger.kernel.org, netdev@vger.kernel.org Subject: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Message-ID: <20210608092819.3f4191b3@coco.lan> In-Reply-To: <20210608003458.kwhbn6mraekcutlt@notapiano> References: <20210605151109.axm3wzbcstsyxczp@notapiano> <20210605210836.540577d4@coco.lan> <20210606225225.fz4dsyz6im4bqena@notapiano> <20210607093422.0a369909@coco.lan> <20210608003458.kwhbn6mraekcutlt@notapiano> X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.33; x86_64-redhat-linux-gnu) MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210608_002828_088237_C09E8491 X-CRM114-Status: GOOD ( 56.05 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org RW0gTW9uLCA3IEp1biAyMDIxIDIxOjM0OjU4IC0wMzAwCk7DrWNvbGFzIEYuIFIuIEEuIFByYWRv IDxuQG5mcmFwcmFkby5uZXQ+IGVzY3JldmV1OgoKPiBIaSBNYXVybywKPiAKPiBPbiBNb24sIEp1 biAwNywgMjAyMSBhdCAwOTozNDoyMkFNICswMjAwLCBNYXVybyBDYXJ2YWxobyBDaGVoYWIgd3Jv dGU6Cj4gPiBFbSBTdW4sIDYgSnVuIDIwMjEgMTk6NTI6MjUgLTAzMDAKPiA+IE7DrWNvbGFzIEYu IFIuIEEuIFByYWRvIDxuQG5mcmFwcmFkby5uZXQ+IGVzY3JldmV1Ogo+ID4gICAKPiA+ID4gT24g U2F0LCBKdW4gMDUsIDIwMjEgYXQgMDk6MDg6MzZQTSArMDIwMCwgTWF1cm8gQ2FydmFsaG8gQ2hl aGFiIHdyb3RlOiAgCj4gPiA+ID4gRW0gU2F0LCA1IEp1biAyMDIxIDEyOjExOjA5IC0wMzAwCj4g PiA+ID4gTsOtY29sYXMgRi4gUi4gQS4gUHJhZG8gPG5AbmZyYXByYWRvLm5ldD4gZXNjcmV2ZXU6 Cj4gPiA+ID4gICAgIAo+ID4gPiA+ID4gSGkgTWF1cm8sCj4gPiA+ID4gPiAKPiA+ID4gPiA+IE9u IFNhdCwgSnVuIDA1LCAyMDIxIGF0IDAzOjE3OjU5UE0gKzAyMDAsIE1hdXJvIENhcnZhbGhvIENo ZWhhYiB3cm90ZTogICAgCj4gPiA+ID4gPiA+IEFzIGRpc2N1c3NlZCBhdDoKPiA+ID4gPiA+ID4g CWh0dHBzOi8vbG9yZS5rZXJuZWwub3JnL2xpbnV4LWRvYy84NzFyOWs2cm15LmZzZkBtZWVyLmx3 bi5uZXQvCj4gPiA+ID4gPiA+IAo+ID4gPiA+ID4gPiBJdCBpcyBiZXR0ZXIgdG8gYXZvaWQgdXNp bmcgOmRvYzpgZm9vYCB0byByZWZlciB0byBEb2N1bWVudGF0aW9uL2Zvby5yc3QsIGFzIHRoZQo+ ID4gPiA+ID4gPiBhdXRvbWFya3VwLnB5IGV4dGVuc2lvbiBzaG91bGQgaGFuZGxlIGl0IGF1dG9t YXRpY2FsbHksIG9uIG1vc3QgY2FzZXMuCj4gPiA+ID4gPiA+IAo+ID4gPiA+ID4gPiBUaGVyZSBh cmUgYSBjb3VwbGUgb2YgZXhjZXB0aW9ucyB0byB0aGlzIHJ1bGU6Cj4gPiA+ID4gPiA+IAo+ID4g PiA+ID4gPiAxLiB3aGVuIDpkb2M6ICB0YWcgaXMgdXNlZCB0byBwb2ludCB0byBhIGtlcm5lbC1k b2MgRE9DOiBtYXJrdXA7Cj4gPiA+ID4gPiA+IDIuIHdoZW4gaXQgaXMgdXNlZCB3aXRoIGEgbmFt ZWQgdGFnLCBlLiBnLiA6ZG9jOmBzb21lIG5hbWUgPGZvbz5gOwo+ID4gPiA+ID4gPiAKPiA+ID4g PiA+ID4gSXQgc2hvdWxkIGFsc28gYmUgbm90aWNlZCB0aGF0IGF1dG9tYXJrdXAucHkgaGFzIGN1 cnJlbnRseSBhbiBpc3N1ZToKPiA+ID4gPiA+ID4gaWYgb25lIHVzZSBhIG1hcmt1cCBsaWtlOgo+ ID4gPiA+ID4gPiAKPiA+ID4gPiA+ID4gCURvY3VtZW50YXRpb24vZGV2LXRvb2xzL2t1bml0L2Fw aS90ZXN0LnJzdAo+ID4gPiA+ID4gPiAJICAtIGRvY3VtZW50cyBhbGwgb2YgdGhlIHN0YW5kYXJk IHRlc3RpbmcgQVBJIGV4Y2x1ZGluZyBtb2NraW5nCj4gPiA+ID4gPiA+IAkgICAgb3IgbW9ja2lu ZyByZWxhdGVkIGZlYXR1cmVzLgo+ID4gPiA+ID4gPiAKPiA+ID4gPiA+ID4gb3IsIGV2ZW46Cj4g PiA+ID4gPiA+IAo+ID4gPiA+ID4gPiAJRG9jdW1lbnRhdGlvbi9kZXYtdG9vbHMva3VuaXQvYXBp L3Rlc3QucnN0Cj4gPiA+ID4gPiA+IAkgICAgZG9jdW1lbnRzIGFsbCBvZiB0aGUgc3RhbmRhcmQg dGVzdGluZyBBUEkgZXhjbHVkaW5nIG1vY2tpbmcKPiA+ID4gPiA+ID4gCSAgICBvciBtb2NraW5n IHJlbGF0ZWQgZmVhdHVyZXMuCj4gPiA+ID4gPiA+IAkKPiA+ID4gPiA+ID4gVGhlIGF1dG9tYXJr dXAucHkgd2lsbCBzaW1wbHkgaWdub3JlIGl0LiBOb3Qgc3VyZSB3aHkuIFRoaXMgcGF0Y2ggc2Vy aWVzCj4gPiA+ID4gPiA+IGF2b2lkIHRoZSBhYm92ZSBwYXR0ZXJucyAod2hpY2ggaXMgcHJlc2Vu dCBvbmx5IG9uIDQgZmlsZXMpLCBidXQgaXQgd291bGQgYmUKPiA+ID4gPiA+ID4gbmljZSB0byBo YXZlIGEgZm9sbG93dXAgcGF0Y2ggZml4aW5nIHRoZSBpc3N1ZSBhdCBhdXRvbWFya3VwLnB5LiAg ICAgIAo+ID4gPiA+ID4gCj4gPiA+ID4gPiBXaGF0IEkgdGhpbmsgaXMgaGFwcGVuaW5nIGhlcmUg aXMgdGhhdCB3ZSdyZSB1c2luZyByU1QncyBzeW50YXggZm9yIGRlZmluaXRpb24KPiA+ID4gPiA+ IGxpc3RzIFsxXS4gYXV0b21hcmt1cC5weSBpZ25vcmVzIGxpdGVyYWwgbm9kZXMsIGFuZCBwZXJo YXBzIGEgZGVmaW5pdGlvbiBpcwo+ID4gPiA+ID4gY29uc2lkZXJlZCBhIGxpdGVyYWwgYnkgU3Bo aW54LiBBZGRpbmcgYSBibGFuayBsaW5lIGFmdGVyIHRoZSBEb2N1bWVudGF0aW9uLy4uLgo+ID4g PiA+ID4gb3IgcmVtb3ZpbmcgdGhlIGFkZGl0aW9uYWwgaW5kZW50YXRpb24gbWFrZXMgaXQgd29y aywgbGlrZSB5b3UgZGlkIGluIHlvdXIKPiA+ID4gPiA+IDJuZCBhbmQgM3JkIHBhdGNoLCBzaW5j ZSB0aGVuIGl0J3Mgbm90IGEgZGVmaW5pdGlvbiBhbnltb3JlLCBhbHRob3VnaCB0aGVuIHRoZQo+ ID4gPiA+ID4gdmlzdWFsIG91dHB1dCBpcyBkaWZmZXJlbnQgYXMgd2VsbC4gICAgCj4gPiA+ID4g Cj4gPiA+ID4gQSBsaXRlcmFsIGhhcyBhIGRpZmZlcmVudCBvdXRwdXQuIEkgdGhpbmsgdGhhdCB0 aGlzIGlzIG5vdCB0aGUgY2FzZSwgYnV0IEkgCj4gPiA+ID4gZGlkbid0IGNoZWNrIHRoZSBweXRo b24gY29kZSBmcm9tIGRvY3V0aWxzL1NwaGlueC4gICAgCj4gPiA+IAo+ID4gPiBPa2F5LCBJIHdl bnQgaW4gZGVlcGVyIHRvIHVuZGVyc3RhbmQgdGhlIGlzc3VlIGFuZCBpbmRlZWQgaXQgd2Fzbid0 IHdoYXQgSQo+ID4gPiB0aG91Z2h0LiBUaGUgcmVhc29uIGRlZmluaXRpb25zIGFyZSBpZ25vcmVk IGJ5IGF1dG9tYXJrdXAucHkgaXMgYmVjYXVzZSB0aGUgbWFpbgo+ID4gPiBsb29wIGl0ZXJhdGVz IG9ubHkgb3ZlciBub2RlcyB0aGF0IGFyZSBvZiB0eXBlIHBhcmFncmFwaDoKPiA+ID4gCj4gPiA+ ICAgICBmb3IgcGFyYSBpbiBkb2N0cmVlLnRyYXZlcnNlKG5vZGVzLnBhcmFncmFwaCk6Cj4gPiA+ ICAgICAgICAgZm9yIG5vZGUgaW4gcGFyYS50cmF2ZXJzZShub2Rlcy5UZXh0KToKPiA+ID4gICAg ICAgICAgICAgaWYgbm90IGlzaW5zdGFuY2Uobm9kZS5wYXJlbnQsIG5vZGVzLmxpdGVyYWwpOgo+ ID4gPiAgICAgICAgICAgICAgICAgbm9kZS5wYXJlbnQucmVwbGFjZShub2RlLCBtYXJrdXBfcmVm cyhuYW1lLCBhcHAsIG5vZGUpKQo+ID4gPiAKPiA+ID4gQW5kIGluc3BlY3RpbmcgdGhlIEhUTUwg b3V0cHV0IGZyb20geW91ciBleGFtcGxlLCB0aGUgZGVmaW5pdGlvbiBuYW1lIGlzIGluc2lkZQo+ ID4gPiBhIDxkdD4gdGFnLCBhbmQgaXQgZG9lc24ndCBoYXZlIGEgPHA+IGluc2lkZS4gU28gaW4g c3VtbWFyeSwgYXV0b21hcmt1cC5weSB3aWxsCj4gPiA+IG9ubHkgd29yayBvbiBlbGVtZW50cyB3 aGljaCBhcmUgaW5zaWRlIGEgPHA+IGluIHRoZSBvdXRwdXQuICAKPiA+IAo+ID4gCj4gPiBZZWFo LCB0aGF0J3Mgd2hhdCBJIHdhcyBzdXNwZWN0aW5nLCBiYXNlZCBvbiB0aGUgY29tbWVudHMuCj4g PiAKPiA+IE1heWJlIHNvbWV0aGluZyBzaW1pbGFyIHRvIHRoZSBhYm92ZSBjb3VsZCBiZSBkb25l IGFsc28gZm9yIHNvbWUKPiA+IG5vbi1wYXJhZ3JhcGggZGF0YS4gQnkgbG9va2luZyBhdDoKPiA+ IAo+ID4gCWh0dHBzOi8vZG9jdXRpbHMuc291cmNlZm9yZ2UuaW8vZG9jcy9yZWYvZG9jdHJlZS5o dG1sCj4gPiAKPiA+IEl0IHNheXMgdGhhdCB0aGUgYm9keSBlbGVtZW50cyBhcmU6Cj4gPiAKPiA+ IAlhZG1vbml0aW9uLCBhdHRlbnRpb24sIGJsb2NrX3F1b3RlLCBidWxsZXRfbGlzdCwgY2F1dGlv biwgY2l0YXRpb24sIAo+ID4gCWNvbW1lbnQsIGNvbXBvdW5kLCBjb250YWluZXIsIGRhbmdlciwg ZGVmaW5pdGlvbl9saXN0LCBkb2N0ZXN0X2Jsb2NrLCAKPiA+IAllbnVtZXJhdGVkX2xpc3QsIGVy cm9yLCBmaWVsZF9saXN0LCBmaWd1cmUsIGZvb3Rub3RlLCBoaW50LCBpbWFnZSwgCj4gPiAJaW1w b3J0YW50LCBsaW5lX2Jsb2NrLCBsaXRlcmFsX2Jsb2NrLCBub3RlLCBvcHRpb25fbGlzdCwgcGFy YWdyYXBoLCAKPiA+IAlwZW5kaW5nLCByYXcsIHJ1YnJpYywgc3Vic3RpdHV0aW9uX2RlZmluaXRp b24sIHN5c3RlbV9tZXNzYWdlLCAKPiA+IAl0YWJsZSwgdGFyZ2V0LCB0aXAsIHdhcm5pbmcgIAo+ IAo+IE9rLCBJIHdlbnQgdGhyb3VnaCBlYWNoIG9uZSBieSBzZWFyY2hpbmcgdGhlIHRlcm0gb24g WzFdIGFuZCBpbnNwZWN0aW5nIHRoZQo+IGVsZW1lbnQgdG8gc2VlIGlmIGl0IGNvbnRhaW5lZCBh IDxwPiBvciBub3QuIFRoZSB2YXN0IG1ham9yaXR5IGRpZC4gVGhlc2UgYXJlCj4gdGhlIG9uZXMg SSBkaWRuJ3QgZmluZCB0aGVyZSBvciBkaWRuJ3QgbWFrZSBzZW5zZToKPiAKPiAJY29tbWVudAo+ IAljb250YWluZXIKPiAJaW1hZ2UKPiAJcGVuZGluZwo+IAlyYXcKPiAJc3Vic3RpdHV0aW9uX2Rl ZmluaXRpb24KPiAJc3lzdGVtX21lc3NhZ2UKPiAJdGFyZ2V0Cj4gCj4gV2UgY2FuIHNhZmVseSBp Z25vcmUgdGhlbS4gQW5kIHRoZXNlIGFyZSB0aGUgb25lcyB0aGF0IG1hdHRlciBhbmQgZG9uJ3Qg aGF2ZQo+IHBhcmFncmFwaHM6Cj4gCj4gCTEuIGxpdGVyYWxfYmxvY2sKPiAJMi4gZG9jdGVzdF9i bG9jawo+IAkzLiBkZWZpbml0aW9uX2xpc3QKPiAJNC4gZmllbGRfbGlzdAo+IAk1LiBvcHRpb25f bGlzdAo+IAk2LiBsaW5lX2Jsb2NrCj4gCj4gMSBhbmQgMiBhcmUgbGl0ZXJhbHMsIHNvIHdlIGRv bid0IGNhcmUgYWJvdXQgdGhlbS4KPiAKPiAzIGlzIHRoZSBvbmUgeW91IG5vdGljZWQgdGhlIGlz c3VlIHdpdGguIEl0J3Mgd29ydGggbWVudGlvbmluZyB0aGF0IHRoZQo+IGRlZmluaXRpb24gdGVy bSBkb2Vzbid0IGhhdmUgYSBwYXJhZ3JhcGgsIGJ1dCBpdHMgZGVmaW5pdGlvbiBkb2VzIChhcyBj YW4gYmUKPiBjaGVja2VkIGJ5IGluc3BlY3RpbmcgWzJdKS4KPiAKPiA0IGlzIGJhc2ljYWxseSB0 aGUgc2FtZSBhcyAzLCB0aGUgcnN0IHN5bnRheCBpcyBkaWZmZXJlbnQgYnV0IHRoZSBvdXRwdXQg aXMgdGhlCj4gc2FtZS4gVGhhdCBzYWlkLCBJIGJlbGlldmUgd2Ugb25seSB1c2UgdGhvc2UgdG8g c2V0IG9wdGlvbnMgYXQgdGhlIHRvcCBvZiB0aGUKPiBmaWxlLCBsaWtlIGluIHRyYW5zbGF0aW9u cywgYW5kIEkgY2FuJ3Qgc2VlIGF1dG9tYXJrdXAgYmVpbmcgdXNlZnVsIGluIHRoZXJlLgo+IAo+ IDUgaXMgc2ltaWxhciB0byAzIGFuZCA0LCBidXQgdGhlIHRlcm0gaXMgZm9ybWF0dGVkIHVzaW5n IDxrYmQ+LCBzbyBpdCdzIGxpa2UgYQo+IGxpdGVyYWwgYW5kIHRoZXJlZm9yZSBub3QgcmVsZXZh bnQuCj4gCj4gNiBpcyB1c2VmdWwganVzdCB0byBwcmVzZXJ2ZSBpbmRlbnRhdGlvbiwgYW5kIEkn bSBwcmV0dHkgc3VyZSB3ZSBkb24ndCB1c2UgaXQgaW4KPiB0aGUgZG9jcy4KPiAKPiBTbyBpbiB0 aGUgZW5kLCBJIHRoaW5rIHRoZSBvbmx5IGNvbnRlbmRlcnMgdG8gYmUgYWRkZWQgdG8gYXV0b21h cmt1cCBhcmUKPiBkZWZpbml0aW9uIGxpc3RzLCBhbmQgZXZlbiB0aGVuIEkgc3RpbGwgdGhpbmsg d2Ugc2hvdWxkIGp1c3Qgc3Vic3RpdHV0ZSB0aG9zZQo+IGRlZmluaXRpb24gbGlzdHMgd2l0aCBh bHRlcm5hdGl2ZXMgbGlrZSB5b3UgZGlkIGluIHlvdXIgcGF0Y2hlcy4gUGVyc29uYWxseSBJCj4g ZG9uJ3Qgc2VlIG11Y2ggZ2FpbiBpbiB1c2luZyBkZWZpbml0aW9ucyBpbnN0ZWFkIG9mIGEgc2lt cGxlIHBhcmFncmFwaC4gQnV0IGlmCj4geW91IHJlYWxseSB0aGluayBpdCdzIGFuIGltcHJvdmVt ZW50IGluIHNvbWUgd2F5LCBpdCBjb3VsZCBwcm9iYWJseSBiZSBhZGRlZCB0bwo+IGF1dG9tYXJr dXAgaW4gdGhlIHdheSB5b3UgZGVzY3JpYmVkLgoKVGhhbmsgeW91IGZvciBjaGVja2luZyB0aGlz IQoKS2VybmVsIGRvY3MgdXNlIGEgbG90IGRlZmluaXRpb24gbGlzdHMuIEF0IHRoZSBpbml0aWFs IHZlcnNpb25zLCBpdCB3YXMKZXF1aXZhbGVudCB0bzoKCgkqKlNvbWV0aGluZyB0byBiZSB3cml0 dGVuIHdpdGggZW1waGFzaXMqKgoKCSAgU29tZSBkZXNjcmlwdGlvbgoKU3BoaW54IGxhdGVyIGNo YW5nZWQgdGhlIGxvb2stYW5kLWZlZWwgZm9yIHRoZSB0ZXJtLCBvbiBodG1sIG91dHB1dCwgYnV0 CnRoZSB0aGluZyBpcyB0aGF0OgoKCVNvbWV0aGluZyB0byBiZSB3cml0dGVuIHdpdGggZW1waGFz aXMKCSAgIFNvbWUgZGVzY3JpcHRpb24KCmxvb2tzIGEgbG90IGJldHRlciB3aGVuIHJlYWQgYXMg YSB0ZXh0IGZpbGUuCgpBbHNvLCBvbiBzb21lIGNhc2VzLCB0aGUgZmlyc3Qgbm90YXRpb24gZG9l c24ndCB3b3JrLiBUaGUgZGVmaW5pdGlvbi1saXN0CndhcyB0aGUgb25seSB3YXkgSSBrbm93IHRo YXQgd291bGQgYWxsb3cgdG8gYXBwbHkgYW4gZW1waGFzaXMgdG8gYSBsaXRlcmFsCmJsb2NrLgoK V2UgY2FuIGF2b2lkIHVzaW5nIERvY3VtZW50YXRpb24vZm9vIG9uIGRlc2NyaXB0aW9uIGxpc3Rz OiB0aGUgY3VycmVudCA0IApjYXNlcyB3aGVyZSBkb2M6YGZvb2AgYXJlIGFscmVhZHkgYWRkcmVz c2VkIGluIHRoaXMgc2VyaWVzLCBhbmQgdGhlIG91dHB1dAppcyBhY2NlcHRhYmxlLgoKWWV0LCBJ IGhhdmUgYSBjb3VwbGUgb2YgY29uY2VybnM6CgoxLiBJdCBtaWdodCBoYXZlIHNvbWUgdW5rbm93 biBwbGFjZXMgd2hlcmUgYSBkZXNjcmlwdGlvbiBsaXN0IGlzIHVzZWQKICAgZm9yIERvY3VtZW50 YXRpb24vZm9vOwoyLiBJdCBpcyBub3QgdHJpdmlhbCB0byBpZGVudGlmeSBpZiBzb21lb25lIGFk ZCBEb2N1bWVudGF0aW9uL2ZvbyBpbgogICB0aGUgZnV0dXJlOwozLiBJIHN1c3BlY3QgdGhhdCB0 aGVyZSBhcmUgc2V2ZXJhbCBwbGFjZXMgd2hlcmUgZnVuY3Rpb25zIGFuZCBzdHJ1Y3RzCiAgIGFw cGVhciBhdCB0aGUgZGVmaW5pdGlvbiBsaXN0cy4KCigxKSBjYW4gcHJvYmFibHkgYmUgY2hlY2tl ZCB3aXRoIGEgbXVsdGktbGluZSBncmVwLiBTbywgbm90IGEgYmlnCiAgICBwcm9ibGVtOwoKKDIp IGlzIHNvbWV0aGluZyB0aGF0IHdvdWxkIHJlcXVpcmUgc29tZW9uZSB0byB2ZXJpZnkgZnJvbSB0 aW1lIHRvCiAgICB0aW1lOwoKYnV0ICgzKSBhcmUgaGFyZGVyIHRvIGNoZWNrIGFuZCBzZWVtcyB0 byBiZSBhIHZhbGlkIHVzZS1jYXNlLgoKRHVlIHRvICgzKSwgSSB0aGluayB3ZSBzaG91bGQgbGV0 IGF1dG9tYXJrdXAgdG8gcGFyc2Ugbm9uLWxpdGVyYWwKdGVybXMgb24gZGVzY3JpcHRpb24gbGlz dHMuIEF0IHZlcnkgbGVhc3QgaXQgc2hvdWxkIGVtaXQgYSB3YXJuaW5nIHdoZW4KaXQgd29uJ3Qg YmUgZG9pbmcgYXV0by1jb252ZXJzaW9ucyBmb3Iga25vd24gcGF0dGVybnMgYXQgZGVmaW5pdGlv bgpsaXN0cyAoaWYgZG9pbmcgdGhhdCB3b3VsZCBnZW5lcmF0ZSBmYWxzZS1wb3NpdGl2ZXMpLgoK VGhhbmtzLApNYXVybwoKX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX18KbGludXgtYXJtLWtlcm5lbCBtYWlsaW5nIGxpc3QKbGludXgtYXJtLWtlcm5lbEBsaXN0 cy5pbmZyYWRlYWQub3JnCmh0dHA6Ly9saXN0cy5pbmZyYWRlYWQub3JnL21haWxtYW4vbGlzdGlu Zm8vbGludXgtYXJtLWtlcm5lbAo=