From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id EE1143858D20 for ; Wed, 15 Nov 2023 22:50:57 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org EE1143858D20 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org EE1143858D20 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1700088659; cv=none; b=Du5Wn5cl9ypd09Onaie8TLw/J9ikUqV2Cc/iCcQxTjdhTFBpsVs/G9hgpbEz7Gy4xYfnrbIDmUUJHdzpGjmGWRqCq1Wb/G89Bg+RjTc0dUfR6DYspc5flhQUjJE1h0WE0NQMOZnhz7LQbDIjYT8jQi1Q+wF6dHAwWpHDl+ImHOk= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1700088659; c=relaxed/simple; bh=GXat5rHkLriKjg0PN7cLB0E+OQFO5HgIR1yxMKLc6HM=; h=DKIM-Signature:Message-ID:Subject:From:To:Date:MIME-Version; b=Sj2Tcm34xCANf86+LbRcGetpdd354eYQWKgnAbMadqOhRIHCSjqc8ADlIdODaY144ybBR3/wLAXXP1wsQtdgf35RZ6O7KGjyHQt7B8hZwJQz07DJh9gZTkgwufJKv/mQYTzf2CC9d3HKAFLEO/j/5DW2yrCb08DprT8piqDrG0M= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1700088657; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=GS+4AUtIzehET8TygPHBnfrlgN98jSCXP0DUcPBdtxU=; b=jRtK61fYGPKbF/RAx26hl4Rs0BkjE8EzJlcdLCcdJEDcvb3fsVMbOqryqZsfdqzjwxMfiW lCMJkow/+P5fx9/1WmWMJ72gYHTOHKE/Clh3aaIhdu88oIEAScMVQyYoFcMV98gC8yyPLP 439M0eocRL+IjgwlBqEz2y9E6wXuiEs= Received: from mail-qk1-f200.google.com (mail-qk1-f200.google.com [209.85.222.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-688-ghmG0asYNfma9ddiHATiJA-1; Wed, 15 Nov 2023 17:50:56 -0500 X-MC-Unique: ghmG0asYNfma9ddiHATiJA-1 Received: by mail-qk1-f200.google.com with SMTP id af79cd13be357-7788ea971caso13040885a.2 for ; Wed, 15 Nov 2023 14:50:56 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700088655; x=1700693455; h=mime-version:user-agent:content-transfer-encoding:references :in-reply-to:date:cc:to:from:subject:message-id:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=GS+4AUtIzehET8TygPHBnfrlgN98jSCXP0DUcPBdtxU=; b=UnQO5SW72Q6tLzmHU5jaSvRU/YaReggFwvv51YE/PJ3t+JI+0bGARNjf/7IUqlu2yA m3dGSpM/+qK6Dao/VQvzpkYoi6o2zftQu3vDjBB+WyvO3VvTFclescyepeDoTu1CMk9b bMxYtRPCDhSFN0zntQit2CmwxMGW70nAaUkX/9mvwAOtIR+KE/cSQg7xeG7SIEZRNmXl wRQUIjhjlOSWV8gd5rSnOW8ivE1euqxdvNawKvR9kuvsOkv/Z6DAu/ww+wuJ6ObrrKqY H2Hpaobkfl3qNv6JppG3Vi9Jw7ya4ICsu2qvBaGc7m1vkIC6MRi4r3b1yWOt3LHmIJSL XSCg== X-Gm-Message-State: AOJu0YywcfYhxpieAyW7sMMFN7ccrUYFBBzKHMYSBYkBPPzgPHHRk3PA KXJaaogKcQpfCofF1LGmddmZM1sOMwG8Vc4prJvYDqYRlu6K1OypeWnS+dX3p3o3rxADkJJglwb +gnVQynyOtk/IzJGWjx/vLbPt+Q== X-Received: by 2002:a05:620a:3705:b0:773:af69:e614 with SMTP id de5-20020a05620a370500b00773af69e614mr8337996qkb.58.1700088655203; Wed, 15 Nov 2023 14:50:55 -0800 (PST) X-Google-Smtp-Source: AGHT+IHcxCfZnJEDpVApjXJ4AiH08hSmoVo2y6DII7lPfMkG4BNOycZz0ZloX8R7SHofhmmmDENz9A== X-Received: by 2002:a05:620a:3705:b0:773:af69:e614 with SMTP id de5-20020a05620a370500b00773af69e614mr8337985qkb.58.1700088654831; Wed, 15 Nov 2023 14:50:54 -0800 (PST) Received: from t14s.localdomain (c-76-28-97-5.hsd1.ma.comcast.net. [76.28.97.5]) by smtp.gmail.com with ESMTPSA id px24-20020a05620a871800b0077a7d02cffbsm3814347qkn.24.2023.11.15.14.50.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 15 Nov 2023 14:50:54 -0800 (PST) Message-ID: Subject: Re: [PATCH 0/3] Option handling: add documentation URLs From: David Malcolm To: Joseph Myers Cc: gcc-patches@gcc.gnu.org Date: Wed, 15 Nov 2023 17:50:52 -0500 In-Reply-To: References: <20231110214246.3087291-1-dmalcolm@redhat.com> User-Agent: Evolution 3.44.4 (3.44.4-2.fc36) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-11.3 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,KAM_SHORT,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: On Tue, 2023-11-14 at 00:12 +0000, Joseph Myers wrote: > On Fri, 10 Nov 2023, David Malcolm wrote: >=20 > > The .opt.urls files it generates become part of the source tree, > > and > > would be regenerated by maintainers whenever new options are added. > > Forgetting to update the files (or not having Python 3 handy) > > merely > > means that URLs might be missing or out of date until someone else > > regenerates them. >=20 > Do I understand correctly that there are no makefile targets to > regenerate=20 > these files; it's up to maintainers to regenerate them manually? >=20 > Advantages: >=20 > * No need to update contrib/gcc_update to handle timestamps for the > files. >=20 > * No modifications unexpectedly appearing in source trees, if the > checked=20 > in files are out of date and you run a build with the timestamps such > that=20 > the file gets regenerated. The .opt.urls are generated from the generated HTML. I think this needs to be a manually-triggered process, otherwise the optionlist depends on the generated HTML, and thus the generated HTML would become a hard early dependency during the build (which I don't think we would want). >=20 > Disadvantages: >=20 > * You need to know how to do the regeneration manually; "make" is the > uniform way for generating any file the build system can generate, > without=20 > needing more specific knowledge about that file. In the patches I posted I merely listed the commands in a comment in the script, but I'm currently working on adding support for options from the gdc and gfortran docs, and in doing so found that running the script with the correct options was a pain. So to make it easier, I'm currently thinking of adding this convenience target, so that when a maintainer does decide to regenerate the .opt.urls, they can simply type "make regenerate-opt-urls" in the gcc build subdir: diff --git a/gcc/Makefile.in b/gcc/Makefile.in index c3ed960b8f3c..6d24b7b9db34 100644 --- a/gcc/Makefile.in +++ b/gcc/Makefile.in @@ -3616,6 +3616,12 @@ $(build_htmldir)/gccinstall/index.html: $(TEXI_GCCIN= STALL_FILES) DESTDIR=3D$(@D) \ $(SHELL) $(srcdir)/doc/install.texi2html =20 +# Regenerate the .opt.urls files from the generated html, and from the .op= t +# files. +.PHONY: regenerate-opt-urls +regenerate-opt-urls: + $(srcdir)/regenerate-opt-urls.py $(build_htmldir) $(shell dirname $= (srcdir)) + MANFILES =3D doc/gcov.1 doc/cpp.1 doc/gcc.1 doc/gfdl.7 doc/gpl.7 \ doc/fsf-funding.7 doc/gcov-tool.1 doc/gcov-dump.1 \ $(if $(filter yes,@enable_lto@),doc/lto-dump.1) >=20 > Given the recent discussion starting at=20 > of=20 > post-commit CI to detect auto*-generated files that aren't fully up > to=20 > date, maybe it would be appropriate to add a check for .opt.urls > files=20 > being up to date (including making sure that each .opt file does have > a=20 > corresponding .opt.urls file checked in) to that CI? >=20 > Since the Python script has hardcoded information about .opt files > and=20 > corresponding URLs for target options documentation, the patch series > should update sourcebuild.texi, section "Back End", to identify that=20 > script as one of the places to update when adding a new target back > end. Thanks, will do. As mentioned, I'm currently investigating capturing per-language option URLs (to address Iain's and Marc's comments about D and Ada); if I get that working, I may need to add a similar note for adding a new frontend. Hope the overall approach seems reasonable. Dave