From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-lf1-f53.google.com (mail-lf1-f53.google.com [209.85.167.53]) by sourceware.org (Postfix) with ESMTPS id 9F8DD388A41D; Wed, 2 Jun 2021 16:05:56 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 9F8DD388A41D Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=rtems.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-lf1-f53.google.com with SMTP id a2so4186961lfc.9; Wed, 02 Jun 2021 09:05:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:reply-to :from:date:message-id:subject:to:cc; bh=Vmz12SL+YAqmalGk/ZZjR8yb3iicGozJn2ahFPz+kXM=; b=Jcej5Z2fOOfKF79LNNCOKjbs19Tw9//f1sC6dqdeF7te4DEJZyN0OwxKuwS9c2/Rr8 uxtEWOMfg7vIKmayUtNO15LFVVxRKn34Wp0zViqzjTVeAFjS/FazKRsFE8W39qYUMYy2 sCqAYMnAOHRaU48UC6kNS0VFDlnC9vonCP72DmOdJl0nShkYQEA6Yd4yMuYUaQ3Mdkhw KthoxkBVGvVJQS0SWHgfxTwFNMSM+t6VNgsGmJ6gDyxiQ0hRxt0Tj1ezb3kqfdZUFlzu EpBgfmXJE5mEvAmULG6iPcWZl9+grozSA8i/2Bb7rXICDyIw25l8P7qwVESupJtA44jf 3YTg== X-Gm-Message-State: AOAM530DNDxqXfrJY/t6HXLHrvpxW6wVnmBsV45w9Vko96aVRcFqzhH1 +M8TE3Qqpto8GVejIFyTghgZ6KuYpYjNsQ== X-Google-Smtp-Source: ABdhPJwNW0XmwzTzfj1tbZU/Dy8OaCfhmlCvC3fWPHG1VIAgTNWqOoOo+vm4MrMG5oocE1ZDJr7WmQ== X-Received: by 2002:ac2:4c0e:: with SMTP id t14mr6720145lfq.555.1622649943699; Wed, 02 Jun 2021 09:05:43 -0700 (PDT) Received: from mail-lj1-f177.google.com (mail-lj1-f177.google.com. [209.85.208.177]) by smtp.gmail.com with ESMTPSA id y22sm31047lfa.145.2021.06.02.09.05.43 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 02 Jun 2021 09:05:43 -0700 (PDT) Received: by mail-lj1-f177.google.com with SMTP id o8so3328294ljp.0; Wed, 02 Jun 2021 09:05:43 -0700 (PDT) X-Received: by 2002:a2e:95d0:: with SMTP id y16mr11638653ljh.140.1622649942878; Wed, 02 Jun 2021 09:05:42 -0700 (PDT) MIME-Version: 1.0 References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> In-Reply-To: Reply-To: joel@rtems.org From: Joel Sherrill Date: Wed, 2 Jun 2021 11:05:31 -0500 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: GCC documentation: porting to Sphinx To: =?UTF-8?Q?Martin_Li=C5=A1ka?= Cc: Michael Matz , GCC Development , gcc-patches@gcc.gnu.org, "Joseph S. Myers" X-Spam-Status: No, score=-3031.2 required=5.0 tests=BAYES_00, FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS, HTML_MESSAGE, KAM_DMARC_STATUS, KAM_EU, KAM_INFOUSMEBIZ, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Content-Filtered-By: Mailman/MimeDel 2.1.29 X-BeenThere: gcc@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 02 Jun 2021 16:05:59 -0000 For RTEMS, we switched from texinfo to Sphinx and the dependency on Python3 for Sphinx has caused a bit of hassle. Is this going to be an issue for GCC? Also we rely on TexLive for PDF output and that's a bit of a pain to install. Tex was incorrectly packaged on some RHEL/CentOS versions. This ignores a couple of plugins we use that I don't expect GCC to use. It works great but the host dependencies are sometimes a pain. We've ended up writing host OS specific advice/howto's to address this. Any expectations on host pain versus the pretty painless texinfo? Thanks. --joel RTEMS On Wed, Jun 2, 2021 at 2:37 AM Martin Li=C5=A1ka wrote: > On 6/1/21 3:31 PM, Michael Matz wrote: > > Hello, > > > > On Tue, 1 Jun 2021, Martin Li=C5=A1ka wrote: > > > >> On 5/31/21 5:49 PM, Michael Matz wrote: > >>> Hello Martin, > >>> > >>> On Mon, 31 May 2021, Martin Li=C5=A1ka wrote: > >>> > >>>> I've made quite some progress with the porting of the documentation > and > >>>> I would like to present it to the community now: > >>>> https://splichal.eu/scripts/sphinx/ > >>>> Note the documentation is automatically ([1]) generated from > texinfo with > >>>> a > >>>> GitHub workflow ([2]). > >>> > >>> One other thing I was recently thinking about, in the Spinx vs. texin= fo > >>> discussion: locally available documentation browsable/searchable in > >>> terminal with info(1) (or equivalents). > >> > >> Yes, that's handy. > >> > >>> I think the above (i.e. generating .rst from the texinfo file) would > >>> immediately nullify all my worries. So, just to be extra sure: your > >>> proposal now is to generate the .rst files, and that .texinfo remains > >>> the maintained sources, right? > >> > >> No, .texinfo files will be gone. However, Sphinx can output to info > >> format: > >> > https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphi= nx-build-M > > > > I see, that's good to hear. > > > >> And I've just added the generated Info pages here: > >> https://splichal.eu/scripts/sphinx/ > > > > Okay, but there's something amiss, just compare a local gcc.info with > > that. The sphinx generated one seems to only contain command line > > options, but none of the other topics, in particular it seems to contai= n > > the "Invoking GCC" chapter (and only that) as top-level, and all other > > ones are missing (like "C implementation", "C++ implementation", "C > > extension", and so on). > > You are right, I reduced that to 'Invoking GCC', which is simply what 'ma= n > gcc' > presents. However, I moved that back to the entire GCC manual what you ca= n > see now in the info page. > > > > > Looking at gccint.info I also seem quite some confusion, it's unclear t= o > > me if content is missing or not. But e.g. the top-level structure has = a > > different order (a less logical one, this one is btw. shared with the > > order of the HTML generated docu, so it's probably specific to sphinx > > setup or such). > > Yes, the organization was bad and I fixed that. Now it's much better. > > Martin > > > > > Ignoring that missing content what is there right now does seem somewha= t > > acceptable for local use, though. > > > > > > Ciao, > > Michael. > > > >