From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id 8D3D041F54;
	Tue, 29 Aug 2023 12:12:08 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 6C0CB40293;
	Tue, 29 Aug 2023 12:12:08 +0200 (CEST)
Received: from mgamail.intel.com (mgamail.intel.com [192.55.52.151])
 by mails.dpdk.org (Postfix) with ESMTP id E1F5740279
 for <dev@dpdk.org>; Tue, 29 Aug 2023 12:12:05 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
 d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
 t=1693303926; x=1724839926;
 h=date:from:to:cc:subject:message-id:references:
 in-reply-to:mime-version;
 bh=/R3LfB+k2rYtfRgTI0jSOl13Ewkl+iK4OWYr3EXl3Tc=;
 b=jt3YWYMs4+ySyBU/ulhf8DGibzcvEKQ1xiztNaCvHjFYDFKcXpWOMsvh
 cNljmH9O2P0t1Med/4uYI78iMPmC2cBlcHJu+JXYGjBR0B8bWDDszClYs
 U+q+R7JBRRYTcxqiVu1TkUcxDbdxMwmChXvKKDlVksNkvyt9B1X+V/TWn
 jiEDByGGPdWF/2cPrkj6BIhEg6//k50VNKP5ksLMjiKuYlsnC8jzMY5QM
 30y7H5iCsSRJA2q3WjerVzq9ivov/ex1+N+23oaorcTHdb+4mHioHfopP
 Q6vnnbvbQ3B1QSmK9dMk72rNhMDeeHwvhpWFTmvuHv5eygO8JEzjJW/xi g==;
X-IronPort-AV: E=McAfee;i="6600,9927,10816"; a="355651511"
X-IronPort-AV: E=Sophos;i="6.02,210,1688454000"; d="scan'208";a="355651511"
Received: from fmsmga005.fm.intel.com ([10.253.24.32])
 by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
 29 Aug 2023 03:10:42 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=McAfee;i="6600,9927,10816"; a="1069407607"
X-IronPort-AV: E=Sophos;i="6.02,210,1688454000"; d="scan'208";a="1069407607"
Received: from orsmsx601.amr.corp.intel.com ([10.22.229.14])
 by fmsmga005.fm.intel.com with ESMTP; 29 Aug 2023 03:10:41 -0700
Received: from orsmsx602.amr.corp.intel.com (10.22.229.15) by
 ORSMSX601.amr.corp.intel.com (10.22.229.14) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2507.27; Tue, 29 Aug 2023 03:10:41 -0700
Received: from ORSEDG602.ED.cps.intel.com (10.7.248.7) by
 orsmsx602.amr.corp.intel.com (10.22.229.15) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2507.27 via Frontend Transport; Tue, 29 Aug 2023 03:10:41 -0700
Received: from NAM02-DM3-obe.outbound.protection.outlook.com (104.47.56.45) by
 edgegateway.intel.com (134.134.137.103) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id
 15.1.2507.27; Tue, 29 Aug 2023 03:10:40 -0700
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none;
 b=FaoAJXMW+2EzGFqwpHVjJtVROi0sqWbchtZaAU4nNIEtWkEydP5n45FqsoB9zI9mJyYjQG7ciyWwTt/jo6akgL6Vd4DZSPBJGXK3c0I7i0st0mUFfeR2oGohFat9II36zXewr1q3upMKMyzn5NiibHmzOqT8iYSPGMzym4bwdY9da43gxgbfX7CqGCduT/kY15SSjPtZHcpFKgYvlVfQtLvUzT+fRIuNuZ1W3JbMfyDSdj5+Nl1lw6RzhQmJG2WaHiobL74jDt7S1O7kiUmFwPPMqWrVp8zzeQI3fk8qIWZwd3CTdQ/RbT94QVOegPkS9ThznU44b9k4JeHevNX/1g==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; 
 s=arcselector9901;
 h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;
 bh=YrTRuCBnU2G0b50mTtCEgIjd/TKvIDQ+gXJFugXVgFA=;
 b=FhwR6/7vE0rR1QuHccf8ic96/tVCXwILHdofkWmX/lNehRXdqM0lax8wsccToaFlZa5MVLs6TL7Xrw3NSRXFhUifAN2w7NP/SQnn30+M7skAKgO4lHL09wKjxxLOJLL8cmDSu/sGdWmZv4ZzhMPbezNPD9Zcwp5coa6Q+brlO+yoRKxJ65Xu+PQjFzpvolcGyuXWVbB+f3lj8e1RrsWj7z3Aq1QA5gu1MN36VBZHZ3LMNHGISgtI1EAb01tmLRU1bIV5rTKxhhu2jamZph5ujlfnGU21IsG/iyX0fitCgkfU7VfQm5FBXfOYlmGtook3WUsuOLC9AH3ncZd45OaTUQ==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass
 smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com;
 dkim=pass header.d=intel.com; arc=none
Authentication-Results: dkim=none (message not signed)
 header.d=none;dmarc=none action=none header.from=intel.com;
Received: from DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17)
 by CYXPR11MB8710.namprd11.prod.outlook.com (2603:10b6:930:da::15) with
 Microsoft SMTP Server (version=TLS1_2,
 cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6699.35; Tue, 29 Aug
 2023 10:10:38 +0000
Received: from DS0PR11MB7309.namprd11.prod.outlook.com
 ([fe80::43d1:af60:464:347]) by DS0PR11MB7309.namprd11.prod.outlook.com
 ([fe80::43d1:af60:464:347%5]) with mapi id 15.20.6699.034; Tue, 29 Aug 2023
 10:10:38 +0000
Date: Tue, 29 Aug 2023 11:10:32 +0100
From: Bruce Richardson <bruce.richardson@intel.com>
To: Thomas Monjalon <thomas@monjalon.net>
CC: <dev@dpdk.org>, David Marchand <david.marchand@redhat.com>
Subject: Re: [PATCH v3] doc: build manpages as well as html output
Message-ID: <ZO3EGF09duMi9X1s@bricha3-MOBL.ger.corp.intel.com>
References: <20230601153801.118616-1-bruce.richardson@intel.com>
 <20230803164400.98873-1-bruce.richardson@intel.com>
 <4029524.5fSG56mABF@thomas>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <4029524.5fSG56mABF@thomas>
X-ClientProxiedBy: DUZPR01CA0133.eurprd01.prod.exchangelabs.com
 (2603:10a6:10:4bc::28) To DS0PR11MB7309.namprd11.prod.outlook.com
 (2603:10b6:8:13e::17)
MIME-Version: 1.0
X-MS-PublicTrafficType: Email
X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|CYXPR11MB8710:EE_
X-MS-Office365-Filtering-Correlation-Id: 6e606c61-3a37-4a80-29e4-08dba8783188
X-MS-Exchange-SenderADCheck: 1
X-MS-Exchange-AntiSpam-Relay: 0
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: mJQm+ZFXHzpGPuhnOxbKajlAhS1uMWVQnugWgK5VIx9DLQt6cPJmUhVkeDGKieN3BXyNODv4W9rb0qi3aenDDslweyR5LPvdjg+YAwczi+MSc7KV5dFKJIkSGvFSlZnnhFgjjL23ZapGH0CejidWUAjF5B7kuXfy9adl89K3MaHTpXDNTdmuJpnnODMbU5EXMd2lctHbVhMxgcJBjHyRJFLxE4CiImr+eU5kq6hyt6jGGUZyMKzFXVyprffaHo9yZo7A9zk3VrZRDL0xgc5FSMBGun9z1OYxd851ViT+vZ610nfzbraVGbuMJt/bW9FOnGpDIE6BRC3NgjLvsAsLWtyNYY+a2xFa6EGGZFnFAa+uia8VqjOew+u2l+vU0oV3pRsMrxymHyokNNVcb2SZtg1KtBs4h4HEacclsTLRyMPs9kezOtEloQHTBORibrGq/a7/TtdJUbzEOmAjkJGGVAapdVICq7EXLDT7ryJ7WtGwTKTHU/MDsCzoqLrS/tQJ/bhz60CDmlJTZrrdIQPTa8CZMFoNXw/yP1o7mqXTRqR3BjMyNvHFJtJ+UvcnY7Oj
X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:;
 IPV:NLI; SFV:NSPM; H:DS0PR11MB7309.namprd11.prod.outlook.com; PTR:; CAT:NONE;
 SFS:(13230031)(39860400002)(366004)(346002)(396003)(376002)(136003)(1800799009)(451199024)(186009)(6512007)(38100700002)(316002)(6916009)(41300700001)(82960400001)(4326008)(2906002)(83380400001)(86362001)(26005)(5660300002)(44832011)(8676002)(8936002)(6666004)(6506007)(6486002)(66556008)(66476007)(66946007)(478600001);
 DIR:OUT; SFP:1102; 
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?81kov2OovC/uaqpGcj1iq/8L5g5wer+JsHI6YIvmH4O+PUFWRMma8tsMgWcX?=
 =?us-ascii?Q?GQJLCCkzKOYFgZ7y/a3QhqamrVX0e+AuR1WNdVl3R53W4EMkQ08TLl+ouDw+?=
 =?us-ascii?Q?3OOAsjjweVccqlOS4smB2H7oi03XS/nY1DrygYUqTDOd3aTTCxzLxpZvnpcd?=
 =?us-ascii?Q?zMQsGETc4Wr/rvi9x2sqYPgM2zblsMe/PTDUmgNTfPaCNzVqMAjKMyUYdfO7?=
 =?us-ascii?Q?Rz/YC4XuVmwgnFcJ/7j6Uv5/n/61C3BryMu9vmq/8YnH8mkdLe16U8TJ4Npn?=
 =?us-ascii?Q?8J0rI0e1RinB20iJEb6ro0HyeMu2aacDxxGVtdd62DyXNicMz0oQfIlgO+Bo?=
 =?us-ascii?Q?H56uvwhJskFY9B7FDYuIlOaFYBkXrbp9SY1tDH5WlfSX9xqs2irgJLFwDDC4?=
 =?us-ascii?Q?m5ICgzTI2nIy42q2+YhFhr+6cbIjAtX8lIbdZMjvM9d2mUIBOjJLT0+ul096?=
 =?us-ascii?Q?KkswRFN6VhpjufDLnx9jKzJr/FotpJF84Oo5praEbSo3oaez0zD83GndAS+I?=
 =?us-ascii?Q?2uoRhuuYOpQCpTUGL3L8EH57eD/O7EQpo4c4+1UMNGJHwEz6/eoAyuqUxbKz?=
 =?us-ascii?Q?XcglNnQMPRhwNrv6WYK6P+cPUqA+rsebaB4GnsLcp6AgqR7DuxP1BnTfNNse?=
 =?us-ascii?Q?FMEPRkSdEUHssOu3UOeToFSBOYeqw4nBbLWe+O/mpMCnbe27g/JNgZzpVWpk?=
 =?us-ascii?Q?7Ejrz366GX7VbA8IjRlobPJU7pdnhnL+/QPN03YkHQFgblfB+2D/Sql3+ZD2?=
 =?us-ascii?Q?DBsT2hSR/s0qQqSLqi/xFp7yGMkGGWuUAiltYS4BaY/YWb2ZGM4ONfqQEYQd?=
 =?us-ascii?Q?DqnGUhwuImwzjDG7+yNjaUEa8fKUtO21tiZbeW382paahJOS7vDJJKX/dOlZ?=
 =?us-ascii?Q?3e3SgaNXjqMxGcTVFtL/RsIhAFbAcyBZPv/o9e4yJzPP0Eq3pSqsJETvGjiB?=
 =?us-ascii?Q?yvC6gWMqWdPa5I6tBknqeb6vKwAY98T/vY1TraOfXbCvkGydEZQQ8NIT/laR?=
 =?us-ascii?Q?hKwBIY0HtZGPSkJYSIjY0szAK7vQjD5z2IIbIIpfB6ImtvT5Gnb/TjJ0qe8R?=
 =?us-ascii?Q?rUzqZXaCAWE6fEYijb5LGkDlXeXhCGVlsZxGrwHapuUSFtf4QaDrRC69Sp9B?=
 =?us-ascii?Q?jxuTHxiH8bjq0VULNGq48DEjJyHT0yIbpU3hniR9LyeKJBk1u112cZcAlewr?=
 =?us-ascii?Q?OqK+6CM69rWJX2ofuJmoAsO8+6es0fftR6FogLM8UUnwNFk4RLhZvS6CwlQX?=
 =?us-ascii?Q?y1fXHnjMIvb4yL+27wIefARDayWLTMcrwE3CLHTY7mGKR5gGXfJfcQMaGQ2G?=
 =?us-ascii?Q?L+rQeQ0STsbZWICRuJNbBF4oY9wma8j/SmMMUclT9QrCVPJqhdNxUBIO8t9c?=
 =?us-ascii?Q?O+5umtZ5swaKFz/2loB1MQGuT0GWZ1w289jhqVU/H0mBJxplvtnnVEhH48VE?=
 =?us-ascii?Q?MBxJc+fNmFbPHkNPcVLU0G/P3Cxq6mEESR09eAHknrsAVKSRhOW5+JjbfBxb?=
 =?us-ascii?Q?qtAMOWxxKrpvg4NF0HH5lOzsmc3+WjO0RnFBhJjEszQtbaJQOREcny/pc+Gt?=
 =?us-ascii?Q?6xJ+dF9Ib7SpIP+kuund93AeZ40QXMk+hV2WbkNEBfk96zLWBoUfCeqiuFQb?=
 =?us-ascii?Q?7Q=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 6e606c61-3a37-4a80-29e4-08dba8783188
X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 29 Aug 2023 10:10:38.6093 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: YgW3c0h1HU/PwboZW6eSlQmkdJCtZ3ayLypXNLG5tq+3XtixAngXuZWLlK+81puBJ2tF9Pgk5eVeBuCdQgdkwKDiKiu1mHhpA+T3MqRZsNQ=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CYXPR11MB8710
X-OriginatorOrg: intel.com
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org

On Tue, Aug 29, 2023 at 11:28:01AM +0200, Thomas Monjalon wrote:
> 3/08/2023, Bruce Richardson:
> > +#set up common doxygen configuration
> 
> A space is missing here
> 
Ack

> > +man_cdata.set('FULL_PATH_NAMES', 'NO')
> 
> Why it has to be disabled? Maybe add a comment?
> 

Sure, will add comment. It's so that the man pages don't include
full paths to the headers, but are just e.g. "rte_eal.h".

> > +    meson.add_install_script(mandb)
> 
> When is it executed exactly?
> Will it update the database in case we install in a staging directory,
> when preparing a package for later deploying on another machine?

Yes, it will. Unfortunately, I can't find any way to just call mandb if we
are installing in a system manpage location on the local machine. Therefore,
I had two options:
1. don't update the manpage database. In this case, the user won't be able to
actually get the newly install manpages
2. always update the local manpage database. In this case, the user
installing the docs will find them, but anyone installing to staging will
experience a slight delay while their local mandb is updated.

I went for #2 on the basis that the delay in the staging case is pretty
harmless, while not actually finding the manpages is more serious.

However, I'm open to other suggestions on how to work this?

> 
> > +.. code-block:: console
> > +
> > +    export MANPATH=:/path/to/build/doc/api/man
> 
> Styling consideration: I think we should indent with 3 spaces
> so it is aligned with "code-block".
> 
Ack.