Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Stephen Brennan <stephen.s.brennan@oracle.com>
To:     "Paul A. Clarke" <pc@us.ibm.com>
Cc:     Peter Zijlstra <peterz@infradead.org>,
        Ingo Molnar <mingo@redhat.com>,
        Arnaldo Carvalho de Melo <acme@kernel.org>,
        Mark Rutland <mark.rutland@arm.com>,
        Alexander Shishkin <alexander.shishkin@linux.intel.com>,
        Jiri Olsa <jolsa@redhat.com>,
        Namhyung Kim <namhyung@kernel.org>,
        linux-perf-users@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] perf script python: fix unintended underline
In-Reply-To: <20210806211348.GA66379@li-24c3614c-2adc-11b2-a85c-85f334518bdb.ibm.com>
References: <20210806204502.110305-1-stephen.s.brennan@oracle.com>
 <20210806211348.GA66379@li-24c3614c-2adc-11b2-a85c-85f334518bdb.ibm.com>
Date:   Fri, 06 Aug 2021 14:28:13 -0700
Message-ID: <87bl6a1cwi.fsf@stepbren-lnx.us.oracle.com>
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-MessageSentRepresentingType: 1
Received: from localhost (148.87.23.11) by SN7PR04CA0233.namprd04.prod.outlook.com (2603:10b6:806:127::28) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4394.17 via Frontend Transport; Fri, 6 Aug 2021 21:28:12 +0000
X-MS-PublicTrafficType: Email
X-MS-Office365-Filtering-Correlation-Id: 24f7c323-942e-4e6c-9c18-08d959211899
X-MS-TrafficTypeDiagnostic: CH0PR10MB5499:
X-Microsoft-Antispam-PRVS: <CH0PR10MB54996F6E37D4E0882FBC5030DBF39@CH0PR10MB5499.namprd10.prod.outlook.com>
X-MS-Oob-TLC-OOBClassifiers: OLM:9508;
X-MS-Exchange-SenderADCheck: 1
X-MS-Exchange-AntiSpam-Relay: 0
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: LYQ9xrYDxV8Cm3uex7DHq5Az8xyksdfIuk+bK4kUWJZSmUTD5ys4DcUnn6fteuVD2zw9knez/Sn/0kT7jHd6bxc/qAPKsnl0TNkK6AAy1dn2HgKYiZRT/vY6LGyxCpKJCB8uOWyeZqfFqPVVvx1aiyAHHpBN6b6cn71jyZe5mbGFBEM0phDGLXnxZvOYJA/1pzS0W3RDGQFMBONl6KLKs9WY1ZLH9LmP2ew5gnJMM0FIjGF9wgOaQBCaJHrTHO3NdiCvMRW7qGj8Lv9oDtVHoKj1s9+dM7E0zB8AZe+DvL7s6R/0Zh/ZjJXSg1/YRhYA47SmEUWDCLLTMpp4tMOBW7QK4ggeCDJzi5jrLuHxKvi+108REtjyGhEKYMUt9r5teR/e1B6TQoyIQyxZBT/2+Q4FhxPrGo0VYSiFyFrIsjHxLFzWdutZXqPFDBfP/0a9THH8u2CfhEyb/B4Ljcbh09zK66TMP1AitRLtzmqMeXcRWIFNJfurRTLdqCXpZvZ1IIZjFczExIsBM+c+rlwD9xSjHMT85uRGIaT3mWO55Qod/g1LBNaJFRGGC8U1ztNZBwdTe4tQBW4C+fWS0Axi5EjpbzbLopFYaRhj12OKDIhrTCYDWDTl1TcgvANEbVtpV9F9Fs4cHo81tx0sD4fwf/94yzzWs3MQRpHEZ7Laxpnr7fYKIeeJDYuNIHXSgm0c
X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:CH2PR10MB4166.namprd10.prod.outlook.com;PTR:;CAT:NONE;SFS:(136003)(396003)(366004)(346002)(39860400002)(376002)(52116002)(26005)(6486002)(8936002)(186003)(4326008)(8676002)(2906002)(316002)(66946007)(54906003)(86362001)(7416002)(66556008)(66476007)(956004)(38350700002)(6496006)(6916009)(38100700002)(5660300002)(478600001);DIR:OUT;SFP:1101;
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?fp9sIL78LtztYdCSqHcBuYjeb65QEOjGZJugoyIiMmCQPV7IgseI6Oqy7PT5?=
 =?us-ascii?Q?1tTtj4KR8V4v3358ef1xFk0FEi13mJH+ACImk474nfpLRvBini2BCOEWeMPd?=
 =?us-ascii?Q?bPsIeuZWPt7OjfnQkRtKMjng5hVqBvYuhuk9x66uL5lWgiZLPPQqH0pAJcoE?=
 =?us-ascii?Q?/Yjo9nvB5N2q/siiitR73KPctAwlp81byJpji7isU1CUxXPJF7Uw8yzwcMmL?=
 =?us-ascii?Q?jmMH3HddnsByqn6ImxYpJSavfLgOY9hvZxlWVbZNCFza7J5y/AAYqDPFqnl9?=
 =?us-ascii?Q?gqsiq2GO0AyWHe0I7duhOSiCphmIcW4bLr7Rc46v1HEzR5PzeU3M5NuA/G/O?=
 =?us-ascii?Q?ZbMceOGgPJdiZR0w56t1vc4DQkKe6MNwjr+xHNj8jJ9y7vxNs83e79WWmNA8?=
 =?us-ascii?Q?NDM7O292JcrLCQNwMiHlK1XP6ZeE4y5so0+mWvo62VLtLMG/XjrO3JBuetQM?=
 =?us-ascii?Q?qakwhJ9Junwq4t8A0ZjhsgrYLIIL5O0YScaaKBpYuxMgN1mlZVOeXBfi4uzl?=
 =?us-ascii?Q?/lHTCUy8VOZ24Z+wNNCCdKqmV90EK+O9YavpjOxrazRsoy8t0TI+zSr6UwnQ?=
 =?us-ascii?Q?wevmQ6A5ZKKafvAsSxu7Lf9cLbJfRE5qaU0NjdDGcny2nCtLXDNu9sNc4wJm?=
 =?us-ascii?Q?/b0Hw9yfKEol2MLughenDT0NcInyM901l64p0AMjAT6v01yQomU48CIL2bz6?=
 =?us-ascii?Q?UvWGD+SKq21mPNCAPsHpZgUSkZe0Sb+yVRZSuVo55QCLbAXzzIuKKKe+QMak?=
 =?us-ascii?Q?faaVzWPgxBIKYyKrCeaKBDLjjXIvLwjnY+MaRl0rWf6pnfuCDRD63prIocca?=
 =?us-ascii?Q?yVTu/mnPcv/JBKUn0PQiaijXYwG4zyjinVEZf3Wz3oIe1Ryk4pDto5lJUMT3?=
 =?us-ascii?Q?wJQcizVJmN4sYUiuct9lpDJLoFN/cQtkMu0Eek+wCCs08Jh0eMryob5ckIGt?=
 =?us-ascii?Q?G47iMkRraceHt7zid5Wa3QZhK6PkeShcNkkKitqkCddgLk42bL357egSio4a?=
 =?us-ascii?Q?/8R0Cg2UudOkdUOyLKWb6OVjZw+GbUgyhmZ2FTYTzAYKLxcyUpxeGIbd2n80?=
 =?us-ascii?Q?eQsSiKL7HvK8uA469guxZ3A9OQrKzUcyHdl757wasi/P4uv2Ajb5Axn3T9Ow?=
 =?us-ascii?Q?g4ySWungwunAr5K1gS22ZrA1hzKMZp7qi9WHHLn8bA0KQqa7FT+FBoWGC0rQ?=
 =?us-ascii?Q?NOvh0HZuMdqfnQqOPd85R9IliVF1w2TOJHIVWUEvvXTG95vDA4cHH/q7DA9z?=
 =?us-ascii?Q?burGIskqW2KPG3Ob1tTbQqpctnjaGKa7l8W567ulSvVNCKv71MLhVkMUcfn6?=
 =?us-ascii?Q?WwIvGquLmiYMZzW3KueqIq2b?=
X-OriginatorOrg: oracle.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 24f7c323-942e-4e6c-9c18-08d959211899
X-MS-Exchange-CrossTenant-AuthSource: CH2PR10MB4166.namprd10.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 06 Aug 2021 21:28:13.2383
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: VEJjGAaRhV2wez+AGYhaLBmODiwuv3fP30sU+8yA+VZTK7O7vEn/3q8ImWqeAH9zVIrfOqIVSWfsy1y0EkyFVeiLwCrBmFHp8ODhStAytWw=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CH0PR10MB5499
X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=10068 signatures=668682
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxlogscore=999 mlxscore=0 phishscore=0
 bulkscore=0 adultscore=0 suspectscore=0 spamscore=0 malwarescore=0
 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2107140000
 definitions=main-2108060139
X-Proofpoint-ORIG-GUID: Cc4S5-yBdgNbcnflWxxeq3q0R8qpv_jk
X-Proofpoint-GUID: Cc4S5-yBdgNbcnflWxxeq3q0R8qpv_jk
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

"Paul A. Clarke" <pc@us.ibm.com> writes:

> On Fri, Aug 06, 2021 at 01:45:01PM -0700, Stephen Brennan wrote:
>> The text ranging from "subsystem__event_name" to
>> "raw_syscalls__sys_enter()" is interpreted by asciidoc as a pair of
>> unconstrained text formatting markers. The result is that the manual
>> page displayed this text as underlined, and the HTML pages displayed
>> this text as italicized. Escape the first double-underscore to prevent
>> this.
>
> I think it would be better to escape the second double-underscore as well,
> to prevent the same problem recurring with future changes.
>
>> diff --git a/tools/perf/Documentation/perf-script-python.txt b/tools/perf/Documentation/perf-script-python.txt
>> index 5e43cfa5ea1e..0250dc61cf98 100644
>> --- a/tools/perf/Documentation/perf-script-python.txt
>> +++ b/tools/perf/Documentation/perf-script-python.txt
>> @@ -167,7 +167,7 @@ below).
>> 
>>  Following those are the 'event handler' functions generated one for
>>  every event in the 'perf record' output.  The handler functions take
>> -the form subsystem__event_name, and contain named parameters, one for
>> +the form subsystem\__event_name, and contain named parameters, one for
>>  each field in the event; in this case, there's only one event,
>>  raw_syscalls__sys_enter().  (see the EVENT HANDLERS section below for
>
> escape this    ^ , too.

I've tried escaping a few combinations of these four underscores.

  \__ __    - escaping the first but not the second (as this patch)
              produces correct output
  \_\_ \_\_ - escaping all underscores results in no underlines, but the
              manual page shows "raw_syscalls\_\_sys_enter()" in its
              output.
  \_\_ __   - escaping the first two results in no underlines, but the
              manual page shows "subsystem\_\_event_name"
  \__ \__   - escaping the first of each double-underscore results in no
              underlines, but the manual page shows
              "raw_syscalls\__sys_enter()"

It seems that asciidoc only allows the first in a potential pair to be
escaped? I'll be the first to admit, I know nothing about asciidoc, so I
may have missed something here.

Stephen

>
>>  more info on event handlers).
>> -- 
>
> PC