Re: Benefits of using Sphinx documentation format
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
(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
Copiable anchor links in gcc manual
(Please CC bug-texi...@gnu.org in replies to this email.) The current gcc web documentation (for gcc 12.1, released May 2022) doesn't include copiable hyperlinks for some parts of the manual, as the manual was generated with an older version of Texinfo, 6.5: https://gcc.gnu.org/onlinedocs/gcc-12.1.0/gcc/Overall-Options.html#Overall-Options It was also the case for some other versions that I checked, such as gcc 10.4 (released 28th June, 2022). People were asking for links in the Texinfo HTML manual that could be copied to use as links to parts of manuals. See e.g. https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg0.html https://gcc.gnu.org/pipermail/gcc/2021-July/236740.html https://gcc.gnu.org/pipermail/gcc/2021-July/236745.html This was implemented in Texinfo 6.8, released 3rd July, 2021. See for example any of the options listed on this page: https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html Hovering over the options should make a ¶ sign appear which can be copied to give a link. Is there anybody who can regenerate the gcc manuals with Texinfo 6.8 and upload the results to the website (and/or inform me of any issues or possible improvements)? I'm hoping we can get a new Texinfo release made in the next month or two and any issues with this feature would be top agenda. I'm not subscribed to the gcc list so if this message doesn't get through there, would any of the recipients be able to forward this message to the interested people?
Re: Makeinfo generates wrong link
On Sun, Oct 02, 2022 at 09:06:06PM -0400, Richard Stallman wrote:
> generates the following output:
>
> Some macros are predefined on each kind of machine
> (see href="https://gcc.gnu.org/onlinedocs/gcc/System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros";>System-specific
> Predefined Macros in Using the GNU Compiler
> Collection). This allows you to provide code specially tuned for a
> particular machine.
>
> but that link is broken. The OP suggests this link
>
> https://gcc.gnu.org/onlinedocs/gcc-4.8.5/cpp/System-specific-Predefined-Macros.html
>
> may be correct.
>
> Where do those directory names come from? Is there a table in makeinfo
> that needs to be updated?
It comes from the htmlxref.cnf file. (It may be installed under
/usr/share/texinfo/.) The link produced above matches the
current entry for the "gcc" manual in that file.
Changing that file would change the link, e.g.
--- a/util/htmlxref.cnf
+++ b/util/htmlxref.cnf
@@ -340,7 +340,7 @@ gcalmono${GS}/gcal/manual/gcal.html
gcal node${GS}/gcal/manual/html_node/
GCC = https://gcc.gnu.org/onlinedocs
-gccnode${GCC}/gcc/
+gccnode${GCC}/gcc-4.8.5/
cpp node${GCC}/cpp/
gfortran node${GCC}/gfortran/
gnat_rm node${GCC}/gnat_rm/
However, it's wrong to make it link to a specific version.
The gcc developers need to provide a stable, version-independent link
for the manual. This link would have worked in the past, but I don't
know how recently it broke.
I'm attempting to CC the gcc mailing list stated on their documentation page
to see if anyone there can give any information.
Re: Makeinfo generates wrong link
On Mon, Oct 03, 2022 at 08:31:06AM +0100, Jonathan Wakely wrote:
> On Mon, 3 Oct 2022 at 07:01, Gavin Smith via Gcc wrote:
> >
> > On Sun, Oct 02, 2022 at 09:06:06PM -0400, Richard Stallman wrote:
> > > generates the following output:
> > >
> > > Some macros are predefined on each kind of machine
> > > (see > > href="https://gcc.gnu.org/onlinedocs/gcc/System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros";>System-specific
> > > Predefined Macros in Using the GNU Compiler
> > > Collection). This allows you to provide code specially tuned
> > > for a
> > > particular machine.
> > >
> > > but that link is broken. The OP suggests this link
> > >
> > > https://gcc.gnu.org/onlinedocs/gcc-4.8.5/cpp/System-specific-Predefined-Macros.html
> > >
> > > may be correct.
> > >
> > > Where do those directory names come from? Is there a table in makeinfo
> > > that needs to be updated?
> > The gcc developers need to provide a stable, version-independent link
> > for the manual. This link would have worked in the past, but I don't
> > know how recently it broke.
>
> The URL
> https://gcc.gnu.org/onlinedocs/cpp/System-specific-Predefined-Macros.html
> has been stable for many years.
In that case it is the input that is wrong:
Some macros are predefined on each kind of machine
(@pxref{System-specific Predefined Macros, System-specific Predefined
Macros, System-specific Predefined Macros, gcc, Using the GNU Compiler
Collection}). This allows you to provide code specially tuned for a
particular machine.
It should be
Some macros are predefined on each kind of machine
(@pxref{System specific Predefined Macros, System specific Predefined
Macros, System-specific Predefined Macros, gcc, Using the GNU Compiler
Collection}). This allows you to provide code specially tuned for a
particular machine.
changing the hyphen to a space in "System specific".
Re: Makeinfo generates wrong link
On Tue, Oct 04, 2022 at 01:39:04PM -0400, Richard Stallman wrote: > [[[ To any NSA and FBI agents reading my email: please consider]]] > [[[ whether defending the US Constitution against all enemies, ]]] > [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > > > There is one additional error here if the above-mentioned URL is > > correct: the reference should point to the (cpp) manual instead of the > > (gcc) manual. > > What is the full, formal tit;e of the CPP manual? Texinfo cross-references > need to specify that, as well as the short name for Info. The PDF on their website is titled, simply, "The C Preprocessor". https://gcc.gnu.org/onlinedocs/cpp.pdf
