From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) by sourceware.org (Postfix) with ESMTPS id A7CB13833005; Mon, 7 Jun 2021 13:28:31 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org A7CB13833005 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=suse.cz Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.cz Received: from imap.suse.de (imap-alt.suse-dmz.suse.de [192.168.254.47]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 847F91FDA1; Mon, 7 Jun 2021 13:28:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623072510; h=from:from:reply-to: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=9Vbsn/1c5qRQHTYXjf5MubC+ucHJ8wfg0OaWCi1UJnU=; b=jj426pLoiWLByQUY1DYFNChvPecXeab+jGDwAnM6pdT19JA5OgNoYnaJwjeLdBaa/7Xs6G MEsNkSOSS9ne6Mh9IE2n7J+NUWziEu1Pc3sPHRtiyzRdqkdoWQjtYunI4Fzc3C+1cHINIQ lngtju9Idw3vsW8Dct65p8PB/6w505k= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623072510; h=from:from:reply-to: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=9Vbsn/1c5qRQHTYXjf5MubC+ucHJ8wfg0OaWCi1UJnU=; b=STskcWTl9d1dyu2Qs3IeMF6PiaMaSOkD2imW1EWd8WonIb33+YeC6IVNRevVZMs+0Mnde3 u3zgsdSlRXDFjCAA== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 60E70118DD; Mon, 7 Jun 2021 13:28:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623072510; h=from:from:reply-to: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=9Vbsn/1c5qRQHTYXjf5MubC+ucHJ8wfg0OaWCi1UJnU=; b=jj426pLoiWLByQUY1DYFNChvPecXeab+jGDwAnM6pdT19JA5OgNoYnaJwjeLdBaa/7Xs6G MEsNkSOSS9ne6Mh9IE2n7J+NUWziEu1Pc3sPHRtiyzRdqkdoWQjtYunI4Fzc3C+1cHINIQ lngtju9Idw3vsW8Dct65p8PB/6w505k= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623072510; h=from:from:reply-to: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=9Vbsn/1c5qRQHTYXjf5MubC+ucHJ8wfg0OaWCi1UJnU=; b=STskcWTl9d1dyu2Qs3IeMF6PiaMaSOkD2imW1EWd8WonIb33+YeC6IVNRevVZMs+0Mnde3 u3zgsdSlRXDFjCAA== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id LSQ0Fv4evmDYIgAALh3uQQ (envelope-from ); Mon, 07 Jun 2021 13:28:30 +0000 Subject: Re: RFC: Sphinx for GCC documentation To: Tobias Burnus , gcc-patches@gcc.gnu.org Cc: GCC Development References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <7366de44-aece-e53a-42ca-65f59407ec04@codesourcery.com> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <72d8b103-7dab-2dec-066e-aab1f3b8d059@suse.cz> Date: Mon, 7 Jun 2021 15:28:30 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.10.2 MIME-Version: 1.0 In-Reply-To: <7366de44-aece-e53a-42ca-65f59407ec04@codesourcery.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-4.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, NICE_REPLY_A, 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 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: Mon, 07 Jun 2021 13:28:42 -0000 On 6/4/21 9:55 AM, Tobias Burnus wrote: > Hello, > > On 13.05.21 13:45, Martin Liška wrote: >> On 4/1/21 3:30 PM, Martin Liška wrote: >>> That said, I'm asking the GCC community for a green light before I >>> invest >>> more time on it? >> So far, I've received just a small feedback about the transition. In >> most cases positive. >> >> [1] https://splichal.eu/scripts/sphinx/ > Hi. > The HTML output looks quite nice. Thanks. > > What I observed: > > * Looking at >   https://splichal.eu/scripts/sphinx/gfortran/_build/html/intrinsic-procedures/access-checks-file-access-modes.html > why is the first argument description in bold? > It is also not very readable to have a scollbar there – linebreaks would be better. > → I think that's because the assumption is that the first line contains a header >   and the rest the data I've converted the problematic table to '.. function::' directive that has :returns: and :param: arguments. Hope the output is fine now? > > * https://splichal.eu/scripts/sphinx/gfortran/_build/latex/gfortran.pdf >   If I look at page 92 (alias 96), 8.2.13 _gfortran_caf_sendget, the first column >   is too small to fit the argument names. – Admittedly, the current gfortran.pdf >   is not much better – it is very tight but just fits. I don't know how to fix this. This is also converted and should look much better. > > * I note that we write before the argument index, that those are without -/-- prefix >   but that's not true. Something to fix after the conversation. Can you please show me a few examples of it? > > * The syntax highlighting for gfortran is odd. Looking at @smallexample: > - intrinsic.texi: All Fortran examples (F90/free-form) > - gfc-internals.texi: 4x Fortran, 4x C, 3x plain text > - gfortran.texi: Shell, Fortran, C, plain text. > - invoke.texi: 4x Shell, 2x C, 4x Fortran Should be fixed now as I set 'fortran' code-block in the fortran manual. Right now, there are few warnings that a code block is C/C++, but that's quite a small fallout. > Does not seem to be that simple, but it would be nice if at least all in > intrinsic.texi would be marked as Fortran. Should be better now? > > Actually, I do not quite understand when the output is formatted a C (wrongly > or rightly) as Fortran (rarely but correctly) as plain or in some odd formatting > which randomly highlights some examples. We make quests based on keyworks in a code-block and we also consider texinfo filename. > Possibly also an item for after the conversion. Sure, there are still some warnings that can be seen with 'make html' (or other target). Thanks for review, Martin > > Tobias > > ----------------- > Mentor Graphics (Deutschland) GmbH, Arnulfstrasse 201, 80634 München Registergericht München HRB 106955, Geschäftsführer: Thomas Heurung, Frank Thürauf