Message ID | 20211101235703.112341-1-sandra@codesourcery.com |
---|---|
Headers |
Return-Path: <gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org> X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 68C723858018 for <patchwork@sourceware.org>; Mon, 1 Nov 2021 23:57:43 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa2.mentor.iphmx.com (esa2.mentor.iphmx.com [68.232.141.98]) by sourceware.org (Postfix) with ESMTPS id C4FE93858403; Mon, 1 Nov 2021 23:57:26 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C4FE93858403 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com IronPort-SDR: 7ZDULT6rlT3UIHZ2e2uzHEL/VNc1WMbYcxrLWUdjbtG8cXQXFCxrT0leBP3LFP4oBjD/35y66p W9lzIhhSUEa5G5KxN7nAM5JyJH7KpXwOuOJjsYFG5rHbdJuX4D5wlVgrsq5SrdKUQ6PzYFHsv+ o5OuB8Lhjv3sKpWvKh5LNtmP7UG0wfMCyW92Hgp5S6gaWRkBzSXBa9i8tEdBiLnylSKVz2lh/O guOwTSTMEGpvw43ijNqbJUsJdrdZb9gxui+qbNz/FJUrhgDAKungO/Vt+qp7er/H81hplE8Z3o H/Vuoe/2WtuECK0IJCKXe0ki X-IronPort-AV: E=Sophos;i="5.87,201,1631606400"; d="scan'208";a="67917978" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa2.mentor.iphmx.com with ESMTP; 01 Nov 2021 15:57:25 -0800 IronPort-SDR: Lbj7iUmtyTUcrNxMRWyegmZAsRS7c4ZrpcN6FpMne+oWEaPnXTMs7APXcSpTdsr89V44HJoQiU Ajl5ryRnjCeih9+yiUixBzyLSnD48hsuMqYpu4MY4D98jJcUjzgNarR6SzeL83Z9aayxKlJewd DEH7M8jtH1ybPP2xH5pqeyNctIuyzKBO58x1OBp/zhqgZt3pkkkI1euVoibvPWH5jM/2frL+P6 xnMzGfp3fwxxoxTiPG9HaENpyz6h6leyRwU/rS9LMsavusjwFXacJMAN3cMvI9avHuYea9s2VI OHU= From: Sandra Loosemore <sandra@codesourcery.com> To: <fortran@gcc.gnu.org>, <gcc-patches@gcc.gnu.org> Subject: [PATCH 0/5] Fortran manual updates Date: Mon, 1 Nov 2021 17:56:58 -0600 Message-ID: <20211101235703.112341-1-sandra@codesourcery.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-ClientProxiedBy: SVR-ORW-MBX-09.mgc.mentorg.com (147.34.90.209) To svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) X-Spam-Status: No, score=-3.9 required=5.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list <gcc-patches.gcc.gnu.org> List-Unsubscribe: <https://gcc.gnu.org/mailman/options/gcc-patches>, <mailto:gcc-patches-request@gcc.gnu.org?subject=unsubscribe> List-Archive: <https://gcc.gnu.org/pipermail/gcc-patches/> List-Post: <mailto:gcc-patches@gcc.gnu.org> List-Help: <mailto:gcc-patches-request@gcc.gnu.org?subject=help> List-Subscribe: <https://gcc.gnu.org/mailman/listinfo/gcc-patches>, <mailto:gcc-patches-request@gcc.gnu.org?subject=subscribe> Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" <gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org> |
Series | Fortran manual updates | |
Message
Sandra Loosemore
Nov. 1, 2021, 11:56 p.m. UTC
This series of patches addresses some areas of bit-rot in the GNU Fortran manual, mainly relating to the state of standard compliance and the recently-completed TS29113 work. I also removed some material that is primarily of historical interest; given that gfortran replaced g77 almost 17 years ago now, relatively few users will be interested in why or how they differ any more, for instance. And I don't see the point in the manual documenting extensions that aren't actually implemented. I also fixed some organization and copy-editing issues I noticed while working on the relevant sections, although that wasn't my primary purpose in this patch set. The whole manual needs a lot more of that, but with documentation it's fine to do incremental improvements. I'll wait a couple days before committing these patches, in case anybody wants to give some feedback, especially on technical issues. -Sandra Sandra Loosemore (5): Fortran manual: Combine standard conformance docs in one place. Fortran manual: Revise introductory chapter. Fortran manual: Update section on Interoperability with C Fortran manual: Update miscellaneous references to old standard versions. Fortran manual: Remove old docs for never-implemented extensions. gcc/fortran/gfortran.texi | 985 +++++++++++---------------------------------- gcc/fortran/intrinsic.texi | 15 +- gcc/fortran/invoke.texi | 48 ++- 3 files changed, 288 insertions(+), 760 deletions(-)
Comments
On 11/2/21 00:56, Sandra Loosemore wrote: > I'll wait a couple days before committing these patches, in case > anybody wants to give some feedback, especially on technical issues. Hello. Appreciate the work you did, but the patchset will cause quite some conflicts in the prepared Sphinx migration patch I've sent to the mailing list :/ Anyway, I will rebase my patches. For the future, are you planning doing similar documentation reorganization for a manual? Based on discussion with Gerald, I hope we can finish the transition before the end of this year. Thank you, Martin
On 11/2/21 2:51 AM, Martin Liška wrote: > On 11/2/21 00:56, Sandra Loosemore wrote: >> I'll wait a couple days before committing these patches, in case >> anybody wants to give some feedback, especially on technical issues. > > Hello. > > Appreciate the work you did, but the patchset will cause quite some > conflicts > in the prepared Sphinx migration patch I've sent to the mailing list :/ > Anyway, I will rebase my patches. For the future, are you planning doing > similar > documentation reorganization for a manual? Based on discussion with > Gerald, I hope > we can finish the transition before the end of this year. My understanding was that, if this conversion is indeed going to happen, it's going to be automated by scripts? I hadn't seen any discussion of it on the list for months and thought the whole idea was on hold or scrapped, since it hasn't happened yet. In any case it does not seem reasonable to freeze the current Texinfo docs for months while waiting for it to happen, especially as we are heading into the end of the release cycle and people are finishing up changes and new features they need to document. -Sandra
On 11/2/21 15:48, Sandra Loosemore wrote: > On 11/2/21 2:51 AM, Martin Liška wrote: >> On 11/2/21 00:56, Sandra Loosemore wrote: >>> I'll wait a couple days before committing these patches, in case >>> anybody wants to give some feedback, especially on technical issues. >> >> Hello. >> >> Appreciate the work you did, but the patchset will cause quite some conflicts >> in the prepared Sphinx migration patch I've sent to the mailing list :/ >> Anyway, I will rebase my patches. For the future, are you planning doing similar >> documentation reorganization for a manual? Based on discussion with Gerald, I hope >> we can finish the transition before the end of this year. > > My understanding was that, if this conversion is indeed going to happen, it's going to be automated by scripts? Exactly, but the conversion needs some manual post-processing that I've already done. > I hadn't seen any discussion of it on the list for months and thought the whole idea was on hold or scrapped, since it hasn't happened yet. There was almost no response, so that's why I contacted Gerald about help. > In any case it does not seem reasonable to freeze the current Texinfo docs for months while waiting for it to happen, especially as we are heading into the end of the release cycle and people are finishing up changes and new features they need to document. Sure, I can easily rebase normal changes, but you are suggesting a complete redesign/renaming. It's going to take me some time, but I'll rebase my patches. Thanks for understanding, Martin > > -Sandra
On 11/2/21 9:20 AM, Martin Liška wrote: > On 11/2/21 15:48, Sandra Loosemore wrote: >> On 11/2/21 2:51 AM, Martin Liška wrote: >>> On 11/2/21 00:56, Sandra Loosemore wrote: >>>> I'll wait a couple days before committing these patches, in case >>>> anybody wants to give some feedback, especially on technical issues. >>> >>> Hello. >>> >>> Appreciate the work you did, but the patchset will cause quite some >>> conflicts >>> in the prepared Sphinx migration patch I've sent to the mailing list :/ >>> Anyway, I will rebase my patches. For the future, are you planning >>> doing similar >>> documentation reorganization for a manual? Based on discussion with >>> Gerald, I hope >>> we can finish the transition before the end of this year. >> >> My understanding was that, if this conversion is indeed going to >> happen, it's going to be automated by scripts? > > Exactly, but the conversion needs some manual post-processing that I've > already done. > >> I hadn't seen any discussion of it on the list for months and >> thought the whole idea was on hold or scrapped, since it hasn't >> happened yet. > > There was almost no response, so that's why I contacted Gerald about help. I have to admit that I was buried in technical work at the time of the previous discussion (in fact, the Fortran things I am now trying to document), and didn't have time to look at the proposed changes in any detail. I have wondered, though, why it's necessary to do this change.... if people don't like the way Texinfo formats output, can't we fix Texinfo? Or hack it to translate the sources to something like DocBook instead, and then adopt that as our source format? I can write documentation in any markup format, but it seems to me that structured XML-based formats are a lot more amenable to scripted manipulation than either Texinfo or restructured text. If the rest of the community is set on Sphinx, I'm fine with that, but I kind of don't see the point, myself. :-S >> In any case it does not seem reasonable to freeze the current Texinfo >> docs for months while waiting for it to happen, especially as we are >> heading into the end of the release cycle and people are finishing up >> changes and new features they need to document. > > Sure, I can easily rebase normal changes, but you are suggesting a > complete redesign/renaming. It's going to take me some time, > but I'll rebase my patches. Well, what I've done is hardly a "complete" redesign/renaming of the Fortran manual -- I've barely scratched the surface on it. My main goal was just to update the bit-rotten standards conformance sections, which were unfortunately spread among multiple places in the document. I did consolidate those few sections, but I did not make any big-picture changes to the organization of the manual, and I have not even reviewed any other parts of it for accuracy or relevance. I'd been thinking about making a pass to do some copy-editing things, like making sure all chapter/section titles use consistent title case capitalization, but I will hold off on that if it's going to cause problems. -Sandra
On Tue, Nov 2, 2021 at 8:56 AM Sandra Loosemore <sandra@codesourcery.com> wrote: > > ... I will hold off on that if it's going to cause problems. > > Thanks for taking on this task, Sandra. I'm not aware of the technical issues around mark-up formatting and the transition that's happening, but I hope nothing holds up a long-needed update to the standards conformance information. Those are really important references that I've seen people rely upon in decision-making that impacts projects. Damian
On 11/2/21 16:56, Sandra Loosemore wrote: > On 11/2/21 9:20 AM, Martin Liška wrote: >> On 11/2/21 15:48, Sandra Loosemore wrote: >>> On 11/2/21 2:51 AM, Martin Liška wrote: >>>> On 11/2/21 00:56, Sandra Loosemore wrote: >>>>> I'll wait a couple days before committing these patches, in case >>>>> anybody wants to give some feedback, especially on technical issues. >>>> >>>> Hello. >>>> >>>> Appreciate the work you did, but the patchset will cause quite some conflicts >>>> in the prepared Sphinx migration patch I've sent to the mailing list :/ >>>> Anyway, I will rebase my patches. For the future, are you planning doing similar >>>> documentation reorganization for a manual? Based on discussion with Gerald, I hope >>>> we can finish the transition before the end of this year. >>> >>> My understanding was that, if this conversion is indeed going to happen, it's going to be automated by scripts? >> >> Exactly, but the conversion needs some manual post-processing that I've already done. >> >>> I hadn't seen any discussion of it on the list for months and thought the whole idea was on hold or scrapped, since it hasn't happened yet. >> >> There was almost no response, so that's why I contacted Gerald about help. > > I have to admit that I was buried in technical work at the time of the previous discussion (in fact, the Fortran things I am now trying to document), and didn't have time to look at the proposed changes in any detail. I have wondered, though, why it's necessary to do this change.... if people don't like the way Texinfo formats output, can't we fix Texinfo? That's a reasonable question. Well, I believe the technical dept (feature set) of Texinfo (compared to more modern tools) is significant and I don't want to spend my time hacking a HTML, Javascipt and so on. Moreover, Sphinx is massively used: https://www.sphinx-doc.org/en/master/examples.html and the tool is actively developed. > Or hack it to translate the sources to something like DocBook instead, and then adopt that as our source format? I can write documentation in any markup format, but it seems to me that structured XML-based formats are a lot more amenable to scripted manipulation than either Texinfo or restructured text. If the rest of the community is set on Sphinx, I'm fine with that, but I kind of don't see the point, myself. :-S We think with David that DocBook is too complicated and a markup is a better choice (from that perspective, Texinfo is fine). > >>> In any case it does not seem reasonable to freeze the current Texinfo docs for months while waiting for it to happen, especially as we are heading into the end of the release cycle and people are finishing up changes and new features they need to document. >> >> Sure, I can easily rebase normal changes, but you are suggesting a complete redesign/renaming. It's going to take me some time, >> but I'll rebase my patches. > > Well, what I've done is hardly a "complete" redesign/renaming of the Fortran manual -- I've barely scratched the surface on it. My main goal was just to update the bit-rotten standards conformance sections, which were unfortunately spread among multiple places in the document. I did consolidate those few sections, but I did not make any big-picture changes to the organization of the manual, and I have not even reviewed any other parts of it for accuracy or relevance. I'd been thinking about making a pass to do some copy-editing things, like making sure all chapter/section titles use consistent title case capitalization, but I will hold off on that if it's going to cause problems. I see, thanks for doing that. Martin > > -Sandra
On Thu, Nov 4, 2021 at 11:05 AM Martin Liška <mliska@suse.cz> wrote: > > On 11/2/21 16:56, Sandra Loosemore wrote: > > On 11/2/21 9:20 AM, Martin Liška wrote: > >> On 11/2/21 15:48, Sandra Loosemore wrote: > >>> On 11/2/21 2:51 AM, Martin Liška wrote: > >>>> On 11/2/21 00:56, Sandra Loosemore wrote: > >>>>> I'll wait a couple days before committing these patches, in case > >>>>> anybody wants to give some feedback, especially on technical issues. > >>>> > >>>> Hello. > >>>> > >>>> Appreciate the work you did, but the patchset will cause quite some conflicts > >>>> in the prepared Sphinx migration patch I've sent to the mailing list :/ > >>>> Anyway, I will rebase my patches. For the future, are you planning doing similar > >>>> documentation reorganization for a manual? Based on discussion with Gerald, I hope > >>>> we can finish the transition before the end of this year. > >>> > >>> My understanding was that, if this conversion is indeed going to happen, it's going to be automated by scripts? > >> > >> Exactly, but the conversion needs some manual post-processing that I've already done. > >> > >>> I hadn't seen any discussion of it on the list for months and thought the whole idea was on hold or scrapped, since it hasn't happened yet. > >> > >> There was almost no response, so that's why I contacted Gerald about help. > > > > I have to admit that I was buried in technical work at the time of the previous discussion (in fact, the Fortran things I am now trying to document), and didn't have time to look at the proposed changes in any detail. I have wondered, though, why it's necessary to do this change.... if people don't like the way Texinfo formats output, can't we fix Texinfo? > > That's a reasonable question. Well, I believe the technical dept (feature set) of Texinfo (compared to more modern tools) is significant and I don't want > to spend my time hacking a HTML, Javascipt and so on. Moreover, Sphinx is massively used: https://www.sphinx-doc.org/en/master/examples.html > and the tool is actively developed. > > > > Or hack it to translate the sources to something like DocBook instead, and then adopt that as our source format? I can write documentation in any markup format, but it seems to me that structured XML-based formats are a lot more amenable to scripted manipulation than either Texinfo or restructured text. If the rest of the community is set on Sphinx, I'm fine with that, but I kind of don't see the point, myself. :-S > > We think with David that DocBook is too complicated and a markup is a better choice (from that perspective, Texinfo is fine). > > > > >>> In any case it does not seem reasonable to freeze the current Texinfo docs for months while waiting for it to happen, especially as we are heading into the end of the release cycle and people are finishing up changes and new features they need to document. > >> > >> Sure, I can easily rebase normal changes, but you are suggesting a complete redesign/renaming. It's going to take me some time, > >> but I'll rebase my patches. > > > > Well, what I've done is hardly a "complete" redesign/renaming of the Fortran manual -- I've barely scratched the surface on it. My main goal was just to update the bit-rotten standards conformance sections, which were unfortunately spread among multiple places in the document. I did consolidate those few sections, but I did not make any big-picture changes to the organization of the manual, and I have not even reviewed any other parts of it for accuracy or relevance. I'd been thinking about making a pass to do some copy-editing things, like making sure all chapter/section titles use consistent title case capitalization, but I will hold off on that if it's going to cause problems. > > I see, thanks for doing that. Sandra - please go forward with improving the manual with the current texinfo setup. There's zero reason to hold off on improving user level documentation. Thanks, Richard. > Martin > > > > > -Sandra >