From patchwork Fri Jan 27 00:18:28 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Arsen_Arsenovi=C4=87?= X-Patchwork-Id: 55440 Return-Path: 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 04896385B537 for ; Fri, 27 Jan 2023 00:32:55 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 04896385B537 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1674779575; bh=P2fEZkYHIwYVjIeIKRduHnOoyZEeIaIEdf7qgZFU4H0=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=e6e/lf+T0C3P3kgPLrIzXnngXA99nHP9+S8To9xtMmqElWnmm3YxTcXLLFHgPcXbC kojQmyo01cypY7NCyCYdvlVQUwLH2/fug8x8Nbu7zyGXx+OcsNwCEuNYUPyOvigB7P 2kNwnK06mLLw/X0GOZ58pP4vWOVoLfwPVkR7DkNU= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mout-p-202.mailbox.org (mout-p-202.mailbox.org [80.241.56.172]) by sourceware.org (Postfix) with ESMTPS id 8CA8D3858D20 for ; Fri, 27 Jan 2023 00:32:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 8CA8D3858D20 Received: from smtp2.mailbox.org (smtp2.mailbox.org [10.196.197.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-202.mailbox.org (Postfix) with ESMTPS id 4P2z6m1Nfqz9sR0; Fri, 27 Jan 2023 01:32:16 +0100 (CET) To: gcc-patches@gcc.gnu.org Cc: =?utf-8?q?Arsen_Arsenovi=C4=87?= Subject: [PATCH+wwwdocs 0/8] A small Texinfo refinement Date: Fri, 27 Jan 2023 01:18:28 +0100 Message-Id: MIME-Version: 1.0 X-Spam-Status: No, score=-4.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_INFOUSMEBIZ, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: =?utf-8?q?Arsen_Arsenovi=C4=87_via_Gcc-patches?= From: =?utf-8?q?Arsen_Arsenovi=C4=87?= Reply-To: =?utf-8?q?Arsen_Arsenovi=C4=87?= Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" Evening, This patchset includes the requisite changes to gcc-wwwdocs and gcc in order to produce hopefully more accessible and readable documentation. For optimal results, please install Texinfo from master (there's currently no release that includes the few patches I made, the changes in which this patchset exploit). This patchset consists of changes that are mostly mechanical, and came down to reordering @item and @XYZindex commands appropriately. Attached to a few commits are pieces of automation that helped the process. Note that some manuals were not consistent with the rest, specifically the Ada ones, and so the methods I used weren't applicable to them without producing massive amounts of unrelated changes. For the same reasons as the following paragraph, I have decided to defer those. I also started doing less mechanical changes, like the @defbuiltin stuff, but after going over extend.texi I've noticed many sections that'd need many kinds of slightly different rework, and likely would require inventing some new convention (for instance, the instruction-generating built-ins come to mind, there's currently precedent of documenting them as @example blocks that list them, but this skips indexing, breaks the flow on text on narrow screens, and is generally inconsistent with other builtins). I've decided to halt this effort for the current release cycle, based on how much time I'll have until the release. I am curious about why texinfo.tex was left out of date for so long. If there's some reason, please let me know, and I'll see what I can do to remedy the problem. From a quick look I presumed there's none and updated to the latest version. In the process, I also got rid of the @gol macro, that was used for conditionally terminating lines, as this appears to be working around a now-nonexistent bug (and it caused a build issue on the new texinfo version). Note, however, that I did not thoroughly test update_web_docs_git script, as it seems to make a lot of assumptions about the environment it's invoked in, and so, I couldn't replicate it. Instead, I tested the following: #!/bin/sh set -xe MANUALS="cpp cppinternals fastjar gcc gccgo gccint gcj gdc gfortran gfc-internals gnat_ugn gnat-style gnat_rm libgomp libitm libquadmath libiberty porting" for file in $MANUALS; do rm -rf "${file}.html" mkdir "${file}.html" texi="$(find /home/arsen/gcc/gcc -name "$file.texi" | head -n 1)" [ "$texi" ] || continue includes="-I /home/arsen/gcc/gcc/gcc/doc/include" includes="$includes -I /home/arsen/gcc/outstuff/include" if [ "$file" = gnat_ugn ]; then includes="$includes -I /home/arsen/gcc/gcc/gcc/ada" includes="$includes -I /home/arsen/gcc/gcc/gcc/ada/doc/gnat_ugn" fi makeinfo --html -o "${file}.html" $includes \ --css-ref="/~arsen/final/texinfo-manuals.css" \ -c TOP_NODE_UP_URL="/~arsen/final/" \ "$texi" makeinfo --pdf -o "${file}.pdf" $includes "$texi" makeinfo --dvi -o "${file}.dvi" $includes "$texi" makeinfo --info -o "${file}.info" $includes "$texi" done This appeared to produce decent results when I was searching for various parts I touched. The output of the script above is visible online: https://www.aarsen.me/~arsen/final/ This was built against the a8306872ffc91e8d9572a3feedaa125be3c5c1d0 commit in Texinfo. Thanks in advance, have a lovely night. === gcc.git === Arsen Arsenović (7): docs: Create Indices appendix docs: Reorder @opindex to be before corresponding options **/*.texi: Reorder index entries docs: Mechanically reorder item/index combos in extend.texi doc: Add @defbuiltin family of helpers, set documentlanguage Update texinfo.tex, remove the @gol macro/alias update_web_docs_git: Update CSS reference to new manual CSS gcc/d/gdc.texi | 144 +- gcc/d/implement-d.texi | 66 +- gcc/doc/cfg.texi | 12 +- gcc/doc/cpp.texi | 12 +- gcc/doc/cppdiropts.texi | 24 +- gcc/doc/cppenv.texi | 4 +- gcc/doc/cppopts.texi | 94 +- gcc/doc/cppwarnopts.texi | 14 +- gcc/doc/extend.texi | 2564 ++++---- gcc/doc/gcc.texi | 36 +- gcc/doc/generic.texi | 2 +- gcc/doc/implement-c.texi | 2 +- gcc/doc/include/gcc-common.texi | 26 +- gcc/doc/include/texinfo.tex | 7599 +++++++++++++-------- gcc/doc/install.texi | 6 +- gcc/doc/invoke.texi | 8420 ++++++++++++------------ gcc/doc/lto.texi | 8 +- gcc/doc/md.texi | 25 +- gcc/doc/rtl.texi | 8 +- gcc/doc/sourcebuild.texi | 4 - gcc/doc/tm.texi | 4 +- gcc/doc/trouble.texi | 8 +- gcc/fortran/intrinsic.texi | 722 +- gcc/fortran/invoke.texi | 394 +- gcc/go/gccgo.texi | 34 +- maintainer-scripts/update_web_docs_git | 2 +- 26 files changed, 11004 insertions(+), 9230 deletions(-) === gcc-wwwdocs.git === Arsen Arsenović (1): Add revised Texinfo manual CSS htdocs/texinfo-manuals.css | 129 +++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 htdocs/texinfo-manuals.css