Re: tree decl stored during LGEN does not map to a symtab_node during WPA

[Erick Ochoa via Gcc]

> I'm not too familiar with it but I think you're supposed to stream encoded
> symtab references during LGEN/WPA,

Thanks Richard, this happened to be the solution. I am now using
lto_symtab_encoder_t to encode the declarations during LGEN and decode
them during WPA.

Are there any more limitations of using stream_write_tree that one
should be aware of? Now I am looking into storing trees of the type
STRING_CST and I think this might be causing me a problem at WPA time.
I think it segfaults at the moment of creating the process, but I
still need more time to investigate. Perhaps you might know if storing
STRING_CST trees has to be handled in a special way? Not sure if it
also has something to do with LTO file sections. The tree is used to
initialize a global static variable.

Thanks!

Priority of builtins expansion strategies

[Christoph Müllner via Gcc]

Hi,

I'm working on some platform-specific optimizations for
memset/memcpy/strcpy/strncpy.
However, I am having difficulties understanding how my code should be
integrated.
Initially, I got inspired by rs6000-string.c, where I see expansion
code for instructions
like setmemsi or cmpstrsi. However, that expansion code is not always called.
Instead, the first strategy is using the generic by-pieces infrastructure.

To understand what I mean, let's have a look at memset
(expand_builtin_memset_args).
The backend can provide a tailored code sequence by expanding setmem.
However, there is also a generic solution available using the
by-pieces infrastructure.
The generic by-pieces infrastructure has a higher priority than the
target-specific setmem
expansion. However, the recently added by-multiple-pieces
infrastructure has lower priority
than setmem.

See:
https://gcc.gnu.org/git/?p=gcc.git;a=blob;f=gcc/builtins.c;h=39ab139b7e1c06c98d2db1aef2b3a6095ffbec63;hb=HEAD#l7004

The same observation is true for most (all?) other uses of builtins.

The current priority requires me to duplicate the condition code to
decide if my optimization
can be applied to the following places:
1) in TARGET_USE_BY_PIECES_INFRASTRUCTURE_P () to block by-pieces
2) in the setmem expansion to gate the optimization

As I would expect  that a target-specific mechanism is preferred over
a generic mechanism,
my questions are:
* Why does the generic by-pieces infrastructure have a higher priority
than the target-specific expansion via INSNs like setmem?
* And if there are no particular reasons, would it be acceptable to
change the order?

Thanks,
Christoph

Benefits of using Sphinx documentation format

[Martin Liška]

Hello.

Let's make it a separate sub-thread where we can discuss motivation why
do I want moving to Sphinx format.

Benefits:
1) modern looking HTML output (before: [1], after: [2]):
   a) syntax highlighting for examples (code, shell commands, etc.)
   b) precise anchors, the current Texinfo anchors are not displayed (start 
with first line of an option)
   c) one can easily copy a link to an anchor (displayed as ¶)
   d) internal links are working, e.g. one can easily jump from listing of 
options
   e) left menu navigation provides better orientation in the manual
   f) Sphinx provides internal search capability: [3]
2) internal links are also provided in PDF version of the manual
3) some existing GCC manuals are already written in Sphinx (GNAT manuals and 
libgccjit)
4) support for various output formats, some people are interested in ePUB format
5) Sphinx is using RST which is quite minimal semantic markup language
6) TOC is automatically generated - no need for manual navigation like seen 
here: [5]

Disadvantages:

1) info pages are currently missing Page description in TOC
2) rich formatting is leading to extra wrapping in info output - beings 
partially addresses in [4]
3) one needs e.g. Emacs support for inline links (rendered as notes)

I'm willing to address issue 1) in next weeks and I tend to skip emission of 
links as mentioned in 3).
Generally speaking, I'm aware that some people still use Info, but I think we 
should more focus
on more modern documentation formats. That's HTML (and partially PDF).

Martin

[1] 
https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing
[2] 
https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing
[3] 
https://splichal.eu/gccsphinx-final/html/gcc/search.html?q=-fipa-icf&check_keywords=yes&area=default#
[4] https://github.com/sphinx-doc/sphinx/pull/9391
[5] @comment node-name, next,  previous, up
@nodeInstalling GCC, Binaries, , Top

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> Cc: gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org, jos...@codesourcery.com
> From: Martin Liška 
> Date: Mon, 12 Jul 2021 15:25:47 +0200
> 
> Let's make it a separate sub-thread where we can discuss motivation why
> do I want moving to Sphinx format.

Thanks for starting this discussion.

> Benefits:
> 1) modern looking HTML output (before: [1], after: [2]):
> a) syntax highlighting for examples (code, shell commands, etc.)
> b) precise anchors, the current Texinfo anchors are not displayed (start 
> with first line of an option)
> c) one can easily copy a link to an anchor (displayed as ¶)
> d) internal links are working, e.g. one can easily jump from listing of 
> options
> e) left menu navigation provides better orientation in the manual
> f) Sphinx provides internal search capability: [3]
> 2) internal links are also provided in PDF version of the manual

How is this different from Texinfo?

> 3) some existing GCC manuals are already written in Sphinx (GNAT manuals and 
> libgccjit)
> 4) support for various output formats, some people are interested in ePUB 
> format

Texinfo likewise supports many output formats.  Someone presented a
very simple package to produce epub format from it.

> 5) Sphinx is using RST which is quite minimal semantic markup language

Is it more minimal than Texinfo?

> 6) TOC is automatically generated - no need for manual navigation like seen 
> here: [5]

That is not needed in Texinfo as well, since long ago.  Nowadays, you
just say

  @node Whatever

and the rest is done automatically, as long as the manual's structure
is a proper tree (which it normally is, I know of only one manual that
is an exception).

> Disadvantages:
> 
> 1) info pages are currently missing Page description in TOC
> 2) rich formatting is leading to extra wrapping in info output - beings 
> partially addresses in [4]
> 3) one needs e.g. Emacs support for inline links (rendered as notes)

 4) The need to learn yet another markup language.
While this is not a problem for simple text, it does require a
serious study of RST and Sphinx to use the more advanced features.

 5) Lack of macros.
AFAIK, only simple textual substitution is available, no macros
with arguments.

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 14:41, Eli Zaretskii via Gcc  wrote:
>
> > Cc: gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org, jos...@codesourcery.com
> > From: Martin Liška 
> > Date: Mon, 12 Jul 2021 15:25:47 +0200
> >
> > Let's make it a separate sub-thread where we can discuss motivation why
> > do I want moving to Sphinx format.
>
> Thanks for starting this discussion.
>
> > Benefits:
> > 1) modern looking HTML output (before: [1], after: [2]):
> > a) syntax highlighting for examples (code, shell commands, etc.)
> > b) precise anchors, the current Texinfo anchors are not displayed 
> > (start with first line of an option)
> > c) one can easily copy a link to an anchor (displayed as ¶)
> > d) internal links are working, e.g. one can easily jump from listing of 
> > options

For me, these items are enough justification to switch away from
texinfo, which produces crap HTML pages with crap anchors. You can't
find out the anchors without inspecting (and searching) the HTML
source. That's utterly stupid. And even after you do that, the anchor
is at the wrong place:
https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c
As somebody who spends a lot of time helping users on the mailing
list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
HTML has angered me for many years.

Yes, some people like texinfo, but some people also dislike it and
there are serious usability problems with the output. I support
replacing texinfo with anything that isn't texinfo.


> > e) left menu navigation provides better orientation in the manual
> > f) Sphinx provides internal search capability: [3]
> > 2) internal links are also provided in PDF version of the manual
>
> How is this different from Texinfo?
>
> > 3) some existing GCC manuals are already written in Sphinx (GNAT manuals 
> > and libgccjit)
> > 4) support for various output formats, some people are interested in ePUB 
> > format
>
> Texinfo likewise supports many output formats.  Someone presented a
> very simple package to produce epub format from it.
>
> > 5) Sphinx is using RST which is quite minimal semantic markup language
>
> Is it more minimal than Texinfo?
>
> > 6) TOC is automatically generated - no need for manual navigation like seen 
> > here: [5]
>
> That is not needed in Texinfo as well, since long ago.  Nowadays, you
> just say
>
>   @node Whatever
>
> and the rest is done automatically, as long as the manual's structure
> is a proper tree (which it normally is, I know of only one manual that
> is an exception).
>
> > Disadvantages:
> >
> > 1) info pages are currently missing Page description in TOC
> > 2) rich formatting is leading to extra wrapping in info output - beings 
> > partially addresses in [4]
> > 3) one needs e.g. Emacs support for inline links (rendered as notes)
>
>  4) The need to learn yet another markup language.
> While this is not a problem for simple text, it does require a
> serious study of RST and Sphinx to use the more advanced features.

This is a problem with texinfo too.

>
>  5) Lack of macros.
> AFAIK, only simple textual substitution is available, no macros
> with arguments.

Is this a problem for GCC docs though?

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 14:53, Jonathan Wakely wrote:
> For me, these items are enough justification to switch away from
> texinfo, which produces crap HTML pages with crap anchors. You can't
> find out the anchors without inspecting (and searching) the HTML
> source. That's utterly stupid. And even after you do that, the anchor
> is at the wrong place:
> https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c
> As somebody who spends a lot of time helping users on the mailing
> list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
> HTML has angered me for many years.

To be clear, I give links to users frequently (several times a week,
every week, for decades) and prefer to give them a link to specific
options. Obviously I link to the online HTML docs rather than telling
them an 'info' command to run, because most people don't use info
pages or know how to navigate them. That means I can't provide decent
links, because the actual option name I'm trying to link to is always
off the top of the page. This is simply unacceptable IMHO. Texinfo
must go.

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> From: Jonathan Wakely 
> Date: Mon, 12 Jul 2021 14:53:44 +0100
> Cc: Martin Liška , 
>   "gcc@gcc.gnu.org" , gcc-patches 
> , 
>   "Joseph S. Myers" 
> 
> For me, these items are enough justification to switch away from
> texinfo, which produces crap HTML pages with crap anchors.

If we want to have a serious discussion with useful conclusions, I
suggest to avoid "loaded" terminology.

I get it that you dislike the HTML produced by Texinfo, but without
some examples of such bad HTML it is impossible to know what exactly
do you dislike and why.

> You can't find out the anchors without inspecting (and searching)
> the HTML source. That's utterly stupid.

I don't think I follow: find out the anchors with which means and for
what purposes?

> And even after you do that, the anchor
> is at the wrong place:
> https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c

IME, the anchor is where you put it.  If you show me the source of
that HTMl, maybe we can have a more useful discussion of the issue.

> As somebody who spends a lot of time helping users on the mailing
> list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
> HTML has angered me for many years.

As somebody who spends a lot of time helping users on every possible
forum, and as someone who has wrote a lot of Texinfo, I don't
understand what angers you.  Please elaborate.

> Yes, some people like texinfo, but some people also dislike it and
> there are serious usability problems with the output. I support
> replacing texinfo with anything that isn't texinfo.

"Anything"?  Even plain text?  I hope not.

See, such "arguments" don't help to have a useful discussion.

> >  4) The need to learn yet another markup language.
> > While this is not a problem for simple text, it does require a
> > serious study of RST and Sphinx to use the more advanced features.
> 
> This is a problem with texinfo too.

Not for someone who already knows Texinfo.  We are talking about
switching away of it, so I'm thinking about people who contributed
patches for the manual in the past.  They already know Texinfo, at
least to some extent, and some of them know it very well.

> >  5) Lack of macros.
> > AFAIK, only simple textual substitution is available, no macros
> > with arguments.
> 
> Is this a problem for GCC docs though?

I don't know.  It could be, even if it isn't now.

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> From: Jonathan Wakely 
> Date: Mon, 12 Jul 2021 15:05:11 +0100
> Cc: Martin Liška , 
>   "gcc@gcc.gnu.org" , gcc-patches 
> , 
>   "Joseph S. Myers" 
> 
> To be clear, I give links to users frequently (several times a week,
> every week, for decades) and prefer to give them a link to specific
> options. Obviously I link to the online HTML docs rather than telling
> them an 'info' command to run, because most people don't use info
> pages or know how to navigate them. That means I can't provide decent
> links, because the actual option name I'm trying to link to is always
> off the top of the page. This is simply unacceptable IMHO. Texinfo
> must go.

"Texinfo must go" is one possible conclusion from your description.
But it isn't the only one.  An alternative is "the Texinfo source of
the GCC manual must be improved to fix this problem."  And yes, this
problem does have a solution in Texinfo.

Re: Benefits of using Sphinx documentation format

[Martin Liška]

On 7/12/21 4:12 PM, Eli Zaretskii wrote:

From: Jonathan Wakely 
Date: Mon, 12 Jul 2021 14:53:44 +0100
Cc: Martin Liška ,
"gcc@gcc.gnu.org" , gcc-patches 
,
"Joseph S. Myers" 

For me, these items are enough justification to switch away from
texinfo, which produces crap HTML pages with crap anchors.


If we want to have a serious discussion with useful conclusions, I
suggest to avoid "loaded" terminology.

I get it that you dislike the HTML produced by Texinfo, but without
some examples of such bad HTML it is impossible to know what exactly
do you dislike and why.


Please follow my 1) from Benefits and *read* bullet points a) to f). That will
give you an answer.




You can't find out the anchors without inspecting (and searching)
the HTML source. That's utterly stupid.


I don't think I follow: find out the anchors with which means and for
what purposes?


Benefits, 1c).




And even after you do that, the anchor
is at the wrong place:
https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c


IME, the anchor is where you put it.  If you show me the source of
that HTMl, maybe we can have a more useful discussion of the issue.


Problem is that Texinfo emits poor HTML where # link points to a wrong place.
Open the given page, view source and search for .




As somebody who spends a lot of time helping users on the mailing
list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
HTML has angered me for many years.


As somebody who spends a lot of time helping users on every possible
forum, and as someone who has wrote a lot of Texinfo, I don't
understand what angers you.  Please elaborate.


You can't point to an option documentation.




Yes, some people like texinfo, but some people also dislike it and
there are serious usability problems with the output. I support
replacing texinfo with anything that isn't texinfo.


"Anything"?  Even plain text?  I hope not.

See, such "arguments" don't help to have a useful discussion.


  4) The need to learn yet another markup language.
 While this is not a problem for simple text, it does require a
 serious study of RST and Sphinx to use the more advanced features.


This is a problem with texinfo too.


Not for someone who already knows Texinfo.  We are talking about
switching away of it, so I'm thinking about people who contributed
patches for the manual in the past.  They already know Texinfo, at
least to some extent, and some of them know it very well.


Yes, people will have to learn a new syntax. Similarly to transition of SVN,
people also had to learn with a more modern tool.




  5) Lack of macros.
 AFAIK, only simple textual substitution is available, no macros
 with arguments.


Is this a problem for GCC docs though?


I don't know.  It could be, even if it isn't now.


Then it's not an argument, sorry.

Martin

Re: Benefits of using Sphinx documentation format

[Martin Liška]

On 7/12/21 4:16 PM, Eli Zaretskii wrote:

From: Jonathan Wakely 
Date: Mon, 12 Jul 2021 15:05:11 +0100
Cc: Martin Liška ,
"gcc@gcc.gnu.org" , gcc-patches 
,
"Joseph S. Myers" 

To be clear, I give links to users frequently (several times a week,
every week, for decades) and prefer to give them a link to specific
options. Obviously I link to the online HTML docs rather than telling
them an 'info' command to run, because most people don't use info
pages or know how to navigate them. That means I can't provide decent
links, because the actual option name I'm trying to link to is always
off the top of the page. This is simply unacceptable IMHO. Texinfo
must go.


"Texinfo must go" is one possible conclusion from your description.
But it isn't the only one.  An alternative is "the Texinfo source of
the GCC manual must be improved to fix this problem."  And yes, this
problem does have a solution in Texinfo.


No, the alternative is more powerful output given by Texinfo, in particular
more modern HTML pages.

Martin

Re: Benefits of using Sphinx documentation format

[Martin Liška]

On 7/12/21 3:39 PM, Eli Zaretskii wrote:

Cc: gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org, jos...@codesourcery.com
From: Martin Liška 
Date: Mon, 12 Jul 2021 15:25:47 +0200

Let's make it a separate sub-thread where we can discuss motivation why
do I want moving to Sphinx format.


Thanks for starting this discussion.


Benefits:
1) modern looking HTML output (before: [1], after: [2]):
 a) syntax highlighting for examples (code, shell commands, etc.)
 b) precise anchors, the current Texinfo anchors are not displayed (start 
with first line of an option)
 c) one can easily copy a link to an anchor (displayed as ¶)
 d) internal links are working, e.g. one can easily jump from listing of 
options
 e) left menu navigation provides better orientation in the manual
 f) Sphinx provides internal search capability: [3]
2) internal links are also provided in PDF version of the manual


How is this different from Texinfo?


Texinfo does not emit them. See e.g. links in option listing (-O2, -Os, ...).




3) some existing GCC manuals are already written in Sphinx (GNAT manuals and 
libgccjit)
4) support for various output formats, some people are interested in ePUB format


Texinfo likewise supports many output formats.  Someone presented a
very simple package to produce epub format from it.


Good to know.




5) Sphinx is using RST which is quite minimal semantic markup language


Is it more minimal than Texinfo?


I would say that's pretty easy to learn, similarly complex as Texinfo.




6) TOC is automatically generated - no need for manual navigation like seen 
here: [5]


That is not needed in Texinfo as well, since long ago.  Nowadays, you
just say

   @node Whatever

and the rest is done automatically, as long as the manual's structure
is a proper tree (which it normally is, I know of only one manual that
is an exception).


All right, then we likely do an extra work right now.




Disadvantages:

1) info pages are currently missing Page description in TOC
2) rich formatting is leading to extra wrapping in info output - beings 
partially addresses in [4]
3) one needs e.g. Emacs support for inline links (rendered as notes)


  4) The need to learn yet another markup language.
 While this is not a problem for simple text, it does require a
 serious study of RST and Sphinx to use the more advanced features.


No, majority of the documentation is pretty simple: basic formatting, links, 
tables and
code examples.

Martin



  5) Lack of macros.
 AFAIK, only simple textual substitution is available, no macros
 with arguments.

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii  wrote:
>
> > From: Jonathan Wakely 
> > Date: Mon, 12 Jul 2021 14:53:44 +0100
> > Cc: Martin Liška ,
> >   "gcc@gcc.gnu.org" , gcc-patches 
> > ,
> >   "Joseph S. Myers" 
> >
> > For me, these items are enough justification to switch away from
> > texinfo, which produces crap HTML pages with crap anchors.
>
> If we want to have a serious discussion with useful conclusions, I
> suggest to avoid "loaded" terminology.

But the results *are* crap.

>
> I get it that you dislike the HTML produced by Texinfo, but without
> some examples of such bad HTML it is impossible to know what exactly
> do you dislike and why.
>
> > You can't find out the anchors without inspecting (and searching)
> > the HTML source. That's utterly stupid.
>
> I don't think I follow: find out the anchors with which means and for
> what purposes?

I want to point a user at the documentation for the -c option. I can't
do that without examining the HTML source to find the anchor, then
manually editing the URL to append the anchor. It's a tedious process,
and the result is an anchor that doesn't even point to the option but
to the text following it. The process is unnecessarily difficult and
the results are bad.

You participated in a discussion about this very topic previously:
https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg0.html

>
> > And even after you do that, the anchor
> > is at the wrong place:
> > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c
>
> IME, the anchor is where you put it.  If you show me the source of
> that HTMl, maybe we can have a more useful discussion of the issue.

@item -c
@opindex c
Compile or assemble the source files, but do not link.  The linking
stage simply is not done.  The ultimate output is in the form of an
object file for each source file.

Putting the @opindex before the @item causes the anchor to be placed
on the previous item, which is not desirable.


>
> > As somebody who spends a lot of time helping users on the mailing
> > list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
> > HTML has angered me for many years.
>
> As somebody who spends a lot of time helping users on every possible
> forum, and as someone who has wrote a lot of Texinfo, I don't
> understand what angers you.  Please elaborate.

I don't know what part of my email you don't understand. The HTML
anchors that texinfo creates are in the wrong place, and not
"discoverable". If you don't understand that, then you're clearly not
using the GCC HTML docs, and so I'm not surprised you think there's no
reason to ditch texinfo. As a regular user of the HTML (for myself and
end users of GCC), the HTML output has major usability problems.


> > Yes, some people like texinfo, but some people also dislike it and
> > there are serious usability problems with the output. I support
> > replacing texinfo with anything that isn't texinfo.
>
> "Anything"?  Even plain text?  I hope not.

Plain text with a tool to generate good HTML might be better than texinfo.

> See, such "arguments" don't help to have a useful discussion.

Your insistence that texinfo is fine doesn't either. It's not fine.

> > >  4) The need to learn yet another markup language.
> > > While this is not a problem for simple text, it does require a
> > > serious study of RST and Sphinx to use the more advanced features.
> >
> > This is a problem with texinfo too.
>
> Not for someone who already knows Texinfo.  We are talking about
> switching away of it, so I'm thinking about people who contributed
> patches for the manual in the past.  They already know Texinfo, at
> least to some extent, and some of them know it very well.

I've contributed dozens of patches to the manual, and I don't want to
have to use texinfo to do it in future.

> > >  5) Lack of macros.
> > > AFAIK, only simple textual substitution is available, no macros
> > > with arguments.
> >
> > Is this a problem for GCC docs though?
>
> I don't know.  It could be, even if it isn't now.

So not a problem then.

Re: Benefits of using Sphinx documentation format

[Matthias Kretz]

Hi.

I'm commenting as a long-time GCC user and reader of the manual (never via 
info reader, mostly via DuckDuckGo / Google -> HTML docs) who recently started 
contributing more than just PRs.

On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote:
> On 7/12/21 4:12 PM, Eli Zaretskii wrote:
> > I get it that you dislike the HTML produced by Texinfo, but without
> > some examples of such bad HTML it is impossible to know what exactly
> > do you dislike and why.

I believe Martin made a really good list.

But FWIW, when I reach the GCC HTML docs it's like a blast from the past. It 
looks more or less exactly like web pages looked in the 90ies. To me, that 
gives GCC an image of an old and sluggishly moving project. And to me that's a 
high priority issue.
I have to size down the browser window so that line lengths are bearable. I 
have to scroll to the top/bottom of the page for navigation. Navigating 
through the tree of pages requires you to learn how it works; it's not 
intuitive at all.

If the decision for how to write and read documentation places 'info' in 
higher priority than HTML then that would emphasize "the image of an old and 
sluggishly moving project" even more than the sight of the HTML pages. Who is 
the target audience?

> >>>   4) The need to learn yet another markup language.
> >>>   
> >>>  While this is not a problem for simple text, it does require a
> >>>  serious study of RST and Sphinx to use the more advanced features.
> >> 
> >> This is a problem with texinfo too.
> > 
> > Not for someone who already knows Texinfo.  We are talking about
> > switching away of it, so I'm thinking about people who contributed
> > patches for the manual in the past.  They already know Texinfo, at
> > least to some extent, and some of them know it very well.
> 
> Yes, people will have to learn a new syntax. Similarly to transition of SVN,
> people also had to learn with a more modern tool.

Same issue. Is the goal to accommodate only seasoned GNU contributors? 
Basically everyone nowadays knows and uses Markdown. RST is not far from that. 
So it opens up the project for way more people to contribute. I wrote 
documentation patches recently. I found it really awkward to write. Markup 
languages have gotten better and I really hope we can move on!

> >>>   5) Lack of macros.
> >>>   
> >>>  AFAIK, only simple textual substitution is available, no macros
> >>>  with arguments.

I don't recall for sure, but I think I did that with RST at some point.

Best,
  Matthias

-- 
──
 Dr. Matthias Kretz   https://mattkretz.github.io
 GSI Helmholtz Centre for Heavy Ion Research   https://gsi.de
 std::experimental::simd  https://github.com/VcDevel/std-simd
──

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 15:52, Jonathan Wakely  wrote:
>
> On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii  wrote:
> >
> > > From: Jonathan Wakely 
> > > This is a problem with texinfo too.
> >
> > Not for someone who already knows Texinfo.  We are talking about
> > switching away of it, so I'm thinking about people who contributed
> > patches for the manual in the past.  They already know Texinfo, at
> > least to some extent, and some of them know it very well.
>
> I've contributed dozens of patches to the manual, and I don't want to
> have to use texinfo to do it in future.

And some of the people already know sphinx, and some know it very
well. And it seems likely that future contributors are more likely to
know a more modern tool than they are to know texinfo.

You like texinfo. We get it.

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 15:52, Jonathan Wakely  wrote:
>
> On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii  wrote:
> > I get it that you dislike the HTML produced by Texinfo, but without
> > some examples of such bad HTML it is impossible to know what exactly
> > do you dislike and why.
> >
> > > You can't find out the anchors without inspecting (and searching)
> > > the HTML source. That's utterly stupid.
> >
> > I don't think I follow: find out the anchors with which means and for
> > what purposes?
>
> I want to point a user at the documentation for the -c option. I can't
> do that without examining the HTML source to find the anchor, then
> manually editing the URL to append the anchor. It's a tedious process,
> and the result is an anchor that doesn't even point to the option but
> to the text following it. The process is unnecessarily difficult and
> the results are bad.
>
> You participated in a discussion about this very topic previously:
> https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg0.html
>
> >
> > > And even after you do that, the anchor
> > > is at the wrong place:
> > > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c
> >
> > IME, the anchor is where you put it.  If you show me the source of
> > that HTMl, maybe we can have a more useful discussion of the issue.
>
> @item -c
> @opindex c
> Compile or assemble the source files, but do not link.  The linking
> stage simply is not done.  The ultimate output is in the form of an
> object file for each source file.
>
> Putting the @opindex before the @item causes the anchor to be placed
> on the previous item, which is not desirable.

GNU Hello has the same problem with its docs:
https://www.gnu.org/software/hello/manual/hello.html#index-_002dg
That URL is garbage because of the URL-encoded %2d character, and the
fact it links to the wrong place (the description of the option, not
the option itself). The former is no longer an issue for GCC (it was
for many years) but the latter is still a problem.

If you don't know where to find it yourself, the source is visible here:
https://github.com/yugui/example/blob/master/doc/hello.texi#L208

If GNU Hello and GCC can't get this right using texinfo, maybe texinfo
is not fit for purpose?

Re: Benefits of using Sphinx documentation format

[Gavin Smith via Gcc]

On Mon, Jul 12, 2021 at 4:04 PM Jonathan Wakely via Gcc  wrote:
> GNU Hello has the same problem with its docs:
> https://www.gnu.org/software/hello/manual/hello.html#index-_002dg
> That URL is garbage because of the URL-encoded %2d character, and the
> fact it links to the wrong place (the description of the option, not
> the option itself). The former is no longer an issue for GCC (it was
> for many years) but the latter is still a problem.
>
> If you don't know where to find it yourself, the source is visible here:
> https://github.com/yugui/example/blob/master/doc/hello.texi#L208

I downloaded the source for the "hello" manual and recreated it with
Texinfo 6.8 (running " texi2any --html hello.texi --no-split"). I've
attached the results. The current output doesn't exhibit the problem
with the scrolling being at the wrong place - this problem has
evidently resolved itself since the time when the online "hello"
manual was generated. (I don't remember many complaints about it on
the mailing list, though: if we don't know about problems, we can't
fix them.)

The URL is mangled because index entries can have more characters in
them than what is suitable for a URL. A space character becomes a "-",
so a "-" has to become something else. They have to be distinguished
because there may be two separate index entries in different places
which wouldn't be distinguishable otherwise.

However, I find that adding an extra index entry means you can use
hello.html#index-greeting instead:

@item --greeting=@var{text}
@itemx -g @var{text}
@opindex greeting
@opindex --greeting
@opindex -g
Output @var{text} instead of the default greeting.

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 17:01, Gavin Smith wrote:
>
> On Mon, Jul 12, 2021 at 4:04 PM Jonathan Wakely via Gcc  
> wrote:
> > GNU Hello has the same problem with its docs:
> > https://www.gnu.org/software/hello/manual/hello.html#index-_002dg
> > That URL is garbage because of the URL-encoded %2d character, and the
> > fact it links to the wrong place (the description of the option, not
> > the option itself). The former is no longer an issue for GCC (it was
> > for many years) but the latter is still a problem.
> >
> > If you don't know where to find it yourself, the source is visible here:
> > https://github.com/yugui/example/blob/master/doc/hello.texi#L208
>
> I downloaded the source for the "hello" manual and recreated it with
> Texinfo 6.8 (running " texi2any --html hello.texi --no-split"). I've
> attached the results. The current output doesn't exhibit the problem
> with the scrolling being at the wrong place - this problem has
> evidently resolved itself since the time when the online "hello"
> manual was generated. (I don't remember many complaints about it on
> the mailing list, though: if we don't know about problems, we can't
> fix them.)

The "copyable link" does work as I would expect. The #index-_002dg
anchor still seems to be in the "wrong" place, i.e. in the 
element not the  element. But the addition of the copyable link
nicely solves the problem of needing to easily obtain a link to the
right position.

> The URL is mangled because index entries can have more characters in
> them than what is suitable for a URL. A space character becomes a "-",
> so a "-" has to become something else.

Yes, I understand the reason.

Re: Benefits of using Sphinx documentation format

[David Malcolm via Gcc]

On Mon, 2021-07-12 at 15:25 +0200, Martin Liška wrote:
> Hello.
> 
> Let's make it a separate sub-thread where we can discuss motivation
> why
> do I want moving to Sphinx format.
> 
> Benefits:
> 1) modern looking HTML output (before: [1], after: [2]):

"modern looking" is rather subjective; I'd rate Sphinx's output as
looking like it's from 2010s (last decade), whereas Texinfos' looks
like it's from the 1990s.  In theory this ought not to matter, but
every time I look at our documentation it gives me a depressing
feeling, reminiscent of a graveyard, that discourages me from fixing
things.

>     a) syntax highlighting for examples (code, shell commands, etc.)

...with support for multiple programming languages, potentially on the
same page.  For example, in the libgccjit docs:
  https://gcc.gnu.org/onlinedocs/jit/intro/tutorial02.html
we can have a mixture of C, assembler and shell on one page, and each
example is syntax-highlighted accordingly.  It's not clear to me how to
do that in texinfo, since there needs to be a way to express what
language an example is in.

>     b) precise anchors, the current Texinfo anchors are not displayed
> (start with first line of an option)

...and the URLs are sane and stable (so e.g. there is a reliable,
guessable, readable URL for the docs for say, "-Wall").

>     c) one can easily copy a link to an anchor (displayed as ¶)
>     d) internal links are working, e.g. one can easily jump from
> listing of options
>     e) left menu navigation provides better orientation in the manual
>     f) Sphinx provides internal search capability: [3]

...also (quoting myself in places here from 2015
  https://gcc.gnu.org/pipermail/gcc-patches/2015-November/434055.html 
):

* the ability to include fragments of files: libgccjit's documentation
uses directives to include code from the test suite, so that all of the
code examples are also part of the test suite, and are thus known to
compile), allowing for (almost) literate programming.  [That said, the
build of libgccjit's docs on gcc.gnu.org seems to be missing those
fragments; I wonder if there's a path or version issue?]

* a page-splitting structure that make sense, to me, at least (I have
never fathomed the way texinfo's navigation works, for HTML, at least,
and I believe I'm not the only one; I generally pick the all-in-one-
HTML-page option when viewing texinfo-html docs and do textual
searches, since otherwise I usually can't find the thing I'm looking
for (or have to resort to a brute-force depth-first search of clicking
through the links).)

* much more use of markup, with restrained and well-chosen CSS
(texinfo's HTML seems to ignore much of the inline markup in
the .texinfo file)

> 2) internal links are also provided in PDF version of the manual
> 3) some existing GCC manuals are already written in Sphinx (GNAT
> manuals and libgccjit)
> 4) support for various output formats, some people are interested in
> ePUB format
> 5) Sphinx is using RST which is quite minimal semantic markup language

Sphinx is also used by many high-profile FLOSS projects (e.g. the Linux
kernel, LLVM, and the Python community), so it reduces the barrier to
entry for new contributors, relative to texinfo.


> 6) TOC is automatically generated - no need for manual navigation
> like seen here: [5]
> 
> Disadvantages:
> 
> 1) info pages are currently missing Page description in TOC
> 2) rich formatting is leading to extra wrapping in info output -
> beings partially addresses in [4]
> 3) one needs e.g. Emacs support for inline links (rendered as notes)
> 
> I'm willing to address issue 1) in next weeks and I tend to skip
> emission of links as mentioned in 3).
> Generally speaking, I'm aware that some people still use Info, but I
> think we should more focus
> on more modern documentation formats. That's HTML (and partially
> PDF).

I think the output formats we need to support are:
- HTML
- PDF
- man page (hardly "modern", but still used)

I regared "info" as merely "nice to have" - I don't know anyone who
uses it other than some core GNU contributors.

Dave

> 
> Martin
> 
> [1]
> https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing
> [2]
> https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing
> [3]
> https://splichal.eu/gccsphinx-final/html/gcc/search.html?q=-fipa-icf&check_keywords=yes&area=default#
> [4] https://github.com/sphinx-doc/sphinx/pull/9391
> [5] @comment node-name, next,  previous, up
>  @node    Installing GCC, Binaries, , Top
> 

Re: daily report on extending static analyzer project [GSoC]

[Ankur Saini via Gcc]

> 
> On 11-Jul-2021, at 11:19 PM, David Malcolm  wrote:
> 
> On Sat, 2021-07-10 at 21:27 +0530, Ankur Saini wrote:
>> AIM for today : 
>> 
>> - update the call_string to store a vector of pair of supernode*
>> instead of pointer to it 
>> - create a typdef to give a meaning full name to these " pair of
>> supernode* “
>> - send the patch list to gcc-patches mailing list
>> - add the example program I created to the GCC tests
>> 
>> —
>> 
>> PROGRESS :
>> 
>> - I successfully changed the entire call string representation again to
>> keep track of "auto_vec m_elements;” from "auto_vec> std::pair*> m_supernodes;” 
>> 
>> - while doing so, one hurdle I found was to change "hashval_t hash ()
>> const;”, function of which I quite didn’t understood properly, but
>> looking at source, it looked like it just needed some value ( integer
>> or pointer ) to add to ‘hstate’ and ' m_elements’ was neither a pointer
>> nor an integer so I instead added pointer to callee supernode (
>> “second” of the m_elements ) to the ‘hstate’ for now. 
>> 
>> - for the callstring patch, I created a patch file ( using git format-
>> patch ) and sent it to patches mailing list (via git send email ) and
>> CCed my mentor.
>> Although I received a positive reply from the command log (git send
>> email) saying the mail was sent , I didn’t received that mail ( being
>> subscribed to the patches list ) regarding the same ( I sent that just
>> before sending this mail ).
>> The mail should be sent from arse...@sourceware.org 
>>  > arse...@sourceware.org > 
> 
> Thanks.
> 
> I see the patch email in the list archives here:
>  https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574888.html 
> 
> but for some reason it's not showing up in my inbox.  I'm not sure why;
> I recently got migrated to a new email server and my filters are
> currently a mess so it could be a problem at my end; sorry if that's
> the case.
> 
> Given that neither you nor I seem to have received the patch I wonder
> if anyone else received it?

Then I think it’s better to attach patch file with the updates here instead.

> 
> Given that, I'm going to reply to that patch email inline here (by
> copying and pasting it from the archive):
> 
>> [PATCH 1/2] analyzer: refactor callstring to work with pairs of supernodes 
>> [GSoC]
>> 
>> 2021-07-3  Ankur Saini  > >
> 
> There are some formatting rules that we follow with ChangeLog entries.
> We have a script:
> 
>  ./contrib/gcc-changelog/git_check_commit.py --help

Ok, I will keep in mind to double check with it from now on.

> 
> that you can run to check the formatting.
> 
>>* gcc/analyzer/call-string.cc : refactor 
>> callstring to work with pair of supernodes instead of super superedges
>>* gcc/analyzer/call-string.h: make callstring work with pairs of 
>> supernodes
>>* gcc/analyzer/program-point.cc : refactor 
>> program point to work with new call-string format
> 
> The "gcc/analyzer" directory has its own ChangeLog file, and filenames
> should be expressed relative to it, so these entries should read
> something like:
> 
> gcc/analyzer/ChangeLog:
>   * call-string.cc : ...etc
>   * call-string.h: ...etc
>   * program-point.cc : ...etc
> 
> The entries should be sentences (i.e. initial capital letter and
> trailing full-stop).
> 
> They should be line-wrapped (I do it at 74 columns), giving this:
> 
> gcc/analyzer/ChangeLog:
>   * call-string.cc : Refactor callstring to work 
> with pair of
>   supernodes instead of superedges.
>   * call-string.h: Make callstring work with pairs of supernodes.
>   * program-point.cc : Refactor program point 
> to work with new
>   call-string format.
> 
> Your text editor might have a mode for working with ChangeLog files.

Yes, there is a way to wrap text after certain number of columns in my text 
editor, I would be using that from now on when working with changelogs.

> 
>   [...snip...]
> 
>> @@ -152,22 +152,40 @@ call_string::push_call (const supergraph &sg,
>>   gcc_assert (call_sedge);
>>   const return_superedge *return_sedge = call_sedge->get_edge_for_return 
>> (sg);
>>   gcc_assert (return_sedge);
>> -  m_return_edges.safe_push (return_sedge);
>> +  const std::pair *e = new 
>> (std::pair)
> 
> We don't want lines wider than 80 columns unless it can't be helped. 
> Does your text editor have a feature to warn you about overlong lines?
> 
> Changing from:
>  std::pair
> to:
>  element_t
> should make it much easier to avoid overlong lines.
> 
> [...snip...]
> 
>> diff --git a/gcc/analyzer/call-string.h b/gcc/analyzer/call-string.h
>> index 7721571ed60..0134d185b90 100644
>> --- a/gcc/analyzer/call-string.h
>> +++ b

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> From: Matthias Kretz 
> Date: Mon, 12 Jul 2021 16:54:50 +0200
> 
> On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote:
> > On 7/12/21 4:12 PM, Eli Zaretskii wrote:
> > > I get it that you dislike the HTML produced by Texinfo, but without
> > > some examples of such bad HTML it is impossible to know what exactly
> > > do you dislike and why.
> 
> I believe Martin made a really good list.

Gavin Smith, the GNU Texinfo maintainer, responded in detail to that
list.  However, his message didn't get through to the list, for some
reason.  Can someone please see why, and release his message?  I think
he makes some important points, and his message does deserve being
posted and read as part of this discussion.

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> Cc: gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org, jos...@codesourcery.com
> From: Martin Liška 
> Date: Mon, 12 Jul 2021 16:34:11 +0200
> 
> > "Texinfo must go" is one possible conclusion from your description.
> > But it isn't the only one.  An alternative is "the Texinfo source of
> > the GCC manual must be improved to fix this problem."  And yes, this
> > problem does have a solution in Texinfo.
> 
> No, the alternative is more powerful output given by Texinfo, in particular
> more modern HTML pages.

Please see the response by Gavin: it sounds like at least some of that
was resolved in Texinfo, sometimes long ago.

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> Cc: h...@bitrange.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org,
>  jos...@codesourcery.com
> From: Martin Liška 
> Date: Mon, 12 Jul 2021 16:37:00 +0200
> 
> >   4) The need to learn yet another markup language.
> >  While this is not a problem for simple text, it does require a
> >  serious study of RST and Sphinx to use the more advanced features.
> 
> No, majority of the documentation is pretty simple: basic formatting, links, 
> tables and
> code examples.

We also have documentation of APIs (a.k.a. "functions").  I actually
tried to find in the Sphinx docs how to do that and got lost.  So, not
really "very simple".

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> From: Jonathan Wakely 
> Date: Mon, 12 Jul 2021 15:54:49 +0100
> Cc: Martin Liška , 
>   "gcc@gcc.gnu.org" , gcc-patches 
> , 
>   "Joseph S. Myers" 
> 
> You like texinfo. We get it.

Would you please drop the attitude?

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 18:04, Eli Zaretskii via Gcc  wrote:
>
> > From: Matthias Kretz 
> > Date: Mon, 12 Jul 2021 16:54:50 +0200
> >
> > On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote:
> > > On 7/12/21 4:12 PM, Eli Zaretskii wrote:
> > > > I get it that you dislike the HTML produced by Texinfo, but without
> > > > some examples of such bad HTML it is impossible to know what exactly
> > > > do you dislike and why.
> >
> > I believe Martin made a really good list.
>
> Gavin Smith, the GNU Texinfo maintainer, responded in detail to that
> list.  However, his message didn't get through to the list, for some
> reason.

It did:
https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html
https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html

The HTML attachment has been stripped though. The relevant part of the
HTML looks like this:

--greeting=text
¶
-g text

Output text instead of the default greeting.



Note the  ¶  anchor that is part of the  element,
not the  (where the index-__002d anchor is still located).


>  Can someone please see why, and release his message?  I think
> he makes some important points, and his message does deserve being
> posted and read as part of this discussion.

He shows that some of the linking issues are addressed in the latest
texinfo release, which is great. But it doesn't negate all Martin's
other points.

GCC devs and users who frequently modify or refer to the HTML docs
want to replace texinfo. One vocal objector who just keeps repeating
that texinfo is fine should not block that progress.

Re: [PATCH] Port GCC documentation to Sphinx

[Martin Sebor via Gcc]

On 6/29/21 4:09 AM, Martin Liška wrote:

On 6/28/21 5:33 PM, Joseph Myers wrote:

Are formatted manuals (HTML, PDF, man, info) corresponding to this patch
version also available for review?


I've just uploaded them here:
https://splichal.eu/gccsphinx-final/

Martin



I think listing the -Wfoo and -Wno-foo (and analogously the -fbar
and -fno-bar) options is an improvement over prior revisions but when
the positive form is the default the text reads funny.  For example:

  -fno-inline

  Do not expand any functions inline apart from those marked
  with the always_inline attribute. This is the default when
  not optimizing.

  Single functions can be exempted from inlining by marking
  them with the noinline attribute.

  -finline

  Default option value for -fno-inline.


I.e., -finline is not what I would describe as a default value for
-fno-inline.

I would suggest to drop the option name from the text describing
the default, and also replace value with setting (it's really not
a value).  It could be as simple as:

  -finline

  Default setting.

Alternatively, to preserve the connection to the alternate setting:

  -finline

  Default setting; overrides -fno-inline.

At some point we talked about also making attributes hyperlinks
(like always_inline and noinline above) but I don't remember
the conclusion.  Are you planning to do that?  (Would handling
it as part of the transition be easier than doing it later?)

Martin

Re: Benefits of using Sphinx documentation format

[Eli Zaretskii via Gcc]

> From: Jonathan Wakely 
> Date: Mon, 12 Jul 2021 18:15:26 +0100
> Cc: Matthias Kretz , "gcc@gcc.gnu.org" 
> 
> > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that
> > list.  However, his message didn't get through to the list, for some
> > reason.
> 
> It did:
> https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html
> https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html

That's not the message I was talking about.  Gavin sent another, which
didn't get posted.

Re: Benefits of using Sphinx documentation format

[Jonathan Wakely via Gcc]

On Mon, 12 Jul 2021 at 18:24, Eli Zaretskii wrote:
>
> > From: Jonathan Wakely 
> > Date: Mon, 12 Jul 2021 18:15:26 +0100
> > Cc: Matthias Kretz , "gcc@gcc.gnu.org" 
> >
> > > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that
> > > list.  However, his message didn't get through to the list, for some
> > > reason.
> >
> > It did:
> > https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html
> > https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html
>
> That's not the message I was talking about.  Gavin sent another, which
> didn't get posted.

Ah, then he'll have to try resending it. There's nothing to "release",
if the mail didn't get through then it's gone, not in a mod queue.

Re: Benefits of using Sphinx documentation format

[Gavin Smith via Gcc]

(Sending mail again, without attachments this time in the hope it gets through.)

I had the discussion about moving documentation of gcc from Sphinx to
Texinfo brought to my attention.

https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html

Speaking as the Texinfo maintainer, I hope to add my views and
understandings of things to this discussion to improve your
understanding of the facts and possibilities, although of course it's
up to you whether you use Texinfo or not.

I will work through the points made in that email but haven't read any
of the subsequent discussion yet - I'll follow up on anything else
afterwards.

> Benefits:
> 1) modern looking HTML output (before: [1], after: [2]):

>a) syntax highlighting for examples (code, shell commands, etc.)

Syntax highlighting has been achieved with Texinfo before. See

https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html

and

https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg4.html

With Texinfo 6.8, syntax highlighting in multiple languages is easier
to achieve by giving an argument to the @example command
(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040example.html).
This puts a class attribute on the HTML element which can then be
picked up by a post-processor. It might also be possible to achieve
syntax highlighting with a customization file used by the Texinfo
tools themselves: see
https://lists.gnu.org/archive/html/bug-texinfo/2021-01/msg00031.html.

>b) precise anchors, the current Texinfo anchors are not displayed (start 
> with first line of an option)
>c) one can easily copy a link to an anchor (displayed as ¶)

Similar anchors were implemented in Texinfo 6.8. See
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html
and hover any of the options there with your mouse; you will see the
pilcrow sign appear.

>e) left menu navigation provides better orientation in the manual

Left menu navigation is possible with the new JavaScript interface, in
Texinfo 6.8. There is still a demo at

https://per.bothner.com/tmp/Kawa-txjs-plain/Community.html

and

https://per.bothner.com/tmp/Kawa-txjs/Community.html

However, I would say that it isn't necessarily always an improvement,
if it is going to be buggy. When I click on the link
https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing
the browser doesn't scroll the sidebar so to show the active ToC entry
(although it
is displayed correctly when I refresh the page).

The more sophisticated the HTML/JS becomes the more likely there are
these little nits.

>f) Sphinx provides internal search capability: [3]

There is a global search facility with the JavaScript interface
although different to that provided by Sphinx, only showing one match
at a time.

Try

https://per.bothner.com/tmp/Kawa-txjs/index.html

and then press "s" on your keyboard, type in your search string (e.g.
"composable") and it will search through the manual for that string.
To go to the next match, press "s" then Return.

The proviso about "sophisticated" HTML still applies here, though.

> 2) internal links are also provided in PDF version of the manual

Links already work when viewing a PDF on a computer.

If you want to add additional links that only appear in PDF and HTML
and not in Info, this is easily achieved with a conditional macro,
like

@ifset morelinks
@macro link{arg}
@ref{\arg\}
@end macro
@end ifset
@ifclear morelinks
@macro link{arg}
\arg\
@end macro
@end ifclear

followed by "@set morelinks" or "@clear morelinks" as required.

> 5) Sphinx is using RST which is quite minimal semantic markup language

This is really an ineffable question of taste on which it is hard to
be convinced, but I have to point out that Texinfo is minimalistic,
with only three special characters (@, { and }).

> 6) TOC is automatically generated - no nee6d for manual navigation like seen 
> here: [5]
> 5] @comment node-name, next,  previous, up
> @nodeInstalling GCC, Binaries, , Top

This is a completely bogus point with these explicit "pointers" being
optional. I couldn't find out easily how long ago these pointers
became optional, but it is at least twenty years ago.

A couple of other points, not mentioned in the original email:
* One possible disadvantage of moving away from Texinfo which might be
easily missed is support for reliable web links between different
manuals. If you change format you should make sure that these work,
e.g. if you reference the glibc manual the web link to that should
work correctly (as well as the link working in the Info format).
* A disadvantage of focusing on HTML output is that locally installed
documentation gets sidelined: although locally installed HTML
documentation is possible, it tends not to happen and people refer to
the web version instead, with all of its disadvantages (slow speed,
may be the wrong ver

Re: Benefits of using Sphinx documentation format

[Koning, Paul via Gcc]

> On Jul 12, 2021, at 12:36 PM, David Malcolm via Gcc-patches 
>  wrote:
> 
> On Mon, 2021-07-12 at 15:25 +0200, Martin Liška wrote:
>> ...
> 
> I think the output formats we need to support are:
> - HTML
> - PDF
> - man page (hardly "modern", but still used)

Also info format (for the Emacs info reader).  And ebook formats (epub and/or 
mobi).  Having good quality ebook output is a major benefit in my view; it 
would be very good for the standard makefiles to offer make targets for these 
formats.

paul

Re: Priority of builtins expansion strategies

[Alexandre Oliva]

On Jul 12, 2021, Christoph Müllner  wrote:

> * Why does the generic by-pieces infrastructure have a higher priority
> than the target-specific expansion via INSNs like setmem?

by-pieces was not affected by the recent change, and IMHO it generally
makes sense for it to have priority over setmem.  It generates only
straigh-line code for constant-sized blocks.  Even if you can beat that
with some machine-specific logic, you'll probably end up generating
equivalent code at least in some cases, and then, you probably want to
carefully tune the settings that select one or the other, or disable
by-pieces altogether.


by-multiple-pieces, OTOH, is likely to be beaten by machine-specific
looping constructs, if any are available, so setmem takes precedence.

My testing involved bringing it ahead of the insns, to exercise the code
more thoroughly even on x86*, but the submitted patch only used
by-multiple-pieces as a fallback.

> * And if there are no particular reasons, would it be acceptable to
> change the order?

I suppose moving insns ahead of by-pieces might break careful tuning of
multiple platforms, so I'd rather we did not make that change.

-- 
Alexandre Oliva, happy hackerhttps://FSFLA.org/blogs/lxo/
   Free Software Activist   GNU Toolchain Engineer
Disinformation flourishes because many people care deeply about injustice
but very few check the facts.  Ask me about 

Re: Benefits of using Sphinx documentation format

[Richard Biener via Gcc]

On Mon, Jul 12, 2021 at 7:20 PM Jonathan Wakely via Gcc  wrote:
>
> On Mon, 12 Jul 2021 at 18:04, Eli Zaretskii via Gcc  wrote:
> >
> > > From: Matthias Kretz 
> > > Date: Mon, 12 Jul 2021 16:54:50 +0200
> > >
> > > On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote:
> > > > On 7/12/21 4:12 PM, Eli Zaretskii wrote:
> > > > > I get it that you dislike the HTML produced by Texinfo, but without
> > > > > some examples of such bad HTML it is impossible to know what exactly
> > > > > do you dislike and why.
> > >
> > > I believe Martin made a really good list.
> >
> > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that
> > list.  However, his message didn't get through to the list, for some
> > reason.
>
> It did:
> https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html
> https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html
>
> The HTML attachment has been stripped though. The relevant part of the
> HTML looks like this:
>
>  id='index-_002d_002dgreeting'>--greeting=text href='#index-_002d_002dgreeting' class='copiable-anchor'>
> ¶
> -g text
> 
> Output text instead of the default greeting.
> 
> 
>
> Note the  ¶  anchor that is part of the  element,
> not the  (where the index-__002d anchor is still located).
>
>
> >  Can someone please see why, and release his message?  I think
> > he makes some important points, and his message does deserve being
> > posted and read as part of this discussion.
>
> He shows that some of the linking issues are addressed in the latest
> texinfo release, which is great. But it doesn't negate all Martin's
> other points.
>
> GCC devs and users who frequently modify or refer to the HTML docs
> want to replace texinfo. One vocal objector who just keeps repeating
> that texinfo is fine should not block that progress.

You mean one very vocal and one active developers want to replace it?
I actually like texinfo (well, because I know it somewhat, compare to sphinx).
I think it produces quite decent PDF manuals.  I never use the html
output (in fact I read our manual using grep & vim in the original
.texi form ...).

But then I'm mostly of the who-does-the-work-decides attitude - so if there
are people driving a transition to sphinx because they want to improve sth
and they don't manage to do that with texinfo (for whatever reason) then OK.
As long as it doesn't regress my personal usecase (I hope the sphinx
docs are still
digestable in source form, which I understand they are).

Just I really suggest to not claim its texinfos fault.  It's likely
not.  It's likely
the fault of GCCs manual being "old" and hasn't catched up with new
texinfo features.  And where texinfo has bugs they likely can be fixed.

Just my (final) 2c to this discussion.

Richard.